From a47cdc585ba49b5473619650f64900f84086a7e0 Mon Sep 17 00:00:00 2001 From: Rabi Mishra Date: Wed, 20 Jan 2016 17:49:05 +0530 Subject: [PATCH] Add heat contribution guidelines This includes contribution guidelines for blueprints/specs and 'spec-lite'. Change-Id: I85106d2a3d68306b5d373b44d97473707d94a572 --- doc/source/contributing/blueprints.rst | 95 ++++++++++++++++++++++++++ doc/source/contributing/index.rst | 19 ++++++ doc/source/index.rst | 1 + 3 files changed, 115 insertions(+) create mode 100644 doc/source/contributing/blueprints.rst create mode 100644 doc/source/contributing/index.rst diff --git a/doc/source/contributing/blueprints.rst b/doc/source/contributing/blueprints.rst new file mode 100644 index 0000000000..78563bc19c --- /dev/null +++ b/doc/source/contributing/blueprints.rst @@ -0,0 +1,95 @@ +Blueprints and Specs +==================== + +The Heat team uses the `heat-specs +`_ repository for its +specification reviews. Detailed information can be found `here +`_. + +Please note that we use a `template +`_ +for spec submissions. It is not required to fill out all sections in the +template. + +Spec Notes +---------- + +There are occasions when a spec is approved and the code does not land in +the cycle it was targeted for. For these cases, the workflow to get the spec +into the next release is as below: + +* Anyone can propose a patch to heat-specs which moves a spec from the + previous release backlog into the new release directory. + +The specs which are moved in this way can be fast-tracked into the next +release. Please note that it is required to re-propose the spec for the new +release and it'll be evaluated based on the resources available and cycle +priorities. + +Heat Spec Lite +-------------- + +Lite specs are small feature requests tracked as Launchpad bugs, with status +'Wishlist' and tagged with 'spec-lite' tag. These allow for submission and +review of these feature requests before code is submitted. + +These can be used for small features that don’t warrant a detailed spec to be +proposed, evaluated, and worked on. The team evaluates these requests as it +evaluates specs. + +Once a `spec-lite` bug has been approved/triaged as a +Request for Enhancement(RFE), it’ll be targeted for a release. + +The workflow for the life of a spec-lite in Launchpad is as follows: + +* File a bug with a small summary of what the requested change is and + tag it as `spec-lite`. +* The bug is triaged and importance changed to `Wishlist`. +* The bug is evaluated and marked as `Triaged` to announce approval or + to `Won't fix` to announce rejection or `Invalid` to request a full + spec. +* The bug is moved to `In Progress` once the code is up and ready to + review. +* The bug is moved to `Fix Committed` once the patch lands. + +In summary: + ++--------------+-----------------------------------------------------------------------------+ +|State | Meaning | ++==============+=============================================================================+ +|New | This is where spec-lite starts, as filed by the community. | ++--------------+-----------------------------------------------------------------------------+ +|Triaged | Drivers - Move to this state to mean, "you can start working on it" | ++--------------+-----------------------------------------------------------------------------+ +|Won't Fix | Drivers - Move to this state to reject a lite-spec. | ++--------------+-----------------------------------------------------------------------------+ +|Invalid | Drivers - Move to this state to request a full spec for this request | ++--------------+-----------------------------------------------------------------------------+ + +The drivers team will discuss the following bug reports in IRC meetings: + +* `heat RFE's `_ +* `python-heatclient RFE's `_ + + +Lite spec Submission Guidelines +------------------------------- + +When a bug is submitted, there are two fields that must be filled: ‘summary’ +and ‘further information’. The ‘summary’ must be brief enough to fit in one +line. + +The ‘further information’ section must be a description of what you would like +to see implemented in heat. The description should provide enough details for +a knowledgeable developer to understand what is the existing problem and +what’s the proposed solution. + +Add `spec-lite` tag to the bug. + + +Lite spec from existing bugs +---------------------------- + +If there's an already existing bug that describes a small feature suitable for +a spec-lite, add a `spec-lite' tag to the bug. There is no need to create a new +bug. The comments and history of the existing bug are important for it's review. diff --git a/doc/source/contributing/index.rst b/doc/source/contributing/index.rst new file mode 100644 index 0000000000..7acea26b85 --- /dev/null +++ b/doc/source/contributing/index.rst @@ -0,0 +1,19 @@ +Heat Contribution Guidelines +============================ + +In the Contributions Guide, you will find documented policies for +developing with heat. This includes the processes we use for +blueprints and specs, bugs, contributor onboarding, core reviewer +memberships, and other procedural items. + +Policies +-------- +.. toctree:: + :maxdepth: 3 + + blueprints +.. bugs + contributor-onboarding + core-reviewers + gate-failure-triage + code-reviews diff --git a/doc/source/index.rst b/doc/source/index.rst index 8038d1f1f9..dc2bf8f39a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -70,6 +70,7 @@ Developing Heat .. toctree:: :maxdepth: 1 + contributing/index getting_started/on_devstack architecture pluginguide