Userguide section and whitepaper on user change management. (#1999)

* Userguide section and whitepaper on user change management.
SciTools · Jul 27, 2016 · fd53eb6 · fd53eb6
1 parent 53a51f6
commit fd53eb6
Show file tree

Hide file tree

Showing 9 changed files with 510 additions and 0 deletions.
diff --git a/docs/iris/src/developers_guide/deprecations.rst b/docs/iris/src/developers_guide/deprecations.rst
@@ -1,3 +1,5 @@
+.. _iris_development_deprecations:
+
 Deprecations
 ************
 
@@ -87,6 +89,8 @@ Removing a public API
 The deprecated API should be removed and any corresponding documentation
 and/or example code should be removed/updated as appropriate.
 
+.. _iris_developer_future:
+
 Changing a default
 ------------------
 

diff --git a/docs/iris/src/developers_guide/release.rst b/docs/iris/src/developers_guide/release.rst
@@ -1,3 +1,5 @@
+.. _iris_development_releases:
+
 Releases
 ********
 

diff --git a/docs/iris/src/installing.rst b/docs/iris/src/installing.rst
@@ -1,3 +1,5 @@
+.. _installing_iris:
+
 ****************
 Installing Iris
 ****************

diff --git a/docs/iris/src/userguide/change_management_goals.txt b/docs/iris/src/userguide/change_management_goals.txt
@@ -0,0 +1,9 @@
+To reduce code maintenance problems to an absolute minimum, Iris applies
+defined change management procedures to ensure that :
+
+    * you can be confident that your code will still work with a future release
+
+    * you will be aware of future incompatibility problems in advance
+
+    * you can defer making code compatibility changes for some time, until it suits you
+
diff --git a/docs/iris/src/userguide/code_maintenance.rst b/docs/iris/src/userguide/code_maintenance.rst
@@ -0,0 +1,38 @@
+Code Maintenance
+================
+
+From a user point of view "code maintenance" means ensuring that your existing
+working code stays working, in the face of changes to Iris.
+
+
+Stability and Change
+---------------------
+
+In practice, as Iris develops, most users will want to periodically upgrade
+their installed version to access new features or at least bugfixes.
+
+This is obvious if you are still developing other code that uses Iris, or using
+code from other sources.  
+However, even if you have only legacy code that remains untouched, some code
+maintenance effort is probably still necessary :
+
+   * On the one hand, *in principle*, working code will go on working, as long
+     as you don't change anything else.
+
+   * However, such "version statis" can easily become a growing burden, if you
+     are simply waiting until an update becomes unavoidable :
+
+     Often, that will eventually occur when you need to update some other
+     software component, for a completely unconnected reason.
+
+
+Goals of Change Management
+--------------------------
+
+When you do upgrade Iris to a new version, you could potentially find
+that you need to rewrite your legacy code, simply to keep it working.
+
+.. include:: change_management_goals.txt
+
+To take advantage of this, you should read the basic change management
+recommendations laid out in :ref:`change_management`.
diff --git a/docs/iris/src/userguide/index.rst b/docs/iris/src/userguide/index.rst
@@ -36,4 +36,5 @@ User guide table of contents
    cube_statistics.rst
    cube_maths.rst
    citation.rst
+   code_maintenance.rst
    end_of_userguide.rst
diff --git a/docs/iris/src/whatsnew/index.rst b/docs/iris/src/whatsnew/index.rst
@@ -1,3 +1,5 @@
+.. _iris_whatsnew:
+
 What's new in Iris
 ******************