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,18 @@ % 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. It is always a good +idea to 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 to make +sure nothing weird was present. + +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 +1169,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. It is always +a good idea to run them 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, it's advisable to 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 your 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.