doc: Further document development and release process

Signed-off-by: Stewart Smith <stewart@linux.ibm.com>

8 files changed, 136 insertions, 12 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 93ec194..e381bb3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -9,13 +9,9 @@ the mailing list ( skiboot@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 9fdb2e8..d60055e 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 d350acc..660085e 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 0000000..f939e75
--- /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 0000000..83731e9
--- /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
index c0d4362..c0d4362 100644
--- a/doc/stable-skiboot-rules.rst
+++ b/doc/process/stable-skiboot-rules.rst
diff --git a/doc/versioning.rst b/doc/process/versioning.rst
index b802e06..b802e06 100644
--- a/doc/versioning.rst
+++ b/doc/process/versioning.rst
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000..085b3a7
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,2 @@
+sphinx
+recommonmark