112 lines
4.2 KiB
ReStructuredText
112 lines
4.2 KiB
ReStructuredText
.. _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.
|