Hello world :-)
Following the discussion thread
(https://lists.apache.org/thread/o1r2b776y9o3dwytp7hb0x1w0gclsw8n)
lets vote, standard 72h time closes on 2026-02-07 :-)
I would like to copy Contributing Guide [1] to our documentation /
contributing section [2] where some users may look first before the
git repo.
I would like to propose 4 changes before we do that:
1. "Contributing Guidelines" rename to "Contributing Guide" so we use
coherent and shorter naming that would be also aligned with other
open-source projects.
2. "[BREAKING]" mark change to "!" as proposed by Alan. This change
was discussed before [3] and in line with Conventional Commits [4]
(except we want "!" as first char for clarity). This still needs to be
part of git commit and PR description as before.
3. Require "BREAKING CHANGE:" section in breaking changes description
(as discussed in [3] and required by [4]) that will also contain Quick
Fix instructions. As the description is part of git commit and PR it
will not only help understand what changed but also how to quickly
adapt / fix after change to someone impacted with best possible
solution out of the box.
4. Reference Security documentation [5] in the Contributing Guide [1].
To sum up (2) and (3) here is a proposition of point 1.13.9 update:
Old version:
"""
Breaking Change must be clearly marked with a [BREAKING] tag in the
git commit topic and PR title that will propagate to Release Notes.
"""
New version:
"""
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 PR title.
2. Put 'BREAKING CHANGE:' in the git commit and PR 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.
"""
Example? Recently we got cJSON related update, we use 1.7.10 release,
but 1.7.19 is already out. I asked PR author if update to 1.7.19 is
possible. Looking at the cJSON releases page [6] to check for breaking
changes version 1.7.14 contains this kind of description and quick fix
instructions, which may server as good example here:
"""
Since v1.7.13 changed the stucture of linkedlist to improve the
efficiency of adding item to array/object, array->child->prev now is
point to tail node, this won't change any behavior except for backward
through the linkedlist.
The current backward through the linkedlist could be in this way:
cJSON *last = ...; // the last is known
cJSON *current_item = last;
do {
current_item = current_item->prev;
} while(current_item != last);
"""
Why? Because it builds trust in the project, will help ourselves in
the long-term maintenance (LTS), and to align with CRA / Cyber
Resilience Act [7], SBOM [8], etc, that will soon become a mandatory
requirement for commercial and industrial applications /
certifications. I filled in a form [9] recently where this question
was asked, so we would have this already in place :-)
There is a separate discussion necessary for "secure development guide
or security-relevant onboarding for new developers and maintainers".
We have now a Security section in the documentation [5] with some
hints and we may just extend it as dedicated section. We may want to
reference Security documentation in the Contributing Guide too, thus
my proposition for (4).
Thank you :-)
Tomek
[1] https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md
[2] https://nuttx.apache.org/docs/latest/contributing/index.html
[3] https://github.com/apache/nuttx/pull/16823
[4] https://www.conventionalcommits.org/en/v1.0.0/
[5] https://nuttx.apache.org/docs/latest/security.html
[6] https://github.com/DaveGamble/cJSON/releases
[7] https://digital-strategy.ec.europa.eu/en/policies/cra-reporting
[8] https://www.cisa.gov/sbom
[9] https://ec.europa.eu/eusurvey/runner/CRA-Attestation-Survey-2026-FOSDEM
--
CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
