From patchwork Sun May 6 15:28:14 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stewart Smith X-Patchwork-Id: 909339 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [203.11.71.2]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 40f8xM48Nkz9s2k for ; Mon, 7 May 2018 01:36:39 +1000 (AEST) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 40f8xM1jSLzF0ZN for ; Mon, 7 May 2018 01:36:39 +1000 (AEST) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=linux.ibm.com (client-ip=148.163.156.1; helo=mx0a-001b2d01.pphosted.com; envelope-from=stewart@linux.ibm.com; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com [148.163.156.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 40f8wb2HDwzF0ZC for ; Mon, 7 May 2018 01:35:59 +1000 (AEST) Received: from pps.filterd (m0098404.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.22/8.16.0.22) with SMTP id w46FY8uW063918 for ; Sun, 6 May 2018 11:35:56 -0400 Received: from e14.ny.us.ibm.com (e14.ny.us.ibm.com [129.33.205.204]) by mx0a-001b2d01.pphosted.com with ESMTP id 2hssp77x4n-1 (version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT) for ; Sun, 06 May 2018 11:35:56 -0400 Received: from localhost by e14.ny.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Sun, 6 May 2018 11:35:55 -0400 Received: from b01cxnp23032.gho.pok.ibm.com (9.57.198.27) by e14.ny.us.ibm.com (146.89.104.201) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Sun, 6 May 2018 11:35:52 -0400 Received: from b01ledav003.gho.pok.ibm.com (b01ledav003.gho.pok.ibm.com [9.57.199.108]) by b01cxnp23032.gho.pok.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id w46FZqlG48890096 for ; Sun, 6 May 2018 15:35:52 GMT Received: from b01ledav003.gho.pok.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id EBC7FB204D for ; Sun, 6 May 2018 12:37:51 -0400 (EDT) Received: from birb.localdomain (unknown [9.80.222.56]) by b01ledav003.gho.pok.ibm.com (Postfix) with ESMTP id 9A7E8B2046 for ; Sun, 6 May 2018 12:37:51 -0400 (EDT) Received: by birb.localdomain (Postfix, from userid 1000) id DC61C4EC56C; Sun, 6 May 2018 10:28:17 -0500 (CDT) From: Stewart Smith To: skiboot@lists.ozlabs.org Date: Sun, 6 May 2018 10:28:14 -0500 X-Mailer: git-send-email 2.14.3 X-TM-AS-GCONF: 00 x-cbid: 18050615-0052-0000-0000-000002E9C351 X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00008981; HX=3.00000241; KW=3.00000007; PH=3.00000004; SC=3.00000258; SDB=6.01028386; UDB=6.00525395; IPR=6.00807519; MB=3.00020959; MTD=3.00000008; XFM=3.00000015; UTC=2018-05-06 15:35:54 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 18050615-0053-0000-0000-00005C96010C Message-Id: <20180506152816.7152-1-stewart@linux.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2018-05-06_06:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 impostorscore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1709140000 definitions=main-1805060163 Subject: [Skiboot] [PATCH 1/3] doc: Further document development and release process X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Signed-off-by: Stewart Smith --- 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@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