Document some best practices related to vendor import:

Summary:
 - Verify the source code comes from a trustworthy
   source.
 - Always review the diff before importing.
 - Run configure scripts and alike in an isolated
   environment.
 - Perform tests inside chroot, jail or in VM first.

Reviewed by:	emaste, imp
Differential Revision: https://reviews.freebsd.org/D44557

1 files changed, 50 insertions, 2 deletions

diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 96fa3b2707..1f787aaff6 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -1125,8 +1125,24 @@ package:net/rsync[] is commonly installed, so I'll use that.
 % 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, and use isolation mechanisms like jails, chroot, in combination of
+a dedicated, non-privileged user account that is different from the one you
+regularily use (see the Updating the FreeBSD source tree section below for
+more details), until you are confident that the source code you are importing
+looks safe. 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.
@@ -1149,6 +1165,12 @@ At this point you can push the import to `vendor` into our repo.
 Now you need to update the mtree in FreeBSD.
 The sources live in `contrib/mtree` since it is upstream software.
 
+From time to time, we may have to make changes to the contributed code to
+better satisfy FreeBSD's needs. Whenever possible, please try to contribute
+the local changes back to the upstream projects, this helps them to better
+support FreeBSD, and also saves your time for future conflict resolutions
+when importing updates.
+
 [source,shell]
 ....
 % cd ../src
@@ -1156,9 +1178,35 @@ The sources live in `contrib/mtree` since it is upstream software.
 ....
 
 This would generate a subtree merge commit of `contrib/mtree` against the local `vendor/NetBSD/mtree` branch.
+Examine the diff from the merge result and the contents of the
+upstream branch. If the merge reduced our local changes to more
+trivial difference like blank line or indenting changes, try amending
+the local changes to reduce diff against upstream, or try to
+contribute the remaining changes back to the upstream project.
 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, usually, these generated files like
+`config.h` should be updated as part of the import process. When doing
+this, always keep in mind that these scripts are executable code running
+under the current user's credentials. This process should always 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.