Look for and process sem-ver pseudo headers in git

At the moment careful changelog review is needed by humans to
determine the next version number. Semantic versioning means that all
we need to know to get a reasonable default next version (and a lower
bound on the next version) is a record of bugfix/deprecation/feature
work and api-breaking commits. In this patch we start scanning for
such headers from the git history to remove this burden from
developers/project release managers. Higher versions can of course
be used either via pre-versioning or by tagging the desired version.

implements: blueprint pbr-semver
sem-ver: feature
Change-Id: Id5e8cd723d5186d1bd8c01599eae8933e6f7ea6d

1 files changed, 10 insertions, 0 deletions

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 897f3e5..fa77de1 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -36,6 +36,16 @@ If a given revision is tagged, that's the version.
 If it's not, then we take the last tagged version number and increment it to
 get a minimum target version.
 
+We then walk git history back to the last release. Within each commit we look
+for a sem-ver: pseudo header, and if found parse it looking for keywords.
+Unknown symbols are not an error (so that folk can't wedge pbr or break their
+tree), but we will emit an info level warning message.  Known symbols:
+``feature``, ``api-break``, ``deprecation``, ``bugfix``. A missing
+sem-ver line is equivalent to ``sem-ver: bugfix``. The ``bugfix`` symbol causes
+a patch level increment to the version. The ``feature`` and ``deprecation``
+symbols cause a minor version increment. The ``api-break`` symbol causes a
+major version increment.
+
 If postversioning is in use, we use the resulting version number as the target
 version.