diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index defafad5d82..74532bf15bd 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1222,6 +1222,23 @@ A version specifier can also be a list of ranges and specific versions,
 separated by commas.  For example, ``@1.0:1.5,=1.7.1`` matches any version
 in the range ``1.0:1.5`` and the specific version ``1.7.1``.
 
+^^^^^^^^^^^^^^^^^
+Binary Provenance
+^^^^^^^^^^^^^^^^^
+
+Spack versions are paired to attributes that determine the source code Spack
+will use to build. Checksummed assets are preferred but there are a few 
+notable exceptions such as git branches and tags i.e ``pkg@develop``.
+These versions do not naturally have source provenance because they refer to a range
+of commits (branches) or can be changed outside the spack packaging infrastructure
+(tags). Without source provenace we can not have binary provenance.
+
+Spack has a reserved variant to allow users to complete source and binary provenance
+for these cases: ``pkg@develop commit=<SHA>``.  The ``commit`` variant must be supplied
+the full 40 character commit SHA. Using a partial commit SHA or assigning
+the ``commit`` variant to a version that is not using a branch or tag reference will
+lead to an error during concretization.
+
 ^^^^^^^^^^^^
 Git versions
 ^^^^^^^^^^^^
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 453298bea8e..581c1fcb1e4 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -1267,7 +1267,11 @@ Git fetching supports the following parameters to ``version``:
   If paths provided are directories then all the subdirectories and associated files
   will also be cloned.
 
-Only one of ``tag``, ``branch``, or ``commit`` can be used at a time.
+``tag`` and ``branch`` should not be combined in the version parameters. We strongly
+recommend that all ``tag`` entries be paired with ``commit``. Providing the full 
+``commit`` SHA hash allows for Spack to preserve binary provenance for all binaries. 
+This is due to the fact that git tags and branches are mutable references to commits, 
+but git commits are guaranteed to be unique points in the git history.
 
 The destination directory for the clone is the standard stage source path.