diff options
Diffstat (limited to 'roms/skiboot/doc/process/versioning.rst')
| -rw-r--r-- | roms/skiboot/doc/process/versioning.rst | 112 |
1 files changed, 112 insertions, 0 deletions
diff --git a/roms/skiboot/doc/process/versioning.rst b/roms/skiboot/doc/process/versioning.rst new file mode 100644 index 000000000..b802e06d8 --- /dev/null +++ b/roms/skiboot/doc/process/versioning.rst @@ -0,0 +1,112 @@ +.. _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. |