Add documentation describing skiboot versioning

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>

1 files changed, 107 insertions, 0 deletions

diff --git a/doc/versioning.txt b/doc/versioning.txt
new file mode 100644
index 0000000..2bbad69
--- /dev/null
+++ b/doc/versioning.txt
@@ -0,0 +1,107 @@
+Versioning Scheme of skiboot
+============================
+
+History
+-------
+For roughly the first six months of public life, skiboot just presented a
+git SHA1 as a version "number". This was "user visible" in two places:
+1) /sys/firmware/opal/msglog
+   the familiar "SkiBoot 71664fd-dirty starting..." message
+2) device tree:
+   /proc/device-tree/ibm,opal/firmware/git-id
+
+Builds were also referred to by date and by corresponding PowerKVM release.
+Clearly, this was unlikely to be good practice going forward.
+
+As of skiboot-4.0, this scheme has changed and we now present a version
+string instead. This better addresses the needs of everybody who is building
+OpenPower systems.
+
+
+Current practice
+----------------
+The version string is constructed from a few places and is designed to
+be *highly* informative about what you're running. For the most part,
+it should be automatically constructed by the skiboot build system. The
+only times you need to do something is if you are a) making an upstream
+skiboot release or b) building firmware to release for your platform(s).
+
+OPAL/skiboot has several consumers, for example:
+- IBM shipping POWER8 systems with an FSP (FW810.XX and future)
+- OpenPower
+- OpenPower partners manufacturing OpenPower systems
+- developers, test and support needing to understand what code a system
+  is running
+
+and there are going to be several concurrent maintained releases in the wild,
+likely build by different teams of people at different companies.
+
+tl;dr; is you're likely going to see version numbers like this (for the
+hypothetical platforms 'ketchup' and 'mustard'):
+skiboot-4.0-ketchup-0
+skiboot-4.0-ketchup-1
+skiboot-4.1-mustard-4
+skiboot-4.1-ketchup-0
+
+If you see *extra* things on the end of the version, then you're running
+a custom build from a developer
+(e.g. 'skiboot-4.0-1-g23f147e-stewart-dirty-f42fc40' means something to
+us - explained below).
+
+If you see less, for example 'skiboot-4.0', then you're running a build
+directly out of the main git tree. Those producing OPAL builds for users
+must *not* ship like this, even if the tree is identical.
+
+Here are the components of the version string from master:
+
+skiboot-4.0-1-g23f147e-debug-occ-stewart-dirty-f42fc40
+^       ^^^ ^  ^^^^^^^ ^-------^    ^      ^   ^^^^^^^
+|        |  |     |        |        |      |      |
+|        |  |     |        |         \    /        - 'git diff|sha1sum'
+|        |  |     |        |          \  /
+|        |  |     |        |            - built from a dirty tree of $USER
+|        |  |     |        |
+|        |  |     |         - $EXTRA_VERSION (optional)
+|        |  |     |
+|        |  |      - git SHA1 of commit built
+|        |  |
+|        |   - commits head of skiboot-4.0 tag
+|        |
+|         - skiboot version number ---\
+|                                      >--  from  the 'skiboot-4.0' git tag
+ - product name (always skiboot)   ---/
+
+
+When doing a release for a particular platform, you are expected to create
+and tag a branch from master. For the (hypothetical) ketchup platform which
+is going to do a release based on skiboot-4.0, you would create a tag
+'skiboot-4.0-ketchup-0' pointing to the same revision as the 'skiboot-4.0' tag
+and then make any additional modifications to skiboot that were not in the 4.0
+release. So, you could ship a skiboot with the following version string:
+
+skiboot-4.0-ketchup-1
+^       ^^^ ^       ^
+|        |  |       |
+|        |  |        - revision for this platform
+|        |  |      
+|        |  |
+|        |   - Platform name/version
+|        |
+|         - skiboot version number
+|
+ - product name (always skiboot)
+
+This version string tells your users to expect what is in skiboot-4.0 plus
+some revisions for your platform.
+
+
+Practical Considerations
+------------------------
+
+You MUST correctly tag your git tree for sensible version numbers to be
+generated. Look at the (generated) version.c file to confirm you're building
+the correct version number. You will need annotated tags (git tag -a).
+
+If your build infrastructure does *not* build skiboot from a git tree, you
+should specify SKIBOOT_VERSION as an environment variable (following this
+versioning scheme), otherwise the build will fail.