.. _versioning:

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.