README: describe version-string flavors

warner · warner · commit dc78a19e9f2c · 2014-03-11T13:32:01.000-07:00
diff --git a/README.md b/README.md
@@ -26,13 +26,11 @@ system, and maybe making new tarballs.
 
 Source trees come from a variety of places:
 
-* a version-control system checkout (mostly used by developers or eager
-  followers)
+* a version-control system checkout (mostly used by developers)
 * a nightly tarball, produced by build automation
-* a snapshot tarball, produced by a web-based VCS browser, like hgweb or
-  github's "tarball from tag" feature
-* a release tarball, produced by "setup.py sdist", and perhaps distributed
-  through PyPI
+* a snapshot tarball, produced by a web-based VCS browser, like github's
+  "tarball from tag" feature
+* a release tarball, produced by "setup.py sdist", distributed through PyPI
 
 Within each source tree, the version identifier (either a string or a number,
 this tool is format-agnostic) can come from a variety of places:
@@ -165,6 +163,45 @@ Currently, all version strings must be based upon a tag. Versioneer will
 report "unknown" until your tree has at least one tag in its history. This
 restriction will be fixed eventually (see issue #12).
 
+## Version-String Flavors
+
+Code which uses Versioneer can learn about its version string by importing
+`_version` from your main `__init__.py` file and running the `get_versions()`
+method. This returns a dictionary with different keys for different flavors
+of the version string:
+
+* `['version']`: condensed tag+distance+shortid+dirty identifier. For git,
+  this uses the output of `git describe --tags --dirty --always` but strips
+  the tag_prefix. For example "0.11-2-g1076c97-dirty" indicates that the tree
+  is like the "1076c97" commit but has uncommitted changes ("-dirty"), and
+  that this commit is two revisions ("-2-") beyond the "0.11" tag. For
+  released software (exactly equal to a known tag), the identifier will only
+  contain the stripped tag, e.g. "0.11".
+
+* `['full']`: detailed revision identifier. For Git, this is the full SHA1
+  commit id, followed by "-dirty" if the tree contains uncommitted changes,
+  e.g. "1076c978a8d3cfc70f408fe5974aa6c092c949ac-dirty".
+
+Some variants are more useful than others. Including `full` in a bug report
+should allow developers to reconstruct the exact code being tested (or
+indicate the presence of local changes that should be shared with the
+developers). `version` is suitable for display in an "about" box or a CLI
+`--version` output: it can be easily compared against release notes and lists
+of bugs fixed in various releases.
+
+In the future, this will also include a
+[http://legacy.python.org/dev/peps/pep-0440/](PEP-440) -compatible flavor
+(e.g. `.post0.dev123`). This loses a lot of information (and has no place for
+a hash-based revision id), but is safe to use in a `setup.py` "`version=`"
+argument. It also enables tools like *pip* to compare version strings and
+evaluate compatibility constraint declarations.
+
+The `setup.py update_files` command adds the following text to your
+`__init__.py` to place a basic version in `YOURPROJECT.__version__`:
+
+    from ._version import get_versions
+    __version = get_versions()['version']
+    del get_versions
 
 ## Future Directions
 
