add news.rst & define a semantics for Consfigurator version numbers

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

4 files changed, 37 insertions, 8 deletions

diff --git a/doc/ideas.rst b/doc/ideas.rst
index 72f02ff..80dbcc7 100644
--- a/doc/ideas.rst
+++ b/doc/ideas.rst
@@ -80,8 +80,7 @@ Core
 Project & packaging
 -------------------
 
-- Define a semantics for version numbers (probably just like Propellor's),
-  start keeping a NEWS file, start actually announcing releases to
-  sgo-software-announce.  Take the opportunity to review whole public API for
-  good choices of names and sensible separation of responsibilities.
-  Increment major version number from zero to one.
+- Start actually announcing releases to sgo-software-announce.  Take the
+  opportunity to review whole public API for good choices of names and
+  sensible separation of responsibilities.  Increment major version number
+  from zero to one, and from then on start updating news.rst.
diff --git a/doc/index.rst b/doc/index.rst
index 2c62559..96430cf 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -15,6 +15,7 @@ Consfigurator user's manual
    propspecs
    data
    pitfalls
+   news
    ideas
 
 Indices and search
diff --git a/doc/introduction.rst b/doc/introduction.rst
index e1c3a0e..cbf09c1 100644
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
@@ -276,9 +276,6 @@ nicknames.
 Portability and stability
 -------------------------
 
-- **Consfigurator is still stabilising and so there may be lots of breaking
-  changes.**
-
 - The core library should be portable between standards-conforming
   implementations of ANSI Common Lisp which include support for a few
   additional, widely-implemented features such as package-local nicknames.
diff --git a/doc/news.rst b/doc/news.rst
new file mode 100644
index 0000000..5a498da
--- /dev/null
+++ b/doc/news.rst
@@ -0,0 +1,32 @@
+News
+====
+
+Some user-visible changes in versions of Consfigurator >1.0.0 are documented
+here.  Version numbers have three components, ``major.minor.patch``, with the
+following semantics:
+
+- we increment ``major`` for a release which contains particularly significant
+  new features, enhancements and/or reworkings, whether or not upgrading to
+  the release will require changes to user consfigs (though usually it will);
+
+  + Additionally, while ``major`` is zero, we will be much more willing to
+    make breaking changes.
+
+- we increment ``minor`` for a release which does not satisfy the requirements
+  for incrementing ``major``, but where there are changes that could require
+  changes in user consfigs, except very obscure such consfigs; and
+
+- we increment only ``patch`` for a release which includes no changes that we
+  think could require changes in user consfigs.
+
+Note that the notion of consfig-breaking changes is more than just strict API
+breaks, but also changes in behaviour which will likely require review by
+sysadmins using Consfigurator to maintain their systems.
+
+In summary, you should always be able to upgrade to a release which only
+increments ``patch``, but if either of the other two components have changed,
+you should review this document and see if your consfig needs updating.
+
+..
+   1.0.1 (unreleased)
+   ------------------