Improve Puppet.version API to help automate releases

Without this patch applied, it is difficult to fully automate releases
because the `PUPPETVERSION` constant in code must be updated, creating a
new version of the code.  This circular dependency makes it very
difficult to use `git describe` as the basis for a version string.

This patch addresses the problem by providing a way to break the
circular dependency.  With this patch applied, Puppet will use the
contents of `lib/puppet/VERSION`, if it exists, as the version string.
This VERSION file is not intended to be version controlled therefore
changing it does not create a new version in history as does changing
the code itself.

This patch defines the public API to maintain the software version for
package maintainers.

1 files changed, 14 insertions, 0 deletions

diff --git a/README_DEVELOPER.md b/README_DEVELOPER.md
index 48a9965eb..eaa0be0f7 100644
--- a/README_DEVELOPER.md
+++ b/README_DEVELOPER.md
@@ -434,4 +434,18 @@ checksum representing the content.  When managing an out of sync file resource,
 the real contents should be fetched from the server instead of the
 clientbucket.
 
+Package Maintainers
+=====
+
+Software Version API
+-----
+
+Please see the public API regarding the software version as described in
+`lib/puppet/version.rb`.  Puppet provides the means to easily specify the exact
+version of the software packaged using the VERSION file, for example:
+
+    $ git describe --match "3.0.*" > lib/puppet/VERSION
+    $ ruby -r puppet/version -e 'puts Puppet.version'
+    3.0.1-260-g9ca4e54
+
 EOF