SERVER-58284 Add documentation around MONGO_VERSION and MONGO_GIT_HASH

2 files changed, 70 insertions, 0 deletions

diff --git a/docs/build_system.md b/docs/build_system.md
index 477d59b05c4..bba2a24ddde 100644
--- a/docs/build_system.md
+++ b/docs/build_system.md
@@ -71,6 +71,61 @@
 ## Developer builds
 ### Developer build options
 #### `MONGO_{VERSION,GIT_HASH}`
+
+By default, the server build system consults the local git repository
+(assuming one exists) to automatically derive the current version of
+MongoDB and current git revision that is being built. These values are
+recorded in the SCons `MONGO_VERSION` and `MONGO_GIT_HASH`
+`Environment` variables, respectively. The value of `MONGO_GIT_HASH`
+is just that: the value of the currently checked out git hash. The
+value computed for `MONGO_VERSION` is based on the result of `git
+describe`, which looks for tags matching the release numbering
+scheme. Since `git describe` relies on tags, it is important to ensure
+that you periodically synchronize new tags to your local repository
+with `git fetch` against the upstream server repository.
+
+While this automated scheme works well for release and CI builds, it
+has unfortunate consequences for developer builds. Since the git hash
+changes on every commit (whether locally authored or pulled from an
+upstream repo), and since by default an abbreviated git hash forms
+part of the result of `git describe`, a build after a commit or a pull
+will see any target that has a direct or indirect dependency on the
+parts of the codebase that care about `MONGO_VERSION` and
+`MONGO_GIT_HASH` as out of date. Notably, you will at minimum need to
+relink `mongod` and other core server binaries.
+
+It is possible to work around this by manually setting values for
+`MONGO_VERSION` and `MONGO_GIT_HASH` on the SCons command
+line. However, doing so in a way that results in an accurate value for
+`MONGO_VERSION` in particular requires writing shell command
+substitutions into your SCons invocation, which isn't very
+friendly. The longstanding historical practice of setting
+`MONGO_VERSION=0.0.0` was never well-advised, but because of recent
+feature compatibility version related work it is no longer safe to do
+that at all.
+
+To make it easier for developers to manage these variables in a way
+which avoids useless rebuilds, has better ergonomics, and does not run
+afoul of FCV management, the server build system provides a variables
+file to manage these settings automatically:
+`etc/scons/developer_versions.vars` . By using this file, you will get
+an unchanging `MONGO_GIT_HASH` value of `unknown`, and a
+`MONGO_VERSION` value that is still based on `git describe`, but with
+`--abbrev=0` affixed, which will eliminate the dependency on the SHA
+of the current commit. Note that you will still observe rebuilds if
+you pull a new tag which changes the results of `git describe`, but
+this should be a much less frequent event.
+
+You can opt into this variable by adding
+`--variables-files=etc/scons/developer_versions.vars` to your SCons
+command line, either for direct SCons builds, or when generating
+Ninja.
+
+Support for `etc/scons/developer_versioning.vars` has been backported
+as far back as MongoDB `v4.0`, so you can safely add this to your
+SCons invocations on almost any branch you are likely to find yourself
+using.
+
 #### Using sanitizers
 ##### `--sanitize`
 ##### `*SAN_OPTIONS`
diff --git a/docs/build_system_reference.md b/docs/build_system_reference.md
index 8a09bbacb3d..45ae052ad28 100644
--- a/docs/build_system_reference.md
+++ b/docs/build_system_reference.md
@@ -407,6 +407,21 @@ After the server has started up, it should notify you via the terminal that you
 #### Frequently used flags and variables
 ### MongoDB build configuration
 #### Frequently used flags and variables
+
+##### `MONGO_GIT_HASH`
+
+The `MONGO_GIT_HASH` SCons variable controls the value of the git hash
+which will be interpolated into the build to identify the commit
+currently being built. If not overridden, this defaults to the git
+hash of the current commit.
+
+##### `MONGO_VERSION`
+
+The `MONGO_VERSION` SCons variable controls the value which will be
+interpolated into the build to identify the version of the software
+currently being built. If not overridden, this defaults to the result
+of `git describe`, which will use the local tags to derive a version.
+
 ### Targets and Aliases
 
 ## Build artifacts and installation