Please find the form answers below. I think it is better if everybody forwards the form to the mailing list, this way it will be easier to review and re-count the votes.
BR, Alan ---------- Forwarded message --------- From: Google Forms <forms-receipts-nore...@google.com> Date: Mon, Feb 24, 2025 at 12:20 PM Subject: NuttX Contributing Guidelines update 202502 To: <acas...@gmail.com> [image: Google Forms] Thanks for filling out NuttX Contributing Guidelines update 202502 <https://docs.google.com/forms/d/e/1FAIpQLScQaGjMCkhysm_zvNIrlxOqxhwfNLL8Z-UwsrZIwKzjUJ4aiw/viewform?usp=mail_form_link>Here's what was received. Edit response <https://docs.google.com/forms/d/e/1FAIpQLScQaGjMCkhysm_zvNIrlxOqxhwfNLL8Z-UwsrZIwKzjUJ4aiw/viewform?edit2=2_ABaOnufXDZKuDVFPEm9T2p_x6CLF9Dh1UdKJbMt0MDcuL5IqaiTMTB5lIbysBjnbhRD47Q4> NuttX Contributing Guidelines update 202502 VOTE 20250222: ROUND 2. Full set of questions with updates after discussion. If you see better way of texting, especially if you vote 0 or -1, please fill in the preferred text for the rule along with explanation why. Voting will close on 20250228 with results presentation to the mailing list. Thank you for your time and vote :-) Email * acas...@gmail.com 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 0 -1 Requirement 1 text suggestion + explanation. 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 0 -1 Requirement 2 text suggestion + explanation. 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 0 -1 Requirement 3 text suggestion + explanation. 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 0 -1 Requirement 4 text suggestion + explanation. 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. 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. +1 0 -1 Requirement 5 text suggestion + explanation. 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. Signed-off-by: AuthorName <Valid@EmailAddress> +1 0 -1 Requirement 6 text suggestion + explanation. 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 0 -1 Requirement 7 text suggestion + explanation. 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 +1 0 -1 Requirement 8 text suggestion + explanation. 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 0 -1 Requirement 9 test suggestion + explanation. 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 0 -1 Requirement 10 test suggestion + explanation. Breaking are necessary sometimes, saying "Breaking changes are not welcome" will make people afraid of contributing innovation that breaks existing APIs 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 0 -1 Requirement 11 text suggestion + explanation. 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 0 -1 Requirement 12 text suggestion + explanation. Mostly a repetition of 10 mixed with 9 and 11 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 0 -1 Requirement 13 text suggestion + explanation. 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 0 -1 Requirement 14 text suggestion + explanation. 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 0 -1 Requirement 15 text suggestion + explanation. 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 0 -1 Requirement 16 text suggestion + explanation. 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 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 0 -1 Requirement 7 text suggestion + explanation. 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 0 -1 Requirement 18 text suggestion + explanation. 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 0 -1 Requirement 19 text suggestion + explanation. Why to increase from 1 week to 2 weeks? Create your own Google Form <https://docs.google.com/forms?usp=mail_form_link> Does this form look suspicious? Report <https://docs.google.com/forms/u/0/d/e/1FAIpQLScQaGjMCkhysm_zvNIrlxOqxhwfNLL8Z-UwsrZIwKzjUJ4aiw/reportabuse?source=https://docs.google.com/forms/d/e/1FAIpQLScQaGjMCkhysm_zvNIrlxOqxhwfNLL8Z-UwsrZIwKzjUJ4aiw/viewform&usp=mail_receipt_abuse>
