From 58b11f629f5e18df1b18bf4498f33a26f2b9c5e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pablo=20Correa=20G=C3=B3mez?= <ablocorrea@hotmail.com> Date: Thu, 21 Nov 2024 20:03:17 +0100 Subject: [PATCH] 0001-pmcr-process Tweaked-by: Oliver Smith <ollieparanoid@postmarketos.org> --- .gitlab/issue_templates/idea.md | 4 +- 0000-template.md | 23 +++-- 0001-pmcr-process.md | 73 +++++++++++++++ README.md | 152 ++++++++++++++++++-------------- 4 files changed, 174 insertions(+), 78 deletions(-) create mode 100644 0001-pmcr-process.md diff --git a/.gitlab/issue_templates/idea.md b/.gitlab/issue_templates/idea.md index bab84f9..44046ee 100644 --- a/.gitlab/issue_templates/idea.md +++ b/.gitlab/issue_templates/idea.md @@ -1,7 +1,7 @@ <!-- -This template should be used for proposing a new RFC idea, discussing it and +This template should be used for proposing a new PMCR idea, discussing it and potentially finding collaborators to work on a merge request (the eventual -RFC). +PMCR). --> # Idea: diff --git a/0000-template.md b/0000-template.md index 598209d..3ca46b0 100644 --- a/0000-template.md +++ b/0000-template.md @@ -1,8 +1,8 @@ ## REPLACE-ME: Title * Date proposed: yyyy-mm-dd -* RFC ID: https://gitlab.postmarketos.org/postmarketOS/rfcs/-/merge_requests/ID - **update this number after RFC merge request has been filed!** +* PMCR ID: https://gitlab.postmarketos.org/postmarketOS/pmcr/-/merge_requests/ID + **update this number after PMCR merge request has been filed!** ## Summary @@ -11,7 +11,7 @@ extended ## Motivation -REPLACE-ME: Explain the rationale that has motivated the creation of this RFC. If applies, +REPLACE-ME: Explain the rationale that has motivated the creation of this PMCR. If applies, also provide use-cases. ## Consequences @@ -31,15 +31,14 @@ Think about: ## Draft implementation plan -REPLACE-ME: Most RFCs require of some implementation. It could be a technical -implementation, like the coding and packaging work needed to get systemd into -postmarketOS. But it could also be things like documenting a new process on the -website, or changing permissions to certain users. +REPLACE-ME: After approval, executing most PMCRs will require of some +implementation. It could be a technical implementation, like the coding and +packaging work needed to get systemd into postmarketOS. But it could also be +things like documenting a new process on the website, or changing permissions +to certain users. REPLACE-ME: This section aims to make the proposer *think* about how the -proposal can be implemented. It does not require a complete or detailed -plan of every task that needs to be executed. An example in the context of the -gitlab migration: +proposal can be implemented. An example in the context of the gitlab migration: 1. Identify every place in gitlab.com/postmarketOS where gitlab.com is hard-coded @@ -61,11 +60,11 @@ manager? If deemed appropriate, you might request funding from postmarketOS to execute it. postmarketOS can either approve it, reject it, or work with you on a grant -application for the implementation team +application for the implementation team. ### Blocking issues -Sometimes plans require further work. Either other RFCs, or implementations +Sometimes plans require further work. Either other PMCRs, or implementations in other parts of the ecosystem, like Alpine. If deemed appropriate, you might also request funding for this. diff --git a/0001-pmcr-process.md b/0001-pmcr-process.md new file mode 100644 index 0000000..907cf80 --- /dev/null +++ b/0001-pmcr-process.md @@ -0,0 +1,73 @@ +## Establish a Change Request process + +* Date proposed: 2024-11-21 +* PMCR ID: https://gitlab.postmarketos.org/postmarketOS/pmcr/-/merge_requests/1 + +## Summary + +Big changes to postmarketOS should not only be posted in an issue in +https://gitlab.postmarketos.org/postmarketOS/postmarketOS, but actually follow +a process that encourages the people proposing it to think about a plan and +the consequences of the change. + +## Motivation + +We have bumped into the problem that big changes in postmarketOS sometimes +lack structure. Though there have been announcements for most of them, the +timeline and consequences have not always been clear, leading to breakage +for developers and users. There has also been sometimes problems with +transparency and communication of decisions on big changes. This PMCR process +aims to solve those issues by providing a structure for people to think about +such changes, and share them with others. + +## Consequences + +Establishing this PMCR can have the following advantages: + +* Provide a mental model around which people can think about consequences and + planning for big changes, so that they are better planned, and cause less + fallout +* Ensure that big changes are discussed by the community and the members of the + team, establishing an atmosphere of transparency and trust where decisions can + be traced back in time. +* Have a single source of truth for past decisions. This can avoid having to + rationalize again and again. It will also help not having to fetch those + rationales from old blog posts. +* Allow people outside the postmarketOS team to propose breaking ideas that + might improve postmarketOS overall. Those people are currently oftentimes + left out of the decision-making process, or don't have a proper way to + express themselves. +* Ensure that we have a place to point to people that want big changes to be + incorporated. + +Unfortunately, any process has its disadvantages too: + +* Potentially delay the implementation of big features. +* Make the process of implementing big features more bureaucratic. One cannot + anymore just think about something, do it, and push it. It needs to go through + a process, which means it might at some point derail. It requires a non-zero + amount of energy. Any ideas to reduce the bureaucratic impact of this PMCR + process are welcomed. +* It might take a while to get into this, and fine-tune rules of things that + need an PMCR from things that don't. It might cause some confusion. + +## Draft implementation plan + +1. Gather feedback on the documentation written in this repository, and bikeshed + wording until people are satisfied. +2. Approve it. Being the first PMCR, this will require consensus within the Core + Contributors. This should be done via gitlab approvals once all discussion + threads are resolved. As part of those discussion, a voting process is + established and documented in the README of the project. +3. Inform about the new PMCR process in the blog, amend documentation as + needed, and start using it! + +### The proposer + +Myself, a member of the postmarketOS Core Contributors. However, this can be +considered a proposal from the whole team, as it was decided in the meeting +[2024-11-11](https://wiki.postmarketos.org/wiki/Core_Contributors_Meetings#2024-11-11_(CC_+_TC)). + +### Blocking issues + +None! diff --git a/README.md b/README.md index a6423c5..885b54b 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,141 @@ -postmarketOS Request for Comments -================================= +postmarketOS Change Request (PMCR) +================================== -A Request for Comments ([RFC](https://en.wikipedia.org/wiki/Request_for_Comments)) -is a way for postmarketOS contributors to propose, design and discuss new -features and changes in project direction in a focused environment. +A postmarketOS Change Request (PMCR) is an +[RFC](https://en.wikipedia.org/wiki/Request_for_Comments) process for +postmarketOS contributors to propose, design and discuss new features and +changes in project direction in a focused environment. -RFCs start as merge requests in: -https://gitlab.postmarketos.org/postmarketOS/rfc/-/merge_requests +PMCRs start as merge requests in: +https://gitlab.postmarketos.org/postmarketOS/pmcr/-/merge_requests -## What does an RFC do? +## What does a PMCR do? -The RFC process is intended to bring focus and structure to discussions of +The PMCR process is intended to bring focus and structure to discussions of important changes and new features. It provides a space for sharing and collaborating on ideas and design documents, keeping community discussion organized and focused on the goal of reaching a decision. -Visibility and inclusivity are important values for RFCs. They are advertised -in out monthly blog posts, and are followed by the team. +Visibility and inclusivity are important values for PMCRs. They are advertised +in our monthly blog posts, and are followed by the team. -An RFC is only a design document, and not a single line of code needs to be +A PMCR is only a design document, and not a single line of code needs to be written for the discussion to be approved, although prototyping can be a good idea. -## When should I file an RFC? +## When should I file a PMCR? -If you have an idea for something and are unsure if it needs an RFC, the best +If you have an idea for something and are unsure if it needs a PMCR, the best way to find out is to just ask (e.g. by opening -[an issue](https://gitlab.postmarketos.org/postmarketOS/rfc/-/issues/new) and filling out -the "idea" template. - -RFCs are used for proposing "substantial" changes. The meaning of "substantial" -is subjective, but a good start would be anything that benefits from design -discussion. Put a different way, it is recommended to file an RFC if the design -or implementation is not immediately clear, or if there are drawbacks or -potential consequences that require discussion first. Examples of things that -can benefit from such processes: - -- Moving to a new git forge, or gitlab instance -- Big pmbootstrap or pmaports refactorings that have the potential to break - devices -- Changing the permission structure of the project, to give more people rights -- Adding systemd -- Working on an immutable version of postmarketOS -- Adding the Trusted Contributor program -- Other remarkable organizational or governance changes, like big changes to - the RFC process itself - -## Who can file an RFC? - -Anyone can file an RFC. Please make sure that you have discussed it with some -people, or opened an issue to discuss before doing so. This will greatly -increase the changes for it to succeed. This can also help gauge early support -for the feature and work out any obvious issues or design decisions. +[an issue](https://gitlab.postmarketos.org/postmarketOS/pmcr/-/issues/new) and +filling out the "idea" template. + +PMCRs are used for proposing "substantial" changes. The meaning of "substantial" +is subjective and evolves based on community norms. However, there are some +basic rules that can help understanding what needs a PMCR: + +* Big pmbootstrap or pmaports refactorings that require user action and will + otherwise leave devices unbootable for multiple devices (5+) from different + families (3+ SoCs). +* Adding new flavors or ways to distribute postmarketOS. Examples include adding + an immutable or a systemd version. +* Changes in the Governance structure that have an impact on all members with + rights in the project. Like adding the Trusted Contributor program, or + splitting power across committees. +* Remarkable changes to the PMCR process itself. +* Infrastructure changes that require manual actions to be taken from everybody + contributing to postmarketOS. + +Most changes do *not* require a PMCR: + +* Adding new ways to install a small group of devices, or devices within the + same SoC, even if requiring user action. +* Changing supported kernels for some devices. +* Massive rebuild of kernels or device packages in pmaports, due to a change in + features or policy. Such as adding new options to kconfigcheck, or changing the + location of deviceinfo. +* Big pmbootstrap refactorings that are transparent to the developers. + +## Who can file a PMCR? + +Anyone can file a PMCR. We encourage everybody that has big ideas for changes to postmarketOS to open -RFCs. Even if you have not figured out all the details on how to fill an RFC, -it is welcomed. RFCs are specifically designed for feedback to be gathered, and +PMCRs. Even if you have not figured out all the details on how to fill a PMCR, +it is welcomed. PMCRs are specifically designed for feedback to be gathered, and we expect changes to happen between proposal and approval. People interested -can help you get an RFC to the finish line. We will rather have some RFCs +can help you get a PMCR to the finish line. We will rather have some PMCRs opened and waiting for being developed, or politely closed due to requiring more work, than leave great ideas in the drawer because people not feeling entitled to propose changes. -## Proposing an RFC +It might help you shorten the process if you have shared and discussed your idea +with more people. That can also help gauge early support for the feature and +work out any obvious issues or design decisions. This is, however, not a +requirement. -### Step 0: Check previously proposed RFCs and issues +## Proposing a PMCR + +### Step 0: Check previously proposed PMCRs and issues It might be that the idea has already been proposed in the form of an issue, -or there is a previous RFC that is being worked on or was closed. Give those +or there is a previous PMCR that is being worked on or was closed. Give those previous attempts a read. Contribute to them if they are being worked on, -or take feedback with you if you are doing a new attempt +or take feedback with you if you are doing a new attempt. -### Step 1: Prepare the RFC +### Step 1: Prepare the PMCR For this repository, and copy `0000-template.md` to `0000-<my-proposal-title>.md` and fill in as many details as you can. Do not hesitate to talk with other postmarketOS users and community members about it, show it to them and integrate feedback. -### Step 2: File the RFC +### Step 2: File the PMCR Once everything is ready, and you want to announce it and official feedback, check the -[list of MRs](https://gitlab.postmarketos.org/postmarketOS/rfc/-/merge_requests?scope=all&state=all) +[list of MRs](https://gitlab.postmarketos.org/postmarketOS/pmcr/-/merge_requests?scope=all&state=all) and get the last number in there. Move the `0000-<my-proposal-title>.md` to -`<last-mr-number-+1>-<my-proposal-title>.md`. Push an open an MR! Ping any -community members that might be interested or have collaborated with you -in the ellaboration of the RFC. If the RFC might have some remarkable impact, +`<last-mr-number-+1>-<my-proposal-title>.md`. Create a new merge request! Ping +any community members that might be interested or have collaborated with you +in the ellaboration of the PMCR. If the PMCR might have some remarkable impact, please also queue a comment to add it to the monthly blog posts, by commenting on the [corresponding issue](https://gitlab.postmarketos.org/postmarketOS/postmarketos.org/-/issues/?label_name%5B%5D=monthly-blog-post). -## Discussing an RFC +## Discussing a PMCR -Discussion about the RFC should happen on the RFC merge request. Any discussions +Discussion about the PMCR should happen in the PMCR merge request. Any discussions that happen outside it should be summarized or linked to by the authors. -The RFC will likely undergo numerous revisions in the discussion process, and +The PMCR will likely undergo numerous revisions in the discussion process, and some might take time for it gain traction. Often big changes require some time for people to make up their minds and nicely collaborate. -We encourage everybody taking part in the RFC discussion process to work towards -reaching a conclusion in a constructive manner. When you make a post to the RFC -thread, focus on the contents and implications of the RFC only. While +We encourage everybody taking part in the PMCR discussion process to work towards +reaching a conclusion in a constructive manner. When you make a post to the PMCR +thread, focus on the contents and implications of the PMCR only. While disagreeing, please always keep in mind the examples of [positive behavior](https://postmarketos.org/coc/#our-standards) in the Code of Conduct, and try to work towards them. -## Finalizing an RFC +## Finalizing a PMCR -The author(s) or the postmarketOS team might come to the conclusion that the RFC -is in no need of more discussion. If the RFC has no blocking issues, or those +The author(s) or the postmarketOS team might come to the conclusion that the PMCR +needs no more discussion. If the PMCR has no blocking issues, or those are deemed to be short-term resolvable, either the authors or any member of the postmarketOS team may request a vote to take place. -The ???? will vote by approving the MR during a 1-week period. Once a majority -of the members is reached, the RFC will be passed and merged. +At this point, and when the PMCR requires implementation, the PMCR must contain a +draft implementation plan that can be translated into a high-level planning +issue. It is also necessary to have a person responsible for the implementation +towards the Core Contributors. This way there is some warranty that PMCRs will be +executed. + +During +[Core Contributors' Meetings](https://wiki.postmarketos.org/wiki/Core_Contributors_Meetings), +the Core Contributors will vote on approving or rejecting the PMCR. There will +be one vote per contributor, and a majority of 60% is needed to either approve, +or reject the PMCR. Decisions need a quorum of more than half of the members. If +there is a tie, it might be indicative that the PMCR requires further discussion, +and should be sent back to the author(s) to iterate based on feedback. The +results and reasoning will be published on a comment in the Merge Request. -- GitLab