diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -1125,8 +1125,21 @@ % git tag -a vendor/NetBSD/mtree/20201211 .... -Note: I run the `git diff` and `git status` commands to make sure nothing weird was present. -Also I used `-m` to illustrate, but you should compose a proper message in an editor (using a commit message template). +It is critical to verify that the source code you are importing comes from a +trustworthy source. Many open-source projects use cryptographic signatures to +sign code changes, git tags, and/or source code tarballs. Always verify these +signatures before proceeding. Following the upstream +development and occasionally reviewing the upstream code changes can greatly +help in improving code quality and benefit everyone involved. It is also a +good idea to examine the git diff results before importing them into the +vendor area. + +Always run the `git diff` and `git status` commands and examine the results +carefully. When in doubt, it is useful to do a `git annotate` on the vendor +branch or the upstream git repository to see who and why a change was made. + +In the example above we used `-m` to illustrate, but you should compose a +proper message in an editor (using a commit message template). It is also important to create an annotated tag using `git tag -a`, otherwise the push will be rejected. Only annotated tags are allowed to be pushed. @@ -1159,6 +1172,25 @@ If there were conflicts, you would need to fix them before committing. Include details about the changes being merged in the merge commit message. +Some open-source software includes a `configure` script that generates files +used to define how the code is built. Keep in mind that these scripts are +executable code running under the current user's credentials. This process +should be run in an isolated environment, ideally inside a jail +that does not have network access, and with an unprivileged account; or, +at minimum, a dedicated account that is different from the user account +you normally use for everyday purposes or for pushing to the FreeBSD source +code repository. This minimizes the risk of encountering bugs that can +cause data loss or, in worse cases, maliciously planted code. Using an +isolated jail also prevents the configure scripts from detecting locally +installed software packages, which may lead to unexpected results. + +When testing your changes, run them in a chroot or jailed environment, +or even within a virtual machine first, especially for kernel or library +modifications. This approach helps prevent adverse interactions with +otheryour working environment. It can be particularly beneficial for +changes to libraries that many base system components use, +among others. + ==== Rebasing your change against latest FreeBSD source tree Because the current policy recommends against using merges, if the upstream FreeBSD `main` moved forward before you get a chance to push, you would have to redo the merge.