This is an automated email from the ASF dual-hosted git repository.
linguini pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 8699c675e29 doc: Contributing Guide updates.
8699c675e29 is described below
commit 8699c675e290d57f5a8bd8dd5f4f902441b3c671
Author: Tomasz 'CeDeROM' CEDRO <[email protected]>
AuthorDate: Thu Feb 19 14:32:30 2026 +0100
doc: Contributing Guide updates.
* As voted in
https://www.mail-archive.com/[email protected]/msg14264.html.
* Contributing Guide nomenclature align.
* Mention CG locations (git and doc).
* Reference NuttX Documentation, Contributing, and Security.
* Added Contributing Guide to NuttX Documentation (md include to stay in
sync).
* Breaking Changes marking update:
* `[BREAKING]` title tag replaced with `!` (exclamation mark).
* `BREAKING CHANGES:` description brief with quick-fix instructions added.
* Breaking change git commit and pr template examples added.
Signed-off-by: Tomasz 'CeDeROM' CEDRO <[email protected]>
---
CONTRIBUTING.md | 64 ++++++++++++++++++++++++++++++------
Documentation/contributing/guide.rst | 3 ++
Documentation/contributing/index.rst | 1 +
3 files changed, 58 insertions(+), 10 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e30eca11bb0..d6739cc8ad7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Apache NuttX RTOS Contributing Guidelines
+# Apache NuttX RTOS Contributing Guide
Thank you for your interest in contributing to Apache NuttX RTOS :-)
@@ -6,29 +6,36 @@ If you haven't yet read
[The Inviolable Principles of NuttX](
https://github.com/apache/nuttx/blob/master/INVIOLABLES.md)
please do so first.
-Please note that NuttX supports over 15 different architectures, 360+ boards,
+Apache NuttX RTOS 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.
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
+follow this guide. 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.
This document is split into two main parts:
- 1. Contribution Rules.
- 2. Contribution Templates.
+ 1. Contributing Rules.
+ 2. Contributing Templates.
If you need more information please read the
-[Full Contributing
Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html)
+[NuttX Documentation](https://nuttx.apache.org/docs/latest),
+[Contributing
Documentation](https://nuttx.apache.org/docs/latest/contributing/index.html),
+[Security Documentation](https://nuttx.apache.org/docs/latest/security.html),
or ask questions at our [Social Media
channels](https://nuttx.apache.org/community).
+Mailing list is our main and preferred communication channel.
+This NuttX Contributing Guide is part of both
+[Git Repository](https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md)
+and [NuttX
Documentation](https://nuttx.apache.org/docs/latest/contributing/guide.html).
-## 1. Contribution Rules.
+
+## 1. Contributing Rules.
### 1.1. Goals.
@@ -285,8 +292,15 @@ We avoid breaking changes unless absolutely necessary and
unavoidable
8. Change must be well documented (build / 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.
+ 9. **All breaking changes must be clearly marked both in git commits and
+ pull requests**:
+ 1. Put `!` (exclamation mark) as first character of the each breaking
+ git commit and pull request title.
+ 2. Put `BREAKING CHANGE:` in the git commit and pull request body with
+ a brief change description and the **quick-fix** instructions.
+
+ This helps users identify areas that need an update on their side,
+ grep git logs, and auto-generate release notes.
See: https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
@@ -351,7 +365,7 @@ See:
https://github.com/apache/nuttx/blob/master/INVIOLABLES.md
-## 2. Contribution Templates.
+## 2. Contributing Templates.
### 2.1. Source Code.
@@ -386,6 +400,22 @@ improving code readability and maintainability.
Signed-off-by: AuthorName <Valid@EmailAddress>
```
+This template provides breaking change git commit example as described in
requirement 1.13:
+
+```
+!interpreters/bas: Align naming of Kconfig options.
+
+Aligns `CONFIG_INTERPRETER_*` options to `CONFIG_INTERPRETERS_*` options
+to be consistent with other interpreters.
+
+BREAKING CHANGE: All configurations using `CONFIG_INTERPRETER_BAS_*`
+options will no longer compile due to missing symbol errors. The fix is
+very quick: any configurations using this options should add a trailing
+S following INTERPRETER in the affected Kconfig variables.
+
+Signed-off-by: AuthorName <Valid@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).
@@ -397,6 +427,8 @@ This template uses MarkDown and provides example Pull
Request content
as described in requirement 1.7.
````
+functional/area: Self explanatory pull request title.
+
## Summary
* Why change is necessary (fix, update, new feature)?
@@ -443,3 +475,15 @@ as described in requirement 1.7.
* [ ] My PR is still work in progress (not ready for review).
* [ ] My PR is ready for review and can be safely merged into a codebase.
````
+
+Breaking changes marking requirement 1.13 implies additional `!` (exclamation
+mark) as the first character of the pull request title and the
+`BREAKING CHANGES:` brief change description with a quick-fix instructions.
+
+```
+!functional/area: Self explanatory pull request title.
+
+## Summary
+
+ * BREAKING CHANGE: Brief change description with a quick-fix instructions.
+```
diff --git a/Documentation/contributing/guide.rst
b/Documentation/contributing/guide.rst
new file mode 100644
index 00000000000..6bdd23d690a
--- /dev/null
+++ b/Documentation/contributing/guide.rst
@@ -0,0 +1,3 @@
+.. _contributing-guide:
+.. include:: ../../CONTRIBUTING.md
+ :parser: myst_parser.sphinx_
diff --git a/Documentation/contributing/index.rst
b/Documentation/contributing/index.rst
index 4cacfea52b0..feabfe2feff 100644
--- a/Documentation/contributing/index.rst
+++ b/Documentation/contributing/index.rst
@@ -9,6 +9,7 @@ to NuttX codebase (from small bugfixes to large new features)
and documentation
.. toctree::
:maxdepth: 2
+ Contributing Guide <guide.rst>
workflow.rst
making-changes.rst
coding_style.rst
