cederom commented on code in PR #16823:
URL: https://github.com/apache/nuttx/pull/16823#discussion_r2271159156
##########
CONTRIBUTING.md:
##########
@@ -285,8 +285,11 @@ 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. Breaking Change must be clearly identified with inclusion of the an
+ exclamation mark `!` as first character of the commit title and a
+ `BREAKING CHANGE:` in the git commit log message, followed by a short
+ comment about way user will use it currently. This change description
+ will be used to create the Release Notes.
Review Comment:
Thanks @hartmannathan :-)
* what is the difference between "identified" and "marked"? is it author who
"marks" and recipient who "identifies"? are IC marked on the casing or
identified on the casing? :-P
* Pull Requests are omitted here, we should keep Git Commits and Pull
Requests tied with the same rule. Release Notes are built from PR titles. This
allows separation of breaking changes in the Release Notes. This saves time for
the user after update. Git Logs are first contact to see why things broke / how
things changed, contain more details than release notes, thus my suggestion git
log can be simply grepped / searched for specific marks to find fixes.
* I like the idea that we should somehow require authors to provide a brief
overview on what changed with a quick-fix, using this "BREAKING CHANGE:" mark,
if something needs an update and the user is not an expert, also to have
consistent fixes implemented. Details of the change will be bundled in the
description too, but its more about what changed and how to fix if broken.
"Adopt their code" is nice but too wide does not imply a specific fix. I know
there is no quick fix always possible, then a hint is enough. Should we make it
more precise?
* How to update last sentence to show that not only release notes are built
that way but also git log can be searched for hints and fixes after update?
Breaking changes happen and we should do best we can to prepare users for
smooth updates :-)
Not all changes will affect all users and not all users are experts so we
should provide braindead simple way to fix things :-)
--
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-unsubscr...@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
