1.. _versioning: 2 3Versioning Scheme of skiboot 4============================ 5 6History 7------- 8For roughly the first six months of public life, skiboot just presented a 9git SHA1 as a version "number". This was "user visible" in two places: 10 111. ``/sys/firmware/opal/msglog`` 12 the familiar ``SkiBoot 71664fd-dirty starting...`` message 132. device tree: 14 ``/proc/device-tree/ibm,opal/firmware/git-id`` 15 16Builds were also referred to by date and by corresponding PowerKVM release. 17Clearly, this was unlikely to be good practice going forward. 18 19As of skiboot-4.0, this scheme has changed and we now present a version 20string instead. This better addresses the needs of everybody who is building 21OpenPower systems. 22 23 24Current practice 25---------------- 26The version string is constructed from a few places and is designed to 27be *highly* informative about what you're running. For the most part, 28it should be automatically constructed by the skiboot build system. The 29only times you need to do something is if you are a) making an upstream 30skiboot release or b) building firmware to release for your platform(s). 31 32OPAL/skiboot has several consumers, for example: 33 34* IBM shipping POWER8 systems with an FSP (FW810.XX and future) 35* OpenPower 36* OpenPower partners manufacturing OpenPower systems 37* developers, test and support needing to understand what code a system 38 is running 39 40and there are going to be several concurrent maintained releases in the wild, 41likely build by different teams of people at different companies. 42 43tl;dr; is you're likely going to see version numbers like this (for the 44hypothetical platforms 'ketchup' and 'mustard'): 45 46* ``skiboot-4.0-ketchup-0`` 47* ``skiboot-4.0-ketchup-1`` 48* ``skiboot-4.1-mustard-4`` 49* ``skiboot-4.1-ketchup-0`` 50 51If you see *extra* things on the end of the version, then you're running 52a custom build from a developer 53(e.g. ``skiboot-4.0-1-g23f147e-stewart-dirty-f42fc40`` means something to 54us - explained below). 55 56If you see less, for example ``skiboot-4.0``, then you're running a build 57directly out of the main git tree. Those producing OPAL builds for users 58must *not* ship like this, even if the tree is identical. 59 60Here are the components of the version string from master: :: 61 62 skiboot-4.0-1-g23f147e-debug-occ-stewart-dirty-f42fc40 63 ^ ^^^ ^ ^^^^^^^ ^-------^ ^ ^ ^^^^^^^ 64 | | | | | | | | 65 | | | | | \ / - 'git diff|sha1sum' 66 | | | | | \ / 67 | | | | | - built from a dirty tree of $USER 68 | | | | | 69 | | | | - $EXTRA_VERSION (optional) 70 | | | | 71 | | | - git SHA1 of commit built 72 | | | 73 | | - commits head of skiboot-4.0 tag 74 | | 75 | - skiboot version number ---\ 76 | >-- from the 'skiboot-4.0' git tag 77 - product name (always skiboot) ---/ 78 79 80When doing a release for a particular platform, you are expected to create 81and tag a branch from master. For the (hypothetical) ketchup platform which 82is going to do a release based on skiboot-4.0, you would create a tag 83'skiboot-4.0-ketchup-0' pointing to the same revision as the 'skiboot-4.0' tag 84and then make any additional modifications to skiboot that were not in the 4.0 85release. So, you could ship a skiboot with the following version string: :: 86 87 skiboot-4.0-ketchup-1 88 ^ ^^^ ^ ^ 89 | | | | 90 | | | - revision for this platform 91 | | | 92 | | | 93 | | - Platform name/version 94 | | 95 | - skiboot version number 96 | 97 - product name (always skiboot) 98 99This version string tells your users to expect what is in skiboot-4.0 plus 100some revisions for your platform. 101 102 103Practical Considerations 104------------------------ 105 106You MUST correctly tag your git tree for sensible version numbers to be 107generated. Look at the (generated) version.c file to confirm you're building 108the correct version number. You will need annotated tags (git tag -a). 109 110If your build infrastructure does *not* build skiboot from a git tree, you 111should specify SKIBOOT_VERSION as an environment variable (following this 112versioning scheme), otherwise the build will fail. 113