Allright Ladies and Gentlemen, here goes the results :-) ACCEPTED: 1. Contributing Guidelines with hints for Reviewers. 2. PR and GIT COMMITS must adhere to Contributing Guidelines or rejected. 3. Git commit messages as important as PR description. 4. Proper description details requirements. 5. PR must adhere to description requirements. 6. Git commit message must adhere to description requirements. 7. Git commit message mandatory fields (topic, desctiption, signature). 9. Zero trust approach to user testing. 11. Respect long term maintenance and self-compatibility. 13. Breaking changes build and runtime test logs are mandatory. 14. Minimum code reviews. 17. Merge rules. 18. PR as small as possible.
REJECTED: 8. Changes must come with documentation. 10. Breaking changes not welcome. 16. Self company commit/review/merge not allowed 19. Lazy Consensus. INCOMPLETE: 12. Breaking changes handling process. 15. Reviews independence. Please verify the answers, it took me ~3h of manual responses processing ;-) I will next prepare a PR draft with updated guidelines for final polishing and review. In addition to points Accepted I will also add points Rejected/Incomplete marked for discussion and hopefully we will reach the agreement on independence, breaking changes, quality, trust, compatibility, and maintenance. Thanks! :-) Tomek ### 1. Contributing Guidelines with hints for Reviewers. We are adding additional section for Reviewers to Contributing Guidelines in order to provide checklist and complementary set of rules that should filter out breaking code as much as possible also on our side. +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 TimK +1 Lup / PMC +1 Filipe +1 Sebastien +1 Nathan / PMC +1 Dmitri +1 Matteo +1 Roberto +1 Alan / PMC +1 TimH Result: PASSED / +1: 13 (6 binding), 0: 0, -1: 0. Remarks: TimH: +1 to all - on the basis that if this doesn't work out quite right it will be reviewed and changed. Best to try something like this than not - it will become clear very soon if something isn't working as intended! ### 2. PR and GIT COMMITS must adhere to Contributing Guidelines or rejected. Each PR and GIT COMMIT **must** adhere to requirements presented in Contributing Guidelines or will be auto-rejected until fixed / updated. Both code authors and reviewers/committers must follow the rules. Special cases are defined in a separate dedicated rules. +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo +1 Roberto +1 Alan +1 TimH Result: PASSED / +1: 13 (6 binding), 0: 0, -1: 0. Remarks: none. ### 3. Git commit messages as important as PR description. Git commit messages are as important as PR descriptions. These provide in-code descriptions of each change and are git interface independent. +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo +1 Roberto +1 Alan +1 TimH Result: PASSED / +1: 13 (6 binding), 0: 0, -1: 0. Remarks: none. ### 4. Proper description details requirements. Proper description of change is mandatory. Description must contain explanation on what proposed change do, why it is necessary, what if fixes, and how things are changed / fixed / updated, what is the impact (build / runtime / api / what area), how it was tested. Local code build and real world hardware runtime test logs must be provided (for code related changes). Description can be single..several sentences long or bullet points but enough for anyone to understand change goals and details. Usually it will look similar for PR and git commit message. +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo +1 Roberto +1 Alan +1 TimH Result: PASSED / +1: 13 (6 binding), 0: 0, -1: 0. Remarks: Tomek: +1, However I understand this PR template is separate from the rule and will be updated / voted independently. TimK: +1, Better to have the 'Motivation/Background' section, while simplifying the rest. In my view, commit messages should address the 'What', whereas PR documents should elaborate more on the 'Why'. ### 5. PR must adhere to description requirements. Proper description in PR according to template is mandatory, fill in all required fields or change is auto-rejected until fixed / updated. For code changes build and runtime logs are mandatory to prove code was tested on at least one real world hardware. +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo +1 Roberto +1 Alan +1 TimH Result: PASSED / +1: 13 (6 binding), 0: 0, -1: 0. Remarks: This point was mostly missing in the answers but no 0 or -1 reported so assuming +1, as voted before, and the template example is taken from existing Guidelines, will discuss the PR. PR TEMPLATE / EXAMPLE: Summary 1. Why change is necessary (fix, update, new feature)? 2. What functional part of the code is being changed? 3. How does the change exactly work (what will change and how)? 4. Related NuttX Issue reference if applicable. 5. Related NuttX Apps Issue / Pull Request reference if applicable. 6. Related NuttX Documentation Pull Request reference if applicable. Impact 1. New feature added? Existing feature changed? 2. User (will user need to adapt to change)? NO / YES (please describe if yes). 3. Build (will build process change)? NO / YES (please descibe if yes). 4. Hardware (will arch(s) / board(s) / driver(s) change)? NO / YES (please describe if yes). 5. Documentation (is update required / provided)? NO / YES (please describe if yes). 6. Security (any sort of implications)? NO / YES (please describe if yes). 7. Compatibility (backward/forward/interoperability)? NO / YES (please describe if yes). 8. Anything else to consider? Testing 1. I confirm that changes are verified on local setup and works as intended NO / YES. 2. Build Host(s): OS (Linux,BSD,macOS,Windows,..), CPU(Intel,AMD,ARM), compiler(GCC,CLANG,version), etc. Target(s): arch(sim,RISC-V,ARM,..), board:config, etc. 3. Testing logs before change: runtime / build logs before change goes here 4.Testing logs after change: runtime / build logs after change goes here 5. (optional) How to repeat. You can also provide steps on how to reproduce problem and verify the change if not obvious from test logs. Optional PR remarks: 1. This PR introduces only one functional change. 2. I have updated all required description fields above. 3. My PR adheres to Contributing Guidelines and Documentation (git commit message, coding standard, testing etc). 4. My PR is still work in progress (not ready for review). 5. My PR is ready for review and can be safely merged into a codebase. ### 6. Git commit message must adhere to description requirements. Proper GIT COMMIT message according to template is mandatory, or change is rejected until fixed / updates. Build and runtime logs are optional here if these are too long and already provided in PR. Git commit message consists of: 1. Topic with functional name prefix, ":" mark, and short self-explanatory context. 2. Blank line 3. Description on what is changed, how, and why. May use several lines, short sentences, or bullet points. 4. Blank line. 5. Signature (created with `git commit -s`). GIT COMMIT TEMPLATE / EXAMPLE: net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc. Add g_ prefix to can_dlc_to_len and len_to_can_dlc to follow NuttX coding style conventions for global symbols, improving code readability and maintainability. * you can also use bullet points. * to note different thing briefly. +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo +1 Roberto +1 Alan +1 TimH Result: PASSED / +1: 13 (6 binding), 0: 0, -1: 0. Remarks: TimK: +1, Regarding the commit message header, I recommend using the style adopted by the Angular Community, which is widely accepted. <type>(<scope>): <short summary> Filipe: +1, Let's make sure we have example for this on docs and also on PR bot). ### 7. Git commit message mandatory fields (topic, desctiption, signature). Each git commit message must consist of topic, description, and signature (git commit -s), as presented in GIT COMMIT TEMPLATE, which are mandatory, or change is auto-rejected until fixed / updated. +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo +1 Roberto +1 Alan +1 TimH Result: PASSED / +1: 13 (6 binding), 0: 0, -1: 0. Remarks: none. ### 8. Changes must come with documentation. Changes must come with with documentation update where applicable. For maintenance reasons code and documentation should be split into two separate PR with the same name marked [1/2 CODE] for code and [2/2 DOC] for documentation. If change presents new functionality a documentation must be provided along with the code (not in future). If change requires documentation update it must be contained along with the code (not in future). Successful documentation build log shortcut is welcome. See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md 0: Tomek / PMC 0 Alin / PMC 0 Tiago / PMC -1 TimK 0 Lup / PMC -1 Filipe -1 Sebastien -1 Nathan / PMC 0 Dmitri -1 Matteo 0 Roberto +1 Alan / PMC +1 TimH Result: REJECTED / +1: 2 (1 binding), 0: 6 (4 binding), -1: 5 (1 binding). Remarks: Tomek: 0, Having documentation in a single PR (same pr separate commit is easier to perform and review, otherwise we may get out of code/doc sync? But if this is the only way and better for release manager then okay. Alin: 0, Having documentation in a single PR (same pr separate commit is easier to perform and review. The release process can use it. Tiago: 0, Yes, documentation should be provided, but I don't see any reason for splitting it into two different PRs. We keep our documentation in the same repository and - for the sake of traceability - it should be updated in the same PR (separate commit, not PR). We should make reviewers' and committers lives easier. Alternative writing would be: "Changes must come with a documentation update where applicable. For maintenance reasons, code and documentation should be split into two commits in the same PR. If change presents new functionality documentation must be provided along with the code (not in the future). If change requires a documentation update it must be contained along with the code (not in the future)." TimK: -1, I'd like say "should" instead of "must". Lup: 0, It depends? Smaller PRs can include a Doc Commit. When I add a new Arch + Board (e.g. StarPro64), the PR will include a link to my article that explains the new code. Then I prepare another PR for the User Docs. Filipe: -1, Don't see any problem in having documentation on same PR, in fact I think it makes things easier. Sebastien: -1, separate commits in same pr. Nathan: -1, : Similar to others' comments. Also, could be same PR but separate commits? Matteo: -1, : Documentation should be required, in the same PR as the change. No separate PRs. PROPOSED UPDATED TEXT: Changes must come with a documentation update where applicable. For maintenance reasons, code and documentation should be split into two commits in the same PR. If change presents new functionality documentation must be provided along with the code (not in the future). If change requires a documentation update it must be contained along with the code (not in the future). Successful documentation build log shortcut is welcome. See: 1. https://github.com/apache/nuttx/tree/master/Documentation 2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md <--- Quick note from Tomek: TimK the word "must" is used on purpose to improve documentation that is usually skipped, and complemented "where applicable" :-) ### 9. Zero trust approach to user testing. We implement zero trust approach to user provided testing. It is the commit author duty to provide real world hardware build and runtime logs for at least one device. Remember that any code change may break things for others, please avoid that. See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 TimK +1 Lup / PMC +1 Filipe +1 Sebastien +1 Nathan / PMC +1 Dmitri +1 Matteo +1 Roberto 0 Alan / PMC +1 TimH Result: PASSED / +1: 12 (5 binding), 0: 1 (1 binding), -1: 0. Remarks: Alan: 0, We cannot transfer this responsibility to the developer, he should test it in the HW he has, but we need to have better HW coverage to avoid issues. ### 10. Breaking changes not welcome. Breaking changes are not welcome. We do not "break by design". When unavoidable breaking changes need prior discussion and agreement of the community (see Breaking Changes handling rule). This is anything that alters Build / Kernel / Architecture / API, alters both nuttx and nuttx-apps repo at the same time, breaks build/runtime/api for single or many boards/architectures/applications, breaks self-compatibility, breaks build/runtime compatibility with existing release code (packages) both for nuttx and nuttx-apps, etc. Because thousands of users / companies and their projects / products depend on NuttX code, we strongly prefer self-compatibility and long-term maintenance over "change is good" ideologies. Any code change may impact other users and their business, please keep that in mind. See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 TimK +1 Lup / PMC +1 Filipe +1 Sebastien +1 Nathan / PMC +1 Dmitri 0 Matteo +1 Roberto -1 Alan / PMC +1 TimH Result: REJECTED / +1: 11 (5 binding), 0: 1 , -1: 1 (1 binding). Remarks: Alan: -1, Breaking are necessary sometimes, saying "Breaking changes are not welcome" will make people afraid of contributing innovation that breaks existing APIs. <--- Quick note from Tomek: Alan please re-read that point, it was updated not to scare people except people that want to break the code on purpose, a dedicated section is mentioned and created for breaking changes after last round. The whole point of this voting is to avoid breaking changes that impact self-compatibility and long term maintenance. It is again blocked without preferred text alternative. You gave -1 answer then 0 and asked to use the first form, correct? ### 11. Respect long term maintenance and self-compatibility We respect long term maintenance and self-compatibility is our ultimate goal. Alternative solutions and non-invasive approaches are preferred that offers user a choice and compatibility. Breaking changes are avoided, and planned towards next major release, see Breaking Changes rule. Experimental code that does not impact overall project self-compatibility in terms of Breaking Changes should be clearly marked [EXPERIMENTAL]. See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 TimK +1 Lup / PMC +1 Filipe +1 Sebastien +1 Nathan / PMC +1 Dmitri +1 Matteo 0 Roberto 0 Alan / PMC +1 TimH Result: PASSED / +1: 11 (5 binding), 0: 2 (1 binding), -1: 0. Remarks: none. ### 12. Breaking changes handling process. This rule complements "Breaking changes not welcome" rules. We avoid breaking changes unless absolutely necessary and unavoidable (i.e. security fix, broken code, etc), then special case considerations may apply: 1. First reviewer that recognizes a breaking change should block accidental merge with "Request Changes" mark and ask for discussion. 2. PR is marked as "Draft" to avoid accidental merge. 3. Detailed discussion should follow both in PR AND dev@ Mailing List. 4. Alternative non-breaking alternative solution is researched with help of the community. 5. Breaking change after discussion / updates is voted on the mailing list, requires at least 4 +1 binding votes and single -1 binding vote blocks the change (binding vote means PMC member). 6. Breaking changes **must** be verified on various different real world hardware architectures, build and runtime logs are **mandatory**, help of the community is desired. 7. Breaking change requires at least 4 independent organizations positive PR reviews. 8. Change must be well documented (buid/runtime test logs, pr, git commit, documentation, release notes, etc). 9. Change must be clearly marked with [BREAKING] mark (pr, git commit, release notes, etc). See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 Lup / PMC .. <- votes lost here 0 Roberto -1 Alan / PMC +1 TimH Result: REJECTED / INCOMPLETE / +1: 5 (4 binding), 0: 1, -1: (1 binding). Remarks: Alan: -1, Mostly a repetition of 10 mixed with 9 and 11. <--- Quick note from Tomek: Alan, this procedure is dedicated for handling breaking changes. If rejecting please provide alternative expected text. ### 13. Breaking changes build and runtime test logs are mandatory. Breaking changes are special case where build and runtime test logs (i.e. apps/ostest) from more than one different architecture is **mandatory** . QEmu tests does not count here as it passed breaking change that did not work on a real hardware. Community support is desired. See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo 0 Roberto 0 Alan +1 TimH Result: PASSED / +1: 11 (5 binding), 0: 2 (1 binding), -1: 0. Remarks: Sebastien: +1, Also some mandatory documentation on how to fix the build after the breaking change. rust has cargo fix. Python has 2to3. Alan: 0, All the changes need to be equally coveraged, not only those that break some existing code ### 14. Minimum code reviews. Each PR requires at least 2 independent positive reviews, except Breaking Changes where at least 4 positive independent organizations reviews, are required before merge to the upstream. +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC -1 TimK +1 Lup / PMC +1 Filipe +1 Sebastien 0 Nathan / PMC 0 Dmitri +1 Matteo +1 Roberto +1 Alan / PMC +1 TimH Result: PASSED / +1: 10 (5 binding), 0: 2 (1 binding), -1: 1. Remarks: Tomek: +1, Although I think 3 should be default to increase cross-checks. Alin: +1, minimum 3. Tiago: +1, I still prefer Nathan's proposal of creating "areas". Documentation and experimental features shouldn't require 2 reviewers. For the sake of simplicity, this rule works. Even 2 reviewers for documentation and experimental features are too restrictive. TimK: -1, "at least 2 independent positive reviews", may be too high bar we set. Nathan: 0, Tiago summarized my proposal above. However, I am OK with whatever the community decides on this. Matteo: +1, Agree that pure documentation changes can have 1 reviewer. <--- Quick note from Tomek: We currently require 2 independent reviewers right now for all changes, when breaking changes are reported or discovered then 4 reviewers are required. Its not a big change but simple and should prevent breaking changes. Nathan's proposal is good and desired, we will for sure make it in another step. ### 15. Reviews independence. PR Reviews should come from independent organizations. Each PMC Member, Committer, and Reviewer must report up-to-date Affiliation for clear identification. When code comes from the same organization as positive review, then at least one independent review is necessary (except Breaking Changes). Self review is not allowed. See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 TimK +1 Lup / PMC +1 Filipe -1 Sebastien ?? Nathan / PMC 0 Dmitri +1 Matteo +1 Roberto 0 Alan / PMC +1 TimH Result: INCOMPLETE / +1: 9 (4 binding), 0: 2 (1 binding), -1: 1. Remarks: Sebastien: -1, No. Reviewers must not be from same organization as coder. Otherwise there is no independence. Nathan: ??, Reviews from same organization are nice to have, but shouldn't count toward number of reviews needed. <--- Quick note from Tomek: This is why I preferred online testing solution because there _must_ be a valid vote cast, also proposed alternative text was required ;-) This point goal was to solve single company pr/review/merge. Please provide alternative text that you expect! :-) ### 16. Self company commit/review/merge not allowed Single company commit, review, merge is not allowed. Each PMC Member, Committer, and Reviewer must report up-to-date Affiliation for clear identification. See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 TimK +1 Lup / PMC +1 Filipe 0 Sebastien +1 Nathan / PMC 0 Dmitri +1 Matteo +1 Roberto -1 Alan / PMC +1 TimH Result: REJECTED / +1: 10 (5 binding), 0: 2, -1: 1 (1 binding). Remarks: Alan: -1, People in big companies could work in different areas or be physically distant of the author of PR, and sometimes someone in the company knows more about that subject than some "independent" reviewer. <--- Quick note from Tomek: This point 16 can be merged with 15. Again the goal was to get independent reviews. Please provide full alternative text in comments. ### 17. Merge rules. Each change **must** be provided as PR that undergoes independent review process. Self committed code merge with or without review is not allowed, just as direct push to master, and will be punished. +1 Tomek +1 Alin +1 Tiago +1 TimK +1 Lup +1 Filipe +1 Sebastien +1 Nathan +1 Dmitri +1 Matteo +1 Roberto 0 Alan / PMC +1 TimH Result: PASSED / +1: 12 (5 binding), 0: 1 (1 binding), -1: 0. Remarks: TimK: +1, However, I would prefer the maintainer to perform a 'squash merge' by default. In the case of a significant or breaking PR change, we could consider a 'rebase merge'. On a second thought, why does GitHub provide the 'Squash' option? Nathan: +1, We should guard our master branches from direct pushes. See https://github.com/apache/infrastructure-asfyaml?tab=readme-ov-file#branchpro <--- Quick note from Tomek: Nathan totally true, and all discussions must be resolved before merge is possible, not sure why its not here, could you please take a look and fix on all repos please? ### 18. PR as small as possible. 1. Pull Requests should be as small as possible and focused on only one functional change. 2. Different functional changes must be provided in separate Pull Requests. 3. PR may contain several commits but every single commit included must not break break overall build, runtime, and compatibility, especially for other components. 4. PR that breaks build or runtime anyhow is considered a Breaking Change, is not welcome and requires special considerations (see Breaking Changes rule). 5. PR that introduces a new feature must have Documentation included in separate commit. 6. When changes for dedicated function must be bundled together in order to maintain functionality and self-compatibility, exception can be made, and this must be clearly stated there is no other way and this is not a Breaking Change. +1 Tomek / PMC +1 Alin / PMC +1 Tiago / PMC +1 TimK +1 Lup / PMC +1 Filipe +1 Sebastien +1 Nathan / PMC +1 Dmitri -1 Matteo +1 Roberto +1 Alan / PMC +1 TimH Result: PASSED / +1: 12 (6 binding), 0:0, -1:1. Remarks: Filipe: +1, item 5 clashes with voting item 8 discussion. Sebastien: +1, I'm ok with a single PR that contains separate commits for code and doc. Matteo: -1, #5 PR with new features should not require docs in a separate commit. It's difficult to make changes based on review and still keep the two commits (code and docs) separate when squashing. One commit for both should be fine. <--- Quick note from Tomek: Filipe / Matteo I think you talk about two PR not commits? We will update documentation requirement to be along the code in a single PR but separate commits (like it is right now). ### 19. Lazy Consensus. A PR may be *eligible* to be merged under the concept of *Lazy consensus* with the following conditions: 1. It affects only a single chip or board (no kernel/libs/upper-half drivers etc). 2. It implements a new feature (or app) that doesn't introduce any breaking changes or backward incompatibility. 3. It didn't get the minimum reviewers after two weeks. 4. At least one independent reviewer reviewed it. 5. It adheres to all other Contributing Guide requirements conditions. The PR's author should: 1. After a week without any reviewers, send an e-mail to the mailing list asking for more people to review it. 2. Explain why the PR can't be split into smaller PRs (if applicable). 3. After two weeks ask for the independent reviewer to merge if there are no other reviews. The independent reviewer is responsible for checking if the PR matches the *Lazy Consensus* conditions before merging it. -1 Tomek / PMC -1 Alin / PMC -1 Tiago / PMC 0 TimK 0 Lup / PMC 0 Filipe -1 Sebastien -1 Nathan / PMC 0 Dmitri -1 Matteo +1 Roberto +1 Alan / PMC +1 TimH Result: REJECTED / +1: 3 (1 binding), 0: 4 (1 binding), -1: 6 (4 binding). Remarks: Tomek: -1, Considering we are leaving 2 reviewers as is (increased to 4 for breaking changes), lazy consensus may undermine quality, I think this point is not required anymore :-) Alin: -1, We risk critical bugs or harmful code to slip as lazy consensus. Tiago: -1, For the sake of simplicity, let's adopt rule 14 only and re-evaluate in the future. Lup: 0, I don't think this is priority right now? We can tweak the guideline later. Sebastien: -1, NERVER EVER let untrusted and unverified code in without a review even if the process is slowed down. If developer WANTS his code merged the burden is on them to get other reviewers involved so merge becomes possible. Nathan: -1, I think I suggested Lazy Consensus initially, but after reading the discussions and comments about this, I think it is better to let PR authors to request reviews and keep their PR alive. Alan: +1, Why to increase from 1 week to 2 weeks? -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
NuttX-20250222-ContributingGuidelinesUpdate-Voting-Round2-Answers.xlsx
Description: MS-Excel 2007 spreadsheet