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 <Valid@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 <Valid@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-unsubscr...@nuttx.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
