Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

4 files changed, 307 insertions, 0 deletions

diff --git a/roms/skiboot/doc/process/CONTRIBUTING.md b/roms/skiboot/doc/process/CONTRIBUTING.md
new file mode 120000
index 000000000..f939e75f2
--- /dev/null
+++ b/roms/skiboot/doc/process/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../CONTRIBUTING.md
\ No newline at end of file
diff --git a/roms/skiboot/doc/process/dev-release-process.rst b/roms/skiboot/doc/process/dev-release-process.rst
new file mode 100644
index 000000000..83731e911
--- /dev/null
+++ b/roms/skiboot/doc/process/dev-release-process.rst
@@ -0,0 +1,110 @@
+.. _release-process:
+
+Development and Release Process
+===============================
+
+Skiboot follows the release cycle of `op-build`, so that each new op-build
+has a new stable skiboot. Currently, this means that we release once every
+six weeks (or so). Our *goal* is to have roughly the first 4 weeks of a
+6 week cycle open for merging new features, and reserving the final two
+weeks for stabilisation efforts after the first -rcX release.
+
+It is *strongly* preferred to have new features (especially new APIs and
+device tree bindings) to come in *early* in the cycle.
+
+Once the final release is cut, the :ref:`stable-rules` process takes over.
+
+Our process has evolved, and will so into the future. It's inspired by the
+Linux process, but not a slave to it. For example, there is currently not
+the volume of patches to justify a next tree.
+
+Here's how some of the recent (at time of writing) releases have gone:
+
+============= =========
+Date          Release
+============= =========
+Oct 31st 2017 v5.9
+Feb 6th 2018  v5.10-rc1
+Feb 9th 2018  v5.10-rc2
+Feb 15th 2018 v5.10-rc3
+Feb 21st 2018 v5.10-rc4
+Feb 23rd 2018 v5.10
+Mar 28th 2018 v5.11-rc1
+Apr 6th 2018  v5.11
+============= =========
+
+Lifecycle of a patch
+--------------------
+
+Roughly speaking, a patch has the following lifecycle:
+
+- Design
+
+  It is best to do design work in the open, although sometimes this is hard
+  when upcoming unannounced hardware is involved. Often, it can be useful to
+  post an RFC design or patch to encourage discussion. This is especially
+  useful when designing new OPAL APs or device tree bindings. Never be afraid
+  to send a patch (or series of patches) as RFC (Request for Comment) with
+  whatever disclaimer you deem appropriate.
+
+  Once you have a design, sharing it is an important part of the process of
+  getting the applicable code upstream. Different perspectives are important
+  in coming to elegant solutions, as is having more than one person understand
+  the reasoning behind design decisions.
+- Review and Test
+
+  Once you think your patch is a state suitable for merging, send it to the
+  mailing list for others to review and test. Using `git format-patch` and
+  `git send-email` is good practice to ensure your patches survive being sent
+  to the list. Ensure you have followed `CONTRIBUTING.md` and have your
+  Signed-off-by present on your patches (`git commit -s` will add this for you).
+
+  It is good practice to solicit review from an expert in the area of code
+  you're modifying. A reviewer will add their Reviewed-by or Acked-by tags as
+  replies, as will anybody testing it add Tested-by. The aim of reviewing and
+  testing code before we merge it is to limit any problems to the smallest
+  number of people possible, only merging code we are collectively confident
+  that will *improve* life for all users and developers.
+- Merged to master
+
+  The maintainer as merged your patches to the development tree (the 'master'
+  git branch). Soon after this, many more people are going to be running your
+  code, so good review and testing helps ensure your inbox isn't flooded with
+  bug reports.
+
+  If your patch has also been sent to the stable tree, it's possible it also
+  gets merged there soonafter.
+- Stable release
+
+  Once a stable release is made, it's likely that your code makes its way into
+  vendor's firmware releases via their test cycles.
+- Bug fixes and maintenance
+
+  Bugs are a fact of life, sometimes in our own code, sometimes in others, and
+  sometimes in hardware. After your patch is accepted, being available for
+  input on possible bugs found and possible fixes is invaluable so that all
+  can ship high quality firmware.
+
+
+On closed source branches and forks
+-----------------------------------
+
+Even though the license that skiboot is distributed under does *allow* you
+to keep your changes private, we (the skiboot developers) cannot in any way
+provide support on the resulting code base.
+
+Additionally, the broader PowerPC Linux community has neither the capacity,
+time, or resources to support Linux running on such closed source forks.
+The kernel developers have said that patches to the kernel to support or
+work around closed skiboot changes will *not* be accepted upstream.
+
+If you keep your changes private, you are *entirely* on your own.
+
+License
+-------
+
+Skiboot is licensed under the Apache 2.0 license (see the LICENSE file in the
+source tree for the full text).
+
+Portions (e.g. our libc, CCAN modules we use) are made available under a CC0, BSD,
+or BSD-MIT license (see LICENSE files for specifics).
diff --git a/roms/skiboot/doc/process/stable-skiboot-rules.rst b/roms/skiboot/doc/process/stable-skiboot-rules.rst
new file mode 100644
index 000000000..38bae8f4e
--- /dev/null
+++ b/roms/skiboot/doc/process/stable-skiboot-rules.rst
@@ -0,0 +1,84 @@
+.. _stable-rules:
+
+======================================
+Skiboot stable tree rules and releases
+======================================
+
+If you're at all familiar with the Linux kernel stable trees, this should
+seem fairly familiar.
+
+The purpose of a -stable tree is to give vendors a stable base to create
+firmware releases from and to incorporate into service packs. New stable
+releases contain critical fixes only.
+
+As a general rule, on the most recent skiboot release gets a maintained
+-stable tree. If you wish to maintain an older tree, speak up! For example,
+with my IBMer hat on, we'll maintain branches that we ship in products.
+
+What patches are accepted?
+--------------------------
+
+* Patches must be obviously correct and tested
+
+  * A Tested-by signoff is *important*
+* A patch must fix a real bug
+* No trivial patches, such fixups belong in main branch
+* Not fix a purely theoretical problem unless you can prove how
+  it's exploitable
+* The patch, or an equivalent one, must already be in master
+
+  * Submitting to both at the same time is okay, but backporting is better
+
+HOWTO submit to stable
+----------------------
+Two ways:
+
+1. Send patch to the skiboot-stable@lists.ozlabs.org list with
+   "[PATCH <stable version>]" in subject
+
+   * This targets the patch *ONLY* to the stable branch.
+
+     * Such commits will *NOT* be merged into master.
+   * Use this when:
+
+     a. cherry-picking a fix from master
+     b. fixing something that is only broken in stable
+     c. fix in stable needs to be completely different than in master
+
+     If b or c: explain why.
+   * If cherry-picking, include the following at the top of your
+     commit message: ::
+
+       commit <sha1> upstream.
+   * If the patch has been modified, explain why in description.
+
+2. Add "Cc: skiboot-stable@lists.ozlabs.org" above your Signed-off-by line
+   when sending to skiboot@
+
+   * This targets the patch to master and stable.
+   * You can target a patch to a specific stable tree with: ::
+
+      Cc: skiboot-stable@lists.ozlabs.org # 5.1.x
+
+     and that will target it to the 5.1.x branch.
+   * You can ask for prerequisites to be cherry-picked: ::
+
+        Cc: skiboot-stable@lists.ozlabs.org # 5.1.x 55ae15b Ensure we run pollers in cpu_wait_job()
+        Cc: skiboot-stable@lists.ozlabs.org # 5.1.x
+
+     Which means:
+
+       1. please ``git cherry-pick 55ae15b``
+       2. then apply this patch to 5.1.x".
+
+Trees
+-----
+
+* https://github.com/open-power/skiboot/ (or via ssh at ``git@github.com:open-power/skiboot.git`` )
+
+  * (branches are skiboot-X.Y.x - e.g. skiboot-5.1.x)
+
+* Some stable versions may last longer than others
+
+  * So there may be skiboot-5.1.x and skiboot-5.2.x actively maintained
+    and skiboot-5.1.x could possibly outlast skiboot-5.2.x
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.