Propose "why" folder that we will keep as "advisors" knowledge base I would like to propose the "why" folder, where we will keep a (very) short summary about some of the rules and policies that we will be - as Advisors - discussing with the projects we will advise. I think we need something like that - also as a place where we - advisors - will be able to update and exchange our understanding on why there are certain rules and policies. Also to discuss future variations and changes to those rules, possibly resulting from interactions with multiple PMCs when we will learn from them how they are applying certain rules and policies in their environment. I gave an example of how I see such "why" captured information could look like - starting with the most familiar (for me) release process and I am curious what others think about it.
diff --git a/wg-advisors/red-flags.md b/wg-advisors/red-flags.md index ff2b7a9..d437edd 100644 --- a/wg-advisors/red-flags.md +++ b/wg-advisors/red-flags.md
@@ -14,8 +14,8 @@ * Is having online meetings that are not brought back to the mailing list. * Has a website external to apache.org * Is missing reports -* Is missing release votes -* Has too many release candidates +* Is missing release votes: [why release process](why/why_release_process.md) +* Has too many release candidates: [why engage community](why/why_release_process.md) * Has author tags in the code * Discussions are happening off-list. * Too much talk is happening on the private list. @@ -24,7 +24,7 @@ * There are many GitHub or version control notifications on the mailing list. * Building the project is challenging. * Getting the LICENSE and NOTICE correct is difficult. -* The PMC is making releases without voting on them. +* The PMC is making releases without voting on them: [why release process](why/why_release_process.md) * The PMC members are not looking after the project's name and brand. * No PMC members have been elected for a while * No committers have been elected for a while. @@ -32,7 +32,7 @@ * PMC members are not signed up to the private mailing list. * The project has a benevolent dictator. * A single company is controlling the direction of the project. -* Releases are not being placed in the ASF distribution system. +* Releases are not being placed in the ASF distribution system: [why release process](why/why_release_process.md) * The project is voting on too many things. * PMC members have a conflict of interest. * Conversations on the mailing list mainly occur in a language other than English.
diff --git a/wg-advisors/why/README.md b/wg-advisors/why/README.md new file mode 100644 index 0000000..8599926 --- /dev/null +++ b/wg-advisors/why/README.md
@@ -0,0 +1,41 @@ +# Why this folder? + +In ASF we have a number of rules, processes, policies which we follow that has been established over the +years. They are documented in various places and are not always easy to find. This folder is intended to +be a place where we can collect and curate these documents, and make them more easily accessible to +people who needs them among the advisors, but also to grab the current understanding on why we are doing +it in the first place, whether the policy is optional or mandatory, and what the consequences are if projects +don't follow them. In some cases we might introduce variations of the policies, or best practices, that +might depend on the size of the projects, stage they are in, stakeholder engagement and so on. + +# Where the idea for the folder comes from? + +This folder content is inspired by Architecture Decision Records (ADRs) which is a way to capture +short and comprehensive documents that describe a design decision, the context of the decision, and the +consequences of the decision. The idea is to have a record of the motivations behind the decision, and +the trade-offs that were considered. Similarly, we think that it is good to capture here the motivations +behind the policies, the trade-offs that were considered, and the consequences of the decision in ways +that are not documented in the policies, but are part of the understanding of the community, and sometimes +tribal knowledge. The idea behind keeping it here is to make it easier for the advisors to find the +information they need, and to make it easier to update the information when common understanding changes or +is better understood. + +# What is in the content? + +Those documents are not meant to copy the rules and policies. They are merely here to provide Advisor related +context, so that new advisors can understand the background and the reasoning behind the rules and policies +more easily but also to prevent advisors form spreading [cargo cult](https://en.wikipedia.org/wiki/Cargo_cult) +understanding of the rules and policies. We want to keep the following information in the documents in +similar chapters, to make it easier to build similar understanding of the rules and policies + +* Rule or policy +* Very brief summary +* Links to relevant documents +* Why are we doing it? +* Is it mandatory and what are conditions? +* Are there variations for different projects? + + + + +
diff --git a/wg-advisors/why/why_release_process.md b/wg-advisors/why/why_release_process.md new file mode 100644 index 0000000..335447f --- /dev/null +++ b/wg-advisors/why/why_release_process.md
@@ -0,0 +1,55 @@ +# Release process + +## Summary + +ASF project release software following a well defined process involving PMC members voting on release +candidates, publishing the artifacts in the ASF distribution system, and announcing the release to the +community. + +## Links to relevant documents + +* [Release Policy](https://www.apache.org/dev/release.html) +* [Release Distribution Policy](https://www.apache.org/dev/release-distribution.html) + +## Why are we doing it? + +We are doing it because this is what the ASF is doing. ASF delivers "Software for the public good" +and the act of releasing software is a key part of that. The process is designed to ensure that the +software is properly vetted and that the community is aware of the release and that the process of +releasing software is transparent, open and secure. + +Releasing the software is a Legal Act of the Foundation and it has consequences for the Foundation +as software released by the Foundation is the main way the Foundation interacts with the public +and can be hold accountable for the software it releases. + +Following the release process also provides Legal protection for the PMC and the release manager. + +The release process is also aimed at ensuring that the software is properly vetted and tested and +that the development community is aware of the release and has had a chance to review and test the +release candidate. This is why it is an important aspect of the community building process to +engage the community in the release process and encourage them to vote as well. + +## Is it mandatory and what are conditions? + +The process is mandatory for all ASF projects. + +## Are there variations for different projects? + +There are certain variations of the process that the PMC can adopt, but they should +all be documented, and might involve the need of super-majority voting, release manager +casting and implicit +1, but there are few non-negotiable elements in the process (those +are mainly because of the legal protection they provide). + +* PMC members must verify the release candidate for their provenance (licences, signatures, + checksums, where applicable build reproducibility), and content (sources) +* At least three PMC members must vote +1 for the release candidate + +There are many ways how the PMC can engage the community in the release and testing process +and the PMC should be encouraged to do so, some of the important aspects is to guide the community +what is changed in the upcoming release so that they can test what is changing, as well as +individually involving and engaging contributors who actually contributed to the release. + +What also helps is to not to have too many release candidates, as any new candidate involves +a new round of voting and testing, so release manager should be encouraged to decide on +cancelling release candidates after giving sufficient time for the community to test +and flag potential issues.