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