Address follow-up comments in contributor guide for specs
We recently merged a document for describing how to write
specifications and open bug reports to track feature work:
I5dbf6f81058de3f2a64a95e4cf34a1279a49c5dd
This commit addresses some follow on comments from the initial review,
namely:
* removes copyright dates
* reorders opening RFE bugs before proposing specs to be consistent
with the specification template
* fixes links to be more descriptive
* clarifies some details on the spec writing process
Change-Id: I883beed7c9b731ec69d169702b03652c98307f85
This commit is contained in:
Lance Bragstad
parent
8d84ec2420
commit
3111b8b9bb
|
|
@ -1,7 +1,4 @@
|
|||
..
|
||||
Copyright 2011-2012 OpenStack Foundation
|
||||
All Rights Reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
|
@ -19,10 +16,45 @@ Proposing Features
|
|||
==================
|
||||
|
||||
Requests for enhancements or new features must follow a process that requires
|
||||
using specifications and bug reports. You can find the repository
|
||||
`here <http://git.openstack.org/cgit/openstack/keystone-specs>`_. We publish
|
||||
the contents at
|
||||
`specs.openstack.org <http://specs.openstack.org/openstack/keystone-specs/>`_.
|
||||
using bug reports and specifications. We publish the contents of the
|
||||
`keystone-specs repository
|
||||
<https://git.openstack.org/cgit/openstack/keystone-specs>`_ at
|
||||
`specs.openstack.org <https://specs.openstack.org/openstack/keystone-specs/>`_.
|
||||
|
||||
RFE Bug Reports
|
||||
===============
|
||||
|
||||
All code, documentation, and tests implementing a feature should be tracked.
|
||||
To do this, we use Launchpad bug reports. We use bug reports because the
|
||||
OpenStack review infrastructure has existing tooling that groups patches based
|
||||
on commit message syntax. When you propose a patch that is related to a bug or
|
||||
a feature, the OpenStack Infrastructure bot automatically links the patch as a
|
||||
comment in the bug report. Comments are also immutable, allowing us to track
|
||||
long-running initiatives without losing context.
|
||||
|
||||
To create an RFE bug report, file a bug against the appropriate project. For
|
||||
example, if we were to create an RFE bug report for supporting a new Foobar API
|
||||
within keystone, we'd `open <https://bugs.launchpad.net/keystone/+filebug>`_
|
||||
that RFE against the keystone project. The title should start with "RFE: ",
|
||||
followed by a snippet of the feature or enhancement. For example, "RFE:
|
||||
Implement a Foobar API". The description should be short. Since we use
|
||||
specifications for details, we don't need to duplicate information in the body
|
||||
of the bug report. After you create the bug, you can tag it with the "rfe" tag,
|
||||
which helps people filter feature work from other bug reports. Finally, if your
|
||||
specification has already merged, be sure to include a link to it as a comment.
|
||||
If it hasn't, you can propose, or re-propose, your specification with
|
||||
``Partial-Bug:`` followed by the bug number, at the bottom of your commit
|
||||
message. The OpenStack Infrastructure bot automatically updates the RFE bug
|
||||
report you just created with a link to the proposed specification. The
|
||||
specification template explains how to link to RFE bug reports, which should
|
||||
prompt you to open your RFE bug prior to proposing your specification.
|
||||
|
||||
If your feature is broken up into multiple commits, make sure to include
|
||||
``Partial-Bug`` in your commit messages. Additionally, use ``Closes-Bug`` in
|
||||
the last commit implementing the feature. This process ensures all patches
|
||||
written for a feature are tracked in the bug report, making it easier to audit.
|
||||
If you miss the opportunity to use the ``Closes-Bug`` tag and your feature work
|
||||
is complete, set the bug status to "Fix Committed".
|
||||
|
||||
Specifications
|
||||
==============
|
||||
|
|
@ -47,8 +79,10 @@ solutions, security concerns, among other things. These sections are meant to
|
|||
prompt you to think about how your feature impacts users, operators,
|
||||
developers, related projects, and the existing code base. The template acts as
|
||||
a guide, so if you need to inject an ad-hoc section to describe additional
|
||||
details of your feature, don't hesitate to add one. Propose your specification
|
||||
for review when you're ready for feedback:
|
||||
details of your feature, don't hesitate to add one. Do not remove sections from
|
||||
the template that do not apply to your specification. Instead, simply explain
|
||||
why your proposed change doesn't have an impact on that aspect of the template.
|
||||
Propose your specification for review when you're ready for feedback:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
|
@ -65,36 +99,3 @@ it takes longer than you anticipated for your specification to get feedback. A
|
|||
specification must have support (+2) from at least two keystone-spec core
|
||||
reviewers and it is typically approved (+Workflow) by the PTL, in order to be
|
||||
formally accepted.
|
||||
|
||||
RFE Bug Reports
|
||||
===============
|
||||
|
||||
Once a specification is approved, we need to track the work to implement it. To
|
||||
do this, we use Launchpad bug reports. We use bug reports because the OpenStack
|
||||
review infrastructure has existing tooling that groups patches based on commit
|
||||
message syntax. When you propose a patch that is related to a bug or a feature,
|
||||
the OpenStack Infrastructure bot automatically links the patch as a comment in
|
||||
the bug report. Comments are also immutable, allowing us to track long-running
|
||||
initiatives without losing context.
|
||||
|
||||
To create an RFE bug report, file a bug against the appropriate project. For
|
||||
example, if we were to create an RFE bug report for the example specification
|
||||
we wrote for keystone above, we'd
|
||||
`open <https://bugs.launchpad.net/keystone/+filebug>`_ that RFE against the
|
||||
keystone project. The title should start with "RFE: ", followed by a snippet
|
||||
of the feature or enhancement. For example, "RFE: Implement a foobar API". The
|
||||
description should be short. Since we use specifications for details, we don't
|
||||
need to duplicate information in the body of the bug report. After you create
|
||||
the bug, you can tag it with the "rfe" tag, which helps people filter feature
|
||||
work from other bug reports. Finally, if your specification has already merged,
|
||||
be sure to include a link to it as a comment. If it hasn't, you can re-propose
|
||||
your specification with ``Partial-Bug:`` followed by the bug number, at the
|
||||
bottom of your commit message. The OpenStack Infrastructure bot automatically
|
||||
updates your RFE bug report with a link to the proposed specification.
|
||||
|
||||
If your feature is broken up into multiple commits, make sure to include
|
||||
``Partial-Bug`` in your commit messages. Additionally, use ``Closes-Bug`` in
|
||||
the last commit implementing the feature. This process ensures all patches
|
||||
written for a feature are tracked in the bug report, making it easier to audit.
|
||||
If you miss the opportunity to use the ``Closes-Bug`` tag and your feature work
|
||||
is complete, set the bug status to "Fix Committed".
|
||||
|
|
|
|||
Loading…
Reference in New Issue