[Skiboot] [PATCH 1/3] doc: Further document development and release process
Stewart Smith
stewart at linux.ibm.com
Mon May 7 01:28:14 AEST 2018
Signed-off-by: Stewart Smith <stewart at linux.ibm.com>
---
CONTRIBUTING.md | 6 +-
doc/conf.py | 15 ++--
doc/index.rst | 14 +++-
doc/process/CONTRIBUTING.md | 1 +
doc/process/dev-release-process.rst | 110 +++++++++++++++++++++++++++++
doc/{ => process}/stable-skiboot-rules.rst | 0
doc/{ => process}/versioning.rst | 0
doc/requirements.txt | 2 +
8 files changed, 136 insertions(+), 12 deletions(-)
create mode 120000 doc/process/CONTRIBUTING.md
create mode 100644 doc/process/dev-release-process.rst
rename doc/{ => process}/stable-skiboot-rules.rst (100%)
rename doc/{ => process}/versioning.rst (100%)
create mode 100644 doc/requirements.txt
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 93ec19437f22..e381bb312e3b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,13 +9,9 @@ the mailing list ( skiboot at lists.ozlabs.org - subscribe by
going to https://lists.ozlabs.org/listinfo/skiboot )
While we do use GitHub Issues, patches are accepted via the mailing list.
-We use GitHub Issues and Pull Requests for tracking contributions. We
-expect participants to adhere to the GitHub Community Guidelines (found
+We expect participants to adhere to the GitHub Community Guidelines (found
at https://help.github.com/articles/github-community-guidelines/ ).
-If you are unable or unwilling to use GitHub, we can accept contributions
-via the mailing list.
-
All contributions should have a Developer Certificate of Origin (see below).
Development Environment
diff --git a/doc/conf.py b/doc/conf.py
index 9fdb2e8678c0..d60055ebebe7 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -19,6 +19,7 @@ import os
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('.'))
+from recommonmark.parser import CommonMarkParser
# -- General configuration ------------------------------------------------
@@ -34,16 +35,20 @@ def setup(app):
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = []
+extensions = ['sphinx.ext.intersphinx',
+ 'sphinx.ext.githubpages']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
-# The suffix of source filenames.
-source_suffix = '.rst'
+source_parsers = {
+ '.md': CommonMarkParser,
+}
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = ['.rst', '.md']
# The master toctree document.
master_doc = 'index'
diff --git a/doc/index.rst b/doc/index.rst
index d350acc3a59f..660085e05abb 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -16,20 +16,30 @@ Overview
overview
opal-spec
+Development Process
+===================
+
+.. toctree::
+ :maxdepth: 2
+
+ process/dev-release-process
+ process/CONTRIBUTING.md
+ process/stable-skiboot-rules
+ process/versioning
+
Developer Guide and Internals
=============================
.. toctree::
:maxdepth: 2
+ CONTRIBUTING.md
console-log
error-logging
bmc
gcov
memory
nvlink
- stable-skiboot-rules
- versioning
pci
pci-slot
xscom-node-bindings
diff --git a/doc/process/CONTRIBUTING.md b/doc/process/CONTRIBUTING.md
new file mode 120000
index 000000000000..f939e75f21a8
--- /dev/null
+++ b/doc/process/CONTRIBUTING.md
@@ -0,0 +1 @@
+../../CONTRIBUTING.md
\ No newline at end of file
diff --git a/doc/process/dev-release-process.rst b/doc/process/dev-release-process.rst
new file mode 100644
index 000000000000..83731e9118f8
--- /dev/null
+++ b/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/doc/stable-skiboot-rules.rst b/doc/process/stable-skiboot-rules.rst
similarity index 100%
rename from doc/stable-skiboot-rules.rst
rename to doc/process/stable-skiboot-rules.rst
diff --git a/doc/versioning.rst b/doc/process/versioning.rst
similarity index 100%
rename from doc/versioning.rst
rename to doc/process/versioning.rst
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 000000000000..085b3a792a7b
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,2 @@
+sphinx
+recommonmark
--
2.14.3
More information about the Skiboot
mailing list