NetBSD Commit Guidelines

The following Commit Guidelines define the Project's standards for making commits to the source tree:

  1. Commit only code you are familiar with.

    If you are not sure if the code you plan to commit is acceptable (e. g. when taking code that was submitted with a problem report), ask a developer who is familiar with that part of the system for review. If you're new to the Project, check with your sponsor.

  2. Do not commit tainted code to the repository.

    If you commit code that was not written by yourself, double check that the license on that code permits import into the NetBSD source repository, and permits free distribution. Check with the author(s) of the code, make sure that they were the sole author of the code and verify with them that they did not copy any other code.

    Code generated by a large language model or similar technology, such as GitHub/Microsoft's Copilot, OpenAI's ChatGPT, or Facebook/Meta's Code Llama, is presumed to be tainted code, and must not be committed without prior written approval by core.

  3. Do not commit code from foreign trees.

    Do not commit code from a tree checked out from anywhere but from cvs.NetBSD.org. Note that all developers have access to the private rsync-over-ssh service on cvs.NetBSD.org.

  4. The more intrusive your changes are the higher is the level of required prior approval.

    • "Obvious" fixes can be committed without any prior discussion or review. (The definition of "obvious" in the GCC Project is: "could not possibly cause anyone to object." We adopt this definition here)

    • All other (i. e. "non-obvious") fixes should have a review.

    • Implementing (significant) new features requires a prior discussion on an appropriate technical mailing list.

    • Adding a completely new package (e.g. openldap) requires prior discussion on a mailing list and approval from core.

  5. Commit only code that you have tested.

    Make sure that your code actually works as expected, by compiling and running the code that is affected by your change with your system's tools. If you changed a man page, make sure that groff/nroff creates the formatted man page you expect.

    For normal commits (to the trunk), test that your code works on -current. Prior to requesting a pull-up to a branch, test the very changes you will request from releng on the respective release branch.

    Run all relevant tests from /usr/tests or ideally the whole test suite. Check the daily builds and the automated test runs. Long-term regressions (build breakage or failing tests) are not acceptable and changes causing such will be backed out if the regressions are not addressed.

  6. Group commits together that are part of the same fix.

    Rototilling a make variable that affects 50 Makefiles should get one commit for all of them together.

  7. Each commit should be a separate patch/fix/addition/etc.

    Don't fix 3 bugs with the same commit and roll that into "Fixed some bugs". Fix one, test, commit, rinse, repeat. This makes life infinitely easier for releng to pull up fixes since often not everything applies to a given branch.

  8. Do not mix functionality or bug-fix patches with whitespace/layout updates.

    Do those separately (apart from the general requirement that changes be made in such a way that it is easy to discern what each fix did, as described in item 6, there will be pullup issues with largely changed files from trunk->branch when mixing whitespace with functionality fixes).

  9. Clearly document the reasons for your changes in the commit log.

    Detail to some degree what was changed and why. This doesn't need to be a code review/walkthrough but it should be informative to someone reading the log and looking over the diff in 6 months. The focus should be on "why" since the target audience reading the logs can usually figure out "what" from looking the diffs. As an exercise, consider the difference of usefulness between "set i to 1" and "initialize iterator correctly to fix a rarely triggering bug in memory handling".

    Also, "fixed some stuff" or "cvs-1.10.0" isn't informative whereas the following example is:

    "Print useful line number on error while executing .for directive."

    If your change fixes a PR, document it with an appropriate message. Using the template “PR category/bug-id” in your commit message will also append it to the respective problem report in our bug database:

    "Closes PR bin/6666"

    If your code has been reviewed by someone else, document this:

    "Reviewed by <mrg>"

    (Please note that a good commit log doesn't relieve the need for good documentation in the program itself.)

  10. Give proper credit.

    If you commit code that had been submitted in a PR, give proper credit, like:

    "Code submitted in PR lib/393939 by Joe Doe"

    Since the commit messages will eventually appear on the source-changes mailing list which is also available via web, specifying the e-mail addresses of the PR submitter should generally be avoided.

    If you took code from an other Open Source Project, give credit, like:

    "From FreeBSD"

  11. Do not revert other developer's commits.

    If you do not agree with another developer's commit, do not revert it on your own. Contact the other developer and explain to him or her the issues you have with the commit in question. Ask the other developer to back out the changes instead of doing it yourself.

    If no agreement can be reached, contact the Core Team <[email protected]>, which will serve as mediation authority.