document git commit versions

lib/spack/docs/basic_usage.rst

@@ -1060,14 +1060,19 @@ set of arbitrary versions, such as ``@1.0,1.5,1.7`` (``1.0``, ``1.5``,
 or ``1.7``).  When you supply such a specifier to ``spack install``,
 it constrains the set of versions that Spack will install.
 
+For packages with a ``git`` attribute, a 40-character git commit sha
+may be specified instead of a numerical version. Spack will inspect
+the tags in the git repo to determine the nearest previous version
+known to Spack, and use that as the basis for comparison. Details
+about how versions are compared and how Spack determines if one
+version is less than another are discussed in the developer guide.
+
 If the version spec is not provided, then Spack will choose one
 according to policies set for the particular spack installation.  If
 the spec is ambiguous, i.e. it could match multiple versions, Spack
 will choose a version within the spec's constraints according to
 policies set for the particular Spack installation.
 
-Details about how versions are compared and how Spack determines if
-one version is less than another are discussed in the developer guide.
 
 ^^^^^^^^^^^^^^^^^^
 Compiler specifier

lib/spack/docs/environments.rst

@@ -368,6 +368,34 @@ from being added again.  At the same time, a spec that already exists in the
 environment, but only as a dependency, will be added to the environment as a
 root spec without the ``--no-add`` option.
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Developing Packages in a Spack Environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``spack develop`` command allows one to develop Spack packages in
+an environment. It requires a spec containing a concrete version, and
+will configure Spack to install the package from local source. By
+default, it will also clone the package to a subdirectory in the
+environment. This package will have a special variant ``dev_path``
+set, and Spack will ensure the package and its dependents are rebuilt
+any time the environment is installed if the package's local source
+code has been modified. Spack ensures that all instances of a
+developed package in the environment are concretized to match the
+version (and other constraints) passed as the spec argument to the
+``spack develop`` command.
+
+For packages with ``git`` attributes, 40-character commit hashes are
+also valid versions. This means that for a package ``foo`` whose
+latest commit is ``abcdef1234abcdef1234abcdef1234abcdef1234``, ``spack
+develop foo@abcdef1234abcdef1234abcdef1234abcdef1234`` will clone the
+latest version of the package, and ``spack install`` will install from
+that source if ``foo`` is in the environment. Further development on
+``foo`` can be tested by reinstalling the environment, and eventually
+committed and pushed to the upstream git repo.
+
+Further information on git commits as versions can be found in the
+API documentation for the ``Version`` class.
+
 ^^^^^^^
 Loading
 ^^^^^^^

lib/spack/spack/version.py

@@ -166,7 +166,73 @@ def __gt__(self, other):
 
 
 class Version(object):
-    """Class to represent versions"""
+    """Class to represent versions
+
+    Versions are compared by converting to a tuple and comparing
+    lexicographically.
+
+    The most common Versions are numeric, and are parsed from strings
+    such as ``2.3.0`` or ``1.2-5``. These Versions are represented by
+    the tuples ``(2, 3, 0)`` and ``(1, 2, 5)`` respectively.
+
+    Some Spack versions involve slight extensions of numeric syntax;
+    for example, ``0.1.3a``. Versions are split on ``.``, ``-``, and
+    ``_`` characters, as well as any point at which they switch from
+    numeric to alphabetical or vice-versa. For example, the version
+    ``0.1.3a`` is represented by the tuple ``(0, 1, 3, 'a') and the
+    version ``a-5b`` is represented by the tuple ``('a', 5, 'b')``.
+
+    Spack versions may also be arbitrary non-numeric strings or git
+    commit SHAs. The following are the full rules for comparing
+    versions.
+
+    1. If the version represents a git commit, see the note below.
+
+    2. The version is split into fields based on the delimiters ``.``,
+    ``-``, and ``_``, as well as alphabetic-numeric boundaries.
+
+    3. The following develop-like strings are greater (newer) than all
+    numbers and are ordered as ``develop > main > master > head >
+    trunk``.
+
+    4. All other non-numeric versions are less than numeric versions,
+    and are sorted alphabetically.
+
+    These rules can be summarized as follows:
+
+    ``develop > main > master > head > trunk > 999 > 0 > 'zzz' > 'a' >
+    ''``
+
+    A note on git commit versions:
+
+    Git commit versions are handled separately from all other version
+    comparisons. When Spack identifies a git commit version, it
+    associates a ``CommitLookup`` object with the version. This object
+    handles caching of information from the git repo. When executing
+    comparisons with a git commit version, Spack queries the
+    ``CommitLookup`` for the most recent version previous to this
+    commit, as well as the distance between them expressed as a number
+    of commits. If the previous version is ``X.Y.Z`` and the distance
+    is ``D``, the git commit version is represented by the tuple ``(X,
+    Y, Z, '', D)``. The component ``''`` cannot be parsed as part of
+    any valid version, but is a valid component. This allows a git
+    commit version to be less than (older than) every Version newer
+    than its previous version, but still newer than its previous
+    version.
+
+    To find the previous version from a git commit version, Spack
+    queries the git repo for its tags. Any tag that matches a version
+    known to Spack is associated with that version, as is any tag that
+    is a known version prepended with the character ``v`` (i.e., a tag
+    ``v1.0`` is associated with the known version
+    ``1.0``). Additionally, any tag that represents a semver version
+    (X.Y.Z with X, Y, Z all integers) is associated with the version
+    it represents, even if that version is not known to Spack. Each
+    tag is then queried in git to see whether it is an ancestor of the
+    commit in question, and if so the distance between the two. The
+    previous version is the version that is an ancestor with the least
+    distance from the commit in question.
+    """
     __slots__ = ['version', 'separators', 'string', 'commit_lookup']
 
     def __init__(self, string):