You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by "cederom (via GitHub)" <gi...@apache.org> on 2025/03/07 05:30:03 UTC
[PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
cederom opened a new pull request, #15950:
URL: https://github.com/apache/nuttx/pull/15950
* This comes from vast mailing list discussions on breaking changes, code quality, long term self-compatibility and maintenance, etc.
* Rules are based on mailing list discussion and votes.
* I tried to put this as human friendly as possible.
* I tried to consider all remarks and propositions.
* TODO points need verification.
* All suggestions are welcome! :-)
NOTE: FOR NOW THIS IS ONLY A PR REVIEW DRAFT!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1985112373
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
@jerpelea @tmedicci I agree that is is nice to have documentation in a separated commit, but this should be suggested as good practice, but as an enforced rule. Because even projects like Linux doesn't enforce it. Never be "plus royaliste que le roi"! ;-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "hartmannathan (via GitHub)" <gi...@apache.org>.
hartmannathan commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1993351458
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,445 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so first.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various projects and products around
+the world. Remember that any code change may affect different users and their
+businesses. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us process your contributions smoothly, it is very important that you
+follow the guidelines. NuttX is maintained by a small team of volunteers from
+around the world. These rules are based on daily experiences and help us
+to preserve long term self-compatibility and maintenance of the project.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+The rules presented are here to ensure high qualiy code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
Review Comment:
```suggestion
standardized pull requests processing, as well as long term self-compatibility
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,445 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so first.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various projects and products around
+the world. Remember that any code change may affect different users and their
+businesses. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us process your contributions smoothly, it is very important that you
+follow the guidelines. NuttX is maintained by a small team of volunteers from
+around the world. These rules are based on daily experiences and help us
+to preserve long term self-compatibility and maintenance of the project.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+The rules presented are here to ensure high qualiy code and documentation,
Review Comment:
```suggestion
The rules presented are here to ensure high quality code and documentation,
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1984705688
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
Review Comment:
```suggestion
all rules apply equally to all authors, reviewers, committers and maintainters.
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
Review Comment:
```suggestion
The rules presented are here to ensure high quality code and documentation,
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
Review Comment:
```suggestion
To help us process your contributions smoothly, it is very important that you
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
@cederom I suggest remove this requirement, as I shown other project doesn't require it and even Linux that @jerpelea said requires it I looked the git history and them don't have this requirement.
@raiden00pl @xiaoxiang781216 @hartmannathan for awareness
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
Review Comment:
```suggestion
us to preserve long term self-compatibility and maintenance of the project.
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
Review Comment:
```suggestion
4. Different logical functions changes must be provided in a separate Pull Requests.
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
Review Comment:
```suggestion
must not break overall build, runtime, and compatibility,
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "simbit18 (via GitHub)" <gi...@apache.org>.
simbit18 commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2717269405
Question for old PR before this Guidelines update.
For abandoned and very old PR, how will they be handled?
List filters -> **is:pr is:open created:<2024-01-01 state:open**
https://github.com/apache/nuttx/pulls?q=is%3Apr+is%3Aopen+created%3A%3C2024-01-01+state%3Aopen+
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "tmedicci (via GitHub)" <gi...@apache.org>.
tmedicci commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1985041064
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
The proposed rule reflects exactly what we've been doing for a while (same PR, separate commits). About adding it to the same (or to an individual commit), well, there is always that "gold" rule that each commit should aggregate the minimum buildable code necessary to it. That being said, this rule adheres to it: documentation is not mandatory to make the "code" buildable and should be split into different commits.
The same is valid for arch and board support: when a new feature is added, it might not be mandatory to have arch and board-code in the same commit (the arch code is buildable by itself). They can be split into different commits (in the same PR!). Documentation would be the third commit. Reverting it requires reverting all commits in the same PR.
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 2. PR is marked as "Draft" to avoid accidental merge.
+ 3. Detailed discussion should follow both in PR **and** dev@ Mailing List.
Review Comment:
Should we provide a reference for it?
```suggestion
3. Detailed discussion should follow both in PR **and** [dev@ Mailing List](https://nuttx.apache.org/community/#mailing-list).
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1985112373
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
@jerpelea @tmedicci I agree that is is nice to have documentation in a separated commit, but this should be suggested as good practice, but not as an enforced rule. Because even projects like Linux doesn't enforce it. Never be "plus royaliste que le roi"! ;-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986505410
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
> It is advised that the code and documentation should be split into two
> separate commits in the same PR. This helps backporting and separates
> possible code and documentation build errors. Squashing code together with
> documentation into a single commit should be avoided, but is acceptable.
How about this one? We may prefer to have doc and code commits separate but accept code+doc commits too? :-)
The revert argument is valid, although we use PR revert over github, but code PR may be reverted on nuttx-apps and skipped on nuttx where documentation resides, true. This is why having good PR descriptions is so important.
I can also understand the backporting argument.. but when the code is backported along with the documentation it should be also okay?
I also updated these two points (added "in the same PR"):
> If change presents new functionality documentation **must** be provided
> in the same PR along with the code (not in the future).
>
> If change requires existing documentation update it must be contained
> in the same PR along with the code change (not in the future).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986513102
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
Review Comment:
I know this sounds harsh, but its to clearly underline our approach to breaking changes, these are not welcome :-)
What others think? :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986511929
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
Review Comment:
"Changes affecting different functionalities must be provided in a separate Pull Requests." ? :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "xiaoxiang781216 (via GitHub)" <gi...@apache.org>.
xiaoxiang781216 commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1984718391
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
All related change should come in one patch to avoiding the mismatch.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2715255266
> > @cederom: Thank you folks for all the remarks and grammar suggestions! The update is pushed, please comment :-)
>
> @tmedicci: Just re-reviewed: we are fine here. Can you mark the PR as ready-to-review, @cederom please?
Done :-)
Please add more comments or resolve remaining discussions if all is fine folks :-)
Thanks!! :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "hartmannathan (via GitHub)" <gi...@apache.org>.
hartmannathan commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1993350373
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
Review Comment:
We could link to the NuttX Community page of the project website, which has mailing lists, social media, etc., and let the reader decide which to use... https://nuttx.apache.org/community/ We can leave it as is for now...
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "simbit18 (via GitHub)" <gi...@apache.org>.
simbit18 commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2720575953
Hi @cederom I was referring to
Is a Pull Request open forever ? (PR is like diamonds !!! ) :)
Post **Always Be Closing...Pull Requests**
https://www.hanselman.com/blog/always-be-closingpull-requests
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986514754
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
Review Comment:
Yeah, that would save a lot of CI resources.. for each PR update the process is restarted and executed in full length.. maybe after first update it can be switched to manual launch mode? Maybe only syntax check on drafts? Maybe Draft by default or based on the PR template checkbox? What do you think @lupyuen ? :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "raiden00pl (via GitHub)" <gi...@apache.org>.
raiden00pl commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1985131205
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
There is a difference between adding something new to the documentation and updating the documentation according to changes made to the code. I don't see a problem with a separate commit for doc in the first case, but in the second case this seems strange. Documentation describes the code, if the code changes then the documentation should also be changed otherwise the doc doesn't describe the current code state.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "lupyuen (via GitHub)" <gi...@apache.org>.
lupyuen commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986521272
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
Review Comment:
Sorry I don't think GitHub Actions will allow us to trigger the CI Workflow when we switch from Draft Mode to Ready For Review. [(According to the docs)](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters)
@simbit18 Would you know if this is possible?
Actually I think it's kinda helpful for CI Workflow to run on Draft PRs. This procedure might be better for PR Review:
1. NuttX Dev submits a PR in Draft Mode
2. Wait for CI Workflow to Complete, fix any CI Errors
3. NuttX Dev sets PR to Ready for Review
4. NuttX Admins will review the PR
5. In case of fixes: NuttX Dev will revert PR to Draft Mode, wait for CI Workflow to complete, set to Ready For Review
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2709289490
> @tmedicci: Just to make sure: this file is not rendered into the documentation at https://nuttx.apache.org/docs/latest/index.html, right?
>
> Still pending adding the same info at https://nuttx.apache.org/docs/latest/contributing/index.html (maybe creating a new page)
Yes, this is only the `nuttx/CONTRIBUTING.md` file update for now, but its formatting makes it possible to attach to the Documentation too, I can do that after we sort get the final form and commit :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1984713697
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
@cederom I suggest removing this requirement, as I have shown other project doesn't require it and even Linux that @jerpelea said requires it I looked the git history and them don't have this requirement.
@raiden00pl @xiaoxiang781216 @hartmannathan for awareness
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "hartmannathan (via GitHub)" <gi...@apache.org>.
hartmannathan commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1985116317
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
Review Comment:
This is a good sentence, but I think it might need to move to elsewhere in the document, because it doesn't quite fit with the flow of this part of the text.
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
Review Comment:
```suggestion
businesses. Please try to keep your contributions high quality and compatible.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
Review Comment:
Should we direct questions to the (archived) mailing list?
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or several sentences long or bullet points
+but enough for anyone to understand change goals and details.
Review Comment:
```suggestion
but must be enough for anyone to understand change goals and details.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
Review Comment:
```suggestion
Note that our small team of maintainers is processing hundreds of PRs every month.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
Review Comment:
(I wonder whether draft PRs can be excluded from CI until marked as ready for review?)
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 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 solution is researched along 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 welcome.
+ 7. Breaking change requires at least 4 independent positive PR reviews
+ (see 1.16), all discussions resolved, and zero "request changes".
+ 8. Change must be well documented (buid / runtime test logs, pr, git
+ commit, documentation, release notes, etc) with clear notes on how to
+ fix the introduced problems.
+ 9. Breaking Change must be clearly marked with a `[BREAKING]` tag in the
+ git commit topic and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.14. Breaking changes build and runtime test logs are mandatory.
+
+Breaking changes are special case where build and runtime test logs
+(i.e. `apps/ostest`) for **more than one** different architecture is
+**mandatory**. Community support is welcome.
+
+QEmu tests does not count here as in the past it did not catch problems
Review Comment:
```suggestion
QEmu tests **do not count** here as in the past they did not catch problems
```
(Also I'm unsure of QEmu; I have always seen it stylized as QEMU before.)
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 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 solution is researched along 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 welcome.
+ 7. Breaking change requires at least 4 independent positive PR reviews
+ (see 1.16), all discussions resolved, and zero "request changes".
+ 8. Change must be well documented (buid / runtime test logs, pr, git
+ commit, documentation, release notes, etc) with clear notes on how to
+ fix the introduced problems.
+ 9. Breaking Change must be clearly marked with a `[BREAKING]` tag in the
+ git commit topic and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.14. Breaking changes build and runtime test logs are mandatory.
+
+Breaking changes are special case where build and runtime test logs
+(i.e. `apps/ostest`) for **more than one** different architecture is
+**mandatory**. Community support is welcome.
+
+QEmu tests does not count here as in the past it did not catch problems
+that revealed on a real world hardware after change was already merged.
+
+Although this seems to repeat rule 1.13, it ensures real world hardware
+verification and minimizes possible negative impact on various users.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.15. Reviews reuqirements.
+
+Before PR can be merged to the master repository it requires:
+
+ * 2 or more independent positive reviews.
+ * 4 or more independent positive reviews for Breaking Changes (see 1.12).
+
+In future we plan to add "areas" (such as trivial typo fixes or documentation
+only updates) that may require only one reviewer.
+
+
+### 1.16. Reviews independence.
+
+PR reviews should come from independent organizations.
+NuttX is an Open-Source independent and unbiased project.
+
+Each PMC Member, Committer, and Reviewer must report up-to-date Affiliation
+for clear identification. Commits should contain business email where
+applicable.
+
+When code comes from the same organization as positive review, then review
+is not considered independent, but still may provide helpful insight.
+
+Self review is not allowed.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.17. Merge rules.
+
+1. Each change **must** be provided as PR that undergoes independent review
+ process (see 1.16).
+2. Single company / organization commit, review, and merge is not allowed.
+3. Merge of PRs with unresolved discussions and "change request" marks
+ is not allowed.
+3. Self committed code merge with or without review is not allowed.
+4. Direct push to master is not allowed.
+
+Breaking these rules will be punished.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+
+
+## 2. Contribution Templates.
+
+### 2.1. Source Code.
+
+Your source code **must** conform to the [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+
+Code is automatically checked for each PR (and PR updates) by GitHub Continuous
+Integration (CI) system. Fails at `lint/*` step indicate code style errors.
+
+You may verify the code styling issues with:
+
+ 1. `./tools/checkpatch.sh -g HEAD~...HEAD`
+ 2. `./tools/checkpatch.sh -f path/to/your/file.c`
+
+Note that we require you to solve encountered issues and adapt all modified
+files even if you did not introduce the problem yourself. This way, every
+contribution gets us closer to compliance. Thank you!
+
+
+### 2.2. Commits.
+
+This template provides git commit example as described in requirement 1.5.
+
+```
+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 <Va...@EmailAddress>
+```
+
+Note that first line of the commit message (topic) will be automatically
+used as pull request title and the rest is added as description.
+Use it as a starting point to describe your Pull-Request (PR).
+
+
+### 2.3. Pull Requests.
+
+This template uses MarkDown and provides example Pull Request content
+as described in requirement 1.7.
+
+````
+## Summary
* Why change is necessary (fix, update, new feature)?
* What functional part of the code is being changed?
* How does the change exactly work (what will change and how)?
* Related [NuttX Issue](https://github.com/apache/nuttx/issues) reference if applicable.
* Related NuttX Apps [Issue](https://github.com/apache/nuttx-apps/issues) / [Pull Request](https://github.com/apache/nuttx-apps/pulls) reference if applicable.
-#### Impact
+## Impact
- * Is new feature added? Is existing feature changed?
+ * Is new feature added? Is existing feature changed? NO / YES (please describe if yes).
* Impact on user (will user need to adapt to change)? NO / YES (please describe if yes).
* Impact on build (will build process change)? NO / YES (please descibe if yes).
* Impact on hardware (will arch(s) / board(s) / driver(s) change)? NO / YES (please describe if yes).
* Impact on documentation (is update required / provided)? NO / YES (please describe if yes).
* Impact on security (any sort of implications)? NO / YES (please describe if yes).
* Impact on compatibility (backward/forward/interoperability)? NO / YES (please describe if yes).
- * Anything else to consider?
+ * Anything else to consider or add?
-#### Testing
+## Testing
I confirm that changes are verified on local setup and works as intended:
* 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.
+ * you can also provide steps on how to reproduce problem and verify the change.
Review Comment:
```suggestion
* you can also provide steps on how to reproduce the problem and verify the change.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
Review Comment:
```suggestion
please do so first.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
Review Comment:
```suggestion
follow the guidelines. These rules are based on daily experiences and help
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
Review Comment:
```suggestion
and 1600+ configurations, that are used in various projects and products around
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
Review Comment:
```suggestion
Also, we filter out breaking changes and handle them accordingly.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
Review Comment:
```suggestion
6. PR that breaks build or runtime in any way is considered a Breaking Change
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or several sentences long or bullet points
Review Comment:
```suggestion
Description can be a single sentence, several sentences long, or bullet points
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
Review Comment:
```suggestion
* dependencies (if change depends on other changes).
```
or
```suggestion
* dependencies (if change depends on another change).
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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.
Review Comment:
```suggestion
* to note different things briefly.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
Review Comment:
I don't know about "is not welcome"; how about "requires a discussion and vote of the PMC on the mailing list; see section such-and-such..."
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
Review Comment:
```suggestion
4. Different logical changes must be provided in a separate Pull Requests.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
Review Comment:
```suggestion
until fixed. Special cases are possible and outlined in dedicated rules.
```
or
```suggestion
until fixed. Special cases are possible and outlined in a separate section of dedicated rules.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
Review Comment:
```suggestion
be made, and it must be clearly stated that there is no other way and
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
Review Comment:
```suggestion
We implement zero trust approach to user-provided testing.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
Review Comment:
```suggestion
It is the change author's duty to provide real world hardware build and runtime
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
Review Comment:
```suggestion
Remember that any code change may impact other users and their businesses!
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
Review Comment:
```suggestion
Alternative solutions and non-invasive approaches are preferred. Offer
user a choice and compatibility instead of breaking existing features.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
Review Comment:
```suggestion
Remember that any code change may break things for others. Please do your utmost to avoid that.
```
(We can't always avoid mistakes, but we should ask people to do their due diligence.)
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
Review Comment:
```suggestion
Experimental code and incomplete or experimental features that do not impact
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 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 solution is researched along 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 welcome.
+ 7. Breaking change requires at least 4 independent positive PR reviews
+ (see 1.16), all discussions resolved, and zero "request changes".
+ 8. Change must be well documented (buid / runtime test logs, pr, git
+ commit, documentation, release notes, etc) with clear notes on how to
+ fix the introduced problems.
+ 9. Breaking Change must be clearly marked with a `[BREAKING]` tag in the
+ git commit topic and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.14. Breaking changes build and runtime test logs are mandatory.
+
+Breaking changes are special case where build and runtime test logs
+(i.e. `apps/ostest`) for **more than one** different architecture is
+**mandatory**. Community support is welcome.
+
+QEmu tests does not count here as in the past it did not catch problems
+that revealed on a real world hardware after change was already merged.
+
+Although this seems to repeat rule 1.13, it ensures real world hardware
+verification and minimizes possible negative impact on various users.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.15. Reviews reuqirements.
+
+Before PR can be merged to the master repository it requires:
+
+ * 2 or more independent positive reviews.
+ * 4 or more independent positive reviews for Breaking Changes (see 1.12).
+
+In future we plan to add "areas" (such as trivial typo fixes or documentation
+only updates) that may require only one reviewer.
+
+
+### 1.16. Reviews independence.
+
+PR reviews should come from independent organizations.
+NuttX is an Open-Source independent and unbiased project.
+
+Each PMC Member, Committer, and Reviewer must report up-to-date Affiliation
+for clear identification. Commits should contain business email where
+applicable.
+
+When code comes from the same organization as positive review, then review
+is not considered independent, but still may provide helpful insight.
+
+Self review is not allowed.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.17. Merge rules.
+
+1. Each change **must** be provided as PR that undergoes independent review
+ process (see 1.16).
+2. Single company / organization commit, review, and merge is not allowed.
+3. Merge of PRs with unresolved discussions and "change request" marks
+ is not allowed.
+3. Self committed code merge with or without review is not allowed.
+4. Direct push to master is not allowed.
Review Comment:
(We should setup nuttx and apps repos to block direct push to master. That is something we can do ourselves; INFRA does not need to be involved in that.)
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 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 solution is researched along 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).
Review Comment:
```suggestion
5. Breaking change after discussion / updates is voted on the mailing
list and requires at least 4 +1 binding votes with no -1 binding votes.
Any -1 binding vote is a [veto](https://apache.org/foundation/voting.html#Veto) and blocks the change.
NuttX PMC members cast binding votes. See [Apache Voting Process](https://apache.org/foundation/voting.html)
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 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 solution is researched along the community.
Review Comment:
```suggestion
4. Alternative non-breaking solution is researched alongside the community.
```
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
> @cederom I suggest removing this requirement, as I have shown other project doesn't require it and even Linux that @jerpelea said requires it I looked the git history and them don't have this requirement.
>
>
>
> @raiden00pl @xiaoxiang781216 @hartmannathan for awareness
Thanks, @acassis. I am okay with either option. Code and Documentation in same commit is OK with me, for git bisect purposes. I'm also OK with separating the commits but same PR.
We should choose one and standardize.
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
Review Comment:
> ```suggestion
>
> 4. Different logical functions changes must be provided in a separate Pull Requests.
I recommend to remove the word "functions" entirely here, so:
"Different logical changes must be provided in a separate Pull Requests."
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 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 solution is researched along 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).
Review Comment:
Apologies for my suggested text not being line-wrapped properly. I am doing this from mobile device!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986507878
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
Review Comment:
hmm, i used top-bottom approach.. did small rearrangement.. what place would be better or what better text? :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "tmedicci (via GitHub)" <gi...@apache.org>.
tmedicci commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2714225918
> Thank you folks for all the remarks and grammar suggestions! The update is pushed, please comment :-)
Just re-reviewed: we are fine here. Can you mark the PR as ready-to-review, @cederom please?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "jerpelea (via GitHub)" <gi...@apache.org>.
jerpelea commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1984738705
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
we will do as the majority decides
here is a Linux example
https://web.git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/Documentation/bpf?h=v6.14-rc5
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "tmedicci (via GitHub)" <gi...@apache.org>.
tmedicci commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2707224605
Just to make sure: this file is not rendered into the documentation at https://nuttx.apache.org/docs/latest/index.html, right?
Still pending adding the same info at https://nuttx.apache.org/docs/latest/contributing/index.html (maybe creating a new page)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis merged PR #15950:
URL: https://github.com/apache/nuttx/pull/15950
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1984713697
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
@cederom I suggest removing this requirement, as I shown other project doesn't require it and even Linux that @jerpelea said requires it I looked the git history and them don't have this requirement.
@raiden00pl @xiaoxiang781216 @hartmannathan for awareness
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "acassis (via GitHub)" <gi...@apache.org>.
acassis commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1985275021
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
Review Comment:
> There is a difference between adding something new to the documentation and updating the documentation according to changes made to the code. I don't see a problem with a separate commit for doc in the first case, but in the second case this seems strange. Documentation describes the code, if the code changes then the documentation should also be changed otherwise the doc doesn't describe the current code state.
Exactly, it could happen very ofter: someone revert a commit and forgot the revert the other documentation commit, so the documentation will be out of sync.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "nuttxpr (via GitHub)" <gi...@apache.org>.
nuttxpr commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2705576427
[**\[Experimental Bot, please feedback here\]**](https://github.com/search?q=repo%3Aapache%2Fnuttx+13552&type=issues)
This PR template provides a good starting point for ensuring NuttX contributions meet community standards. Here's a concise review:
**Strengths:**
* **Comprehensive:** Covers key aspects like summary, impact assessment, and testing.
* **Structured:** Well-organized with clear headings and expectations.
* **User-focused:** Emphasizes impact on users and compatibility.
* **Emphasis on Verification:** Requires explicit confirmation of testing and provides sections for pre- and post-change logs.
* **Transparency:** Acknowledges the origins of the requirements and encourages feedback.
**Areas for Improvement:**
* **Enforceability:** While the template is comprehensive, some sections rely on subjective answers (e.g., "Anything else to consider?"). Consider adding more specific checklists or prompts where possible to make reviews more objective.
* **Conciseness in the Template Itself:** The introductory explanation could be shortened. Simply stating "This template ensures PRs meet NuttX contribution requirements" is sufficient. The note at the end can also be removed or integrated as a comment in the template.
* **Specific Testing Requirements:** Encourage more specific testing descriptions. "Works as intended" is vague. Suggest adding prompts for specific test cases, expected outcomes, and performance metrics where applicable. Consider providing links to general testing guidelines.
* **Code Style/Formatting:** While not explicitly mentioned, it's crucial. Add a section or link regarding adherence to NuttX coding style and formatting guidelines.
* **Security Considerations:** The "Impact on security" section is good, but could be strengthened with specific questions, e.g., "Does this change introduce any new potential vulnerabilities?" or "Have any security analysis tools been used?"
* **Documentation Location:** Clarify *where* documentation updates should be placed (e.g., within the code, in a separate file, etc.)
**TODO Points:** The mention of "TODO points" is unclear. If this refers to items within the template itself, address them before finalizing the template.
**Suggestion for Improvement (Example - Testing):**
Instead of:
```
Testing logs before change:
```
Consider:
```
Testing Methodology: [Briefly describe the testing approach used]
Test Cases:
* [Test Case 1]: Expected Outcome: [Expected result], Actual Outcome: [Observed result]
* [Test Case 2]: Expected Outcome: [Expected result], Actual Outcome: [Observed result]
Test Logs (Before Change):
```
By addressing these points, the PR template can be even more effective in ensuring high-quality contributions to the NuttX project.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2709290237
Thank you folks for all the remarks and grammar suggestions! The update is pushed, please comment :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2719668483
> @simbit18: Question for old PR before this Guidelines update. For abandoned and very old PR, how will they be handled? List filters -> **is:pr is:open created:<2024-01-01** https://github.com/apache/nuttx/pulls?q=is%3Apr+is%3Aopen+created%3A%3C2024-01-01+state%3Aopen+
Good question, probably we will ask for the PR/COMMIT description updates where necessary, but we will handle them as usual? If the PR is good right from start there is not much to be done except for code verification :-)
All this is to help everyone in the review process, set standards, and improve quality of the process / project. There are lots of good PRs already and overall is improving. There are not many active reviewers and still outnumbered. I think that long term self-compatibility is the goal and reason behind this update :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986499255
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
Review Comment:
how about "Changes affecting different functionalities must be provided in a separate Pull Requests." ? :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "simbit18 (via GitHub)" <gi...@apache.org>.
simbit18 commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1987029875
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
Review Comment:
Hi @lupyuen and all
> Mi dispiace, ma non credo che GitHub Actions ci consentirà di attivare il flusso di lavoro CI quando passiamo dalla modalità bozza a quella pronta per la revisione. [(Secondo la documentazione)](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#using-filters)
>
> @simbit18Sapresti dirmi se è possibile?
After the PR is marked as draft maybe if we check pull_request event (**github.event.pull_request.draft**) we could skip the draft PRs
Only run on pull requests that are "ready for review" not "draft" pull request.
https://github.com/reviewdog/action-eslint/issues/29#issuecomment-985939887
Don't run GitHub actions for pull requests that are drafts
https://gist.github.com/myobie/671d2f2a1e503efa0c05e7b865c26a9d
> In realtà penso che sia piuttosto utile per CI Workflow eseguire PR Draft. Questa procedura potrebbe essere migliore per PR Review:
>
> 1. NuttX Dev invia un PR in modalità bozza
> 2. Attendi il completamento del flusso di lavoro CI, correggi eventuali errori CI
> 3. NuttX Dev imposta PR su Pronto per la revisione
> 4. Gli amministratori di NuttX esamineranno il PR
> 5. In caso di correzioni: NuttX Dev ripristinerà PR in modalità bozza, attenderà il completamento del flusso di lavoro CI e lo imposterà su Pronto per la revisione
@lupyuen Here I agree with you, also in my opinion the PR Review flow is more logical.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986508565
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
Review Comment:
I think this is shortest and most direct way to point where users may search / ask for help? Please provide text suggestions :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [DRAFT] Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1986520976
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,438 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so right now.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various project and products around
+the world. Remember that any code change may affect different users and their
+business. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us smoothly process your contributions it is very important that you
+follow the guidelines. These rules are based on daily experiences and helps
+us preserve long term self-compatibility and maintenance of the project.
+NuttX is maintained by a small team of volunteers from around the world.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+Presented rules are here to assure high qualiy of the code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
+and maintenance of the project.
-* Valid commit message example:
+Because every change may affect users, products, or services around the world,
+rules apply equally to all authors, reviewers, committers and maintainters.
- ```
- net/can: Add g_ prefix to can_dlc_to_len and len_to_can_dlc.
+This is our Check-List for processing every incoming pull request.
+Also to filter out breaking changes and handle them accordingly.
- 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 <Va...@EmailAddress>
- ```
+### 1.2. Requirements are mandatory.
-* If you create a proper commit message as explained above, the first line
- will be automatically used as pull-request title and the rest is added as
- description. Use it as a starting point to describe your Pull-Request (PR).
+Each Contribution is a Pull Request (PR) that consists of one or more git
+commits (COMMIT). Both PRs and COMMITs **must** adhere to requirements
+presented in the Contributing Guidelines or will be auto-rejected
+until fixed. Special cases are possible and outlined in a dedicated rules.
-### Pull Requests
+### 1.3. Proper change description.
-* Be sure to **fill in the pull-request report** with meaningful content.
- Be very descriptive, take your time. Good explanation, as for someone who
- can see the issue for the first time, will help understand the change and
- improve the assessment process. Please provide short descriptions even for
- a trivial change.
+Proper description of change is mandatory. Description **must** contain
+detailed explanation on:
- * **Summary:** It is important to provide information on why change is
- necessary, what it exactly does and how, if new feature shows up,
- provide references (dependencies, similar problems and solutions), etc.
+ * what is the purpose of change
+ * why it is necessary
+ * what it does / adds / fixes
+ * how things are added / changed / fixed / updated
+ * what is the impact (build / runtime / api / what area)
+ * how it was tested (build host, compiler, target, logs)
+ * references (i.e. `nuttx` and `nuttx-apps` changes).
+ * dependencies (if change depends on other change).
- * **Impact:** State how (where applicable) that change affects users, build
- process, hardware, documentation, security, compatibility, etc.
+Local code build and real world hardware runtime test logs
+**must** be provided (for code related changes), at least short form.
+For fixes, "before" and "after" logs comparison is welcome.
- * **Testing:** Please provide details on how did you verify the change,
- what Host was used for build (OS, CPU, compiler, ..), what Target was
- used for verification (arch, board:config, ..), etc.
- Providing build and runtime logs from before and after change is highly
- appreciated.
+Description can be single or 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.
-* Introduce only one functional change per pull-request.
+Good description when read once will make others understand your work.
+This allows faster review, quick understanding of change history (what
+changed, why, how), and eventual problem identification / fix in future.
-* Provide finished and verified solutions.
- Clearly mark Work-In-Progress pull requests not yet ready for assessment.
+### 1.4. COMMIT and PR descriptions are equally important.
-## References
+Git commit messages are as important as PR descriptions.
-### Example Pull Request Report
+Git log provides offline descriptions of each change that is
+git client / interface independent.
-#### Summary
+
+### 1.5. COMMIT requirements.
+
+Proper git commit message according to template (see 2.1) is **mandatory**,
+or change is auto-rejected until fixed. Build and runtime logs are
+optional here if these are too long and already provided in the PR.
+
+Git commit message consists of:
+
+ 1. Topic with functional area prefix, `:` mark, short self-explanatory
+ functional context, `.` mark.
+ 2. Blank line.
+ 3. Description on what is changed, how, and why. May use several
+ lines, short sentences, or bullet points (see 1.3).
+ 4. Blank line.
+ 5. Signature (created with `git commit -s`).
+
+Valid git commit 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 <Va...@EmailAddress>
+```
+
+
+### 1.6. COMMIT message mandatory fields.
+
+Each git commit message **must** contain these fields, or change is
+auto-rejected until fixed:
+
+ 1. topic.
+ 2. description.
+ 3. signature (`git commit -s`).
+
+Although this seems to repeat rule 1.5, it clearly filters out commits
+with no topic, description, or signature.
+
+
+### 1.7. PR requirements.
+
+1. Proper description (see 1.3) of PR according to template (see 2.3)
+ is **mandatory**. All fields are required or change is auto-rejected
+ until fixed.
+2. For code changes build and runtime logs are **mandatory** to prove code
+ was tested on **at least one** real world hardware target.
+3. Pull Requests should be as small as possible and focused on only one
+ functional change.
+4. Different functional changes must be provided in a separate Pull Requests.
+5. PR may contain several commits but every single commit included
+ must not break break overall build, runtime, and compatibility,
+ especially for other components.
+6. PR that breaks build or runtime anyhow is considered a Breaking Change
+ (see 1.12), is not welcome, and requires special handling (see 1.13).
+7. PR that introduces new feature must have Documentation included (see 1.8).
+8. Work-in-progress PRs should be marked `[WIP]` tag and set as "draft".
+9. When changes for a 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
+ that this is not a Breaking Change.
+
+Note that small team of maintainers is processing hundreds of PRs every month.
+Providing high quality COMMITs and PRs really helps a lot!
+
+Please provide only finished and verified solutions. Every PR code update
+(`git push -f` to your branch that represents the PR) each time triggers big
+GitHub CI machinery that builds / cross-compiles your code to various targets
+on various build hosts. This is not only slow but also expensive.
+
+
+### 1.8. Documentation requirements.
+
+Changes **must** come with a documentation update (where applicable).
+
+Documentation is part of the `nuttx` git repository. If code change is part
+of `nuttx-apps` repository then separate PR in `nuttx` repository is required.
+Otherwise documentation should come in the same PR as the code update.
+
+For maintenance reasons, code and documentation should be split into
+two separate commits in the same PR. This helps backporting and separates
+possible code and documentation build errors. Squashing code together with
+documentation into a single commit should be avoided.
+
+If change presents new functionality documentation **must** be provided
+along with the code (not in the future).
+
+If change requires existing documentation update it must be contained
+along with the code change (not in the future).
+
+Successful documentation build logs (shortcut) are welcome.
+
+This helps us keep documentation in sync with the code.
+
+See:
+1. https://github.com/apache/nuttx/tree/master/Documentation
+2. https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.9. Zero Trust approach to user testing.
+
+We implement zero trust approach to user provided testing.
+
+It is the change author duty to provide real world hardware build and runtime
+logs for **at least one** real world hardware device.
+
+Remember that any code change may break things for others, please avoid that.
+
+This helps us filter out untested code commits.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.10. Long term maintenance and self-compatibility.
+
+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 instead of breaking existing features.
+
+Breaking changes are avoided and planned towards next major release (see 1.12).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.11. Experimental features.
+
+Experimental code and incomplete or experimental features that does not impact
+overall project self-compatibility in terms of Breaking Changes (see 1.12)
+**must** be clearly marked with a `[EXPERIMENTAL]` tag in the git commit topic
+and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.12. Breaking changes not welcome.
+
+Breaking changes are not welcome. **We do not "break by design"**. Please
+provide only high quality code and think about other NuttX users.
+
+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" or "enforced changes" ideologies.
+
+"Breaking change" is anything that alters Build / Kernel / Architecture / API,
+alters both nuttx and nuttx-apps repo at the same time, breaks
+build / runtime / api for a single or many boards / architectures /
+applications, breaks self-compatibility, breaks maintenance,
+breaks build / runtime compatibility with existing release code (packages)
+both for nuttx and nuttx-apps, etc.
+
+Remember that any code change may impact other users and their business!
+
+Changes should provide maximum self-compatibility with existing solutions,
+should not impact build and runtime in a negative way, or may require design
+reconsiderations such as providing alternative non-invasive user selectable
+solutions (see 1.10).
+
+When breaking changes are unavoidable, these may be accepted, but need prior
+discussion and agreement of the community and special handling (see 1.13).
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### TODO: 1.13. Breaking changes handling process.
+
+This rule complements "Breaking changes not welcome" rule.
+
+We avoid breaking changes unless absolutely necessary and unavoidable
+(i.e. security fix, broken code, etc). Special case considerations apply:
+
+ 1. First reviewer that recognizes a breaking change should block
+ accidental merge with "Request Changes" mark and ask for discussion.
+ This PR cannot be merged until all requests are resolved.
+ 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 solution is researched along 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 welcome.
+ 7. Breaking change requires at least 4 independent positive PR reviews
+ (see 1.16), all discussions resolved, and zero "request changes".
+ 8. Change must be well documented (buid / runtime test logs, pr, git
+ commit, documentation, release notes, etc) with clear notes on how to
+ fix the introduced problems.
+ 9. Breaking Change must be clearly marked with a `[BREAKING]` tag in the
+ git commit topic and PR title that will propagate to Release Notes.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.14. Breaking changes build and runtime test logs are mandatory.
+
+Breaking changes are special case where build and runtime test logs
+(i.e. `apps/ostest`) for **more than one** different architecture is
+**mandatory**. Community support is welcome.
+
+QEmu tests does not count here as in the past it did not catch problems
+that revealed on a real world hardware after change was already merged.
+
+Although this seems to repeat rule 1.13, it ensures real world hardware
+verification and minimizes possible negative impact on various users.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.15. Reviews reuqirements.
+
+Before PR can be merged to the master repository it requires:
+
+ * 2 or more independent positive reviews.
+ * 4 or more independent positive reviews for Breaking Changes (see 1.12).
+
+In future we plan to add "areas" (such as trivial typo fixes or documentation
+only updates) that may require only one reviewer.
+
+
+### 1.16. Reviews independence.
+
+PR reviews should come from independent organizations.
+NuttX is an Open-Source independent and unbiased project.
+
+Each PMC Member, Committer, and Reviewer must report up-to-date Affiliation
+for clear identification. Commits should contain business email where
+applicable.
+
+When code comes from the same organization as positive review, then review
+is not considered independent, but still may provide helpful insight.
+
+Self review is not allowed.
+
+See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
+
+
+### 1.17. Merge rules.
+
+1. Each change **must** be provided as PR that undergoes independent review
+ process (see 1.16).
+2. Single company / organization commit, review, and merge is not allowed.
+3. Merge of PRs with unresolved discussions and "change request" marks
+ is not allowed.
+3. Self committed code merge with or without review is not allowed.
+4. Direct push to master is not allowed.
Review Comment:
Definitely :-) I am kinda new here but this is not allowed on most repos that I know, not sure why it was enabled, but there may be a reason? We will switch it after rules are applied for sure :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on code in PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#discussion_r1997815998
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,445 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so first.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various projects and products around
+the world. Remember that any code change may affect different users and their
+businesses. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us process your contributions smoothly, it is very important that you
+follow the guidelines. NuttX is maintained by a small team of volunteers from
+around the world. These rules are based on daily experiences and help us
+to preserve long term self-compatibility and maintenance of the project.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+The rules presented are here to ensure high qualiy code and documentation,
Review Comment:
thank you fixed! :-)
##########
CONTRIBUTING.md:
##########
@@ -1,133 +1,445 @@
-# Contributing to Apache NuttX RTOS
+# Apache NuttX RTOS Contributing Guidelines
-Hi! Thank you for your interest in contributing to Apache NuttX RTOS :-)
+Thank you for your interest in contributing to Apache NuttX RTOS :-)
-## Guidelines
+If you haven't yet read
+[The Inviolable Principles of NuttX]( https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
+please do so first.
-To help us successfully review your contribution, it is very
-important that you follow these guidelines.
+Please note that NuttX supports over 15 different architectures, 360+ boards,
+and 1600+ configurations, that are used in various projects and products around
+the world. Remember that any code change may affect different users and their
+businesses. Please try to keep your contributions high quality and compatible.
-If you need more information please read the [Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html).
+To help us process your contributions smoothly, it is very important that you
+follow the guidelines. NuttX is maintained by a small team of volunteers from
+around the world. These rules are based on daily experiences and help us
+to preserve long term self-compatibility and maintenance of the project.
-### Coding Standard
+This document is split into two main parts:
-* You should follow [NuttX C Coding Standard](https://nuttx.apache.org/docs/latest/contributing/coding_style.html).
+ 1. Contribution Rules.
+ 2. Contribution Templates.
-* Your code will be automatically checked by GitHub Continuous Integration
- (CI) system. If you see the "check" step fails, it is possible that this
- happens due to style errors.
+If you need more information please read the
+[Full Contributing Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+or ask questions at our [Social Media channels](https://nuttx.apache.org/community).
-* Note that we require you to solve these issues and adapt all modified files
- even if you didn't introduce the problem yourself (this way,
- every contribution gets us closer to compliance).
-### Commits
-* Each commit **must** contain a meaningful **commit message** that consist of:
- * **topic** (mandatory).
- * **description** (optional, separate with blank line from topic).
+## 1. Contribution Rules.
-* **Prefix** commit topic with a functional context
- (i.e. `sched: Fixed compiler warning.`).
+### 1.1. Goals.
-* Provide only **signed commits** (`git commit -s`) with valid author
- and email fields.
+The rules presented are here to ensure high qualiy code and documentation,
+standardized pull requests processing, as well as long term self-compatibilty
Review Comment:
thank you fixed! :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] 202503 Apache NuttX RTOS Contributing Guidelines update. [nuttx]
Posted by "cederom (via GitHub)" <gi...@apache.org>.
cederom commented on PR #15950:
URL: https://github.com/apache/nuttx/pull/15950#issuecomment-2727806693
@acassis could you please review your remarks and close discussions if all is okay? :-)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org