opendev/infra-specs
Code Issues Proposed changes

Overhaul instructions in README.rst for clarity

Browse Source 
The README.rst file included some rough instructions which may not
be entirely clear to newcomers to the community. Add some details so
that they don't need to guess where some things are.

Switch the recommendation for Story commit footers to Task so that
the corresponding story task will get its status updated by our
automation accordingly (we hyperlink these since the SB webclient
has grown support for routing them to the correct story, so
including a Story footer as well is now unnecessary).

Drop the step of providing the review link in a story comment since
our automation will do this if a Task footer is included in the
commit message.

Change-Id: I1dcba7c88efa20b542f30f3f34a043caba7a4c3f
This commit is contained in:
Jeremy Stanley 2018-12-06 13:48:13 +00:00
parent e1aed27bc2
commit 6bf2659085
1 changed files with 27 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
README.rst
View File

@ -11,19 +11,29 @@ Expected Work Flow
==================
1. Create a story in StoryBoard_ with a task affecting the
``infra-specs`` project.
2. Propose a change to infra-specs repository (ensure Story:<story
number> is in the commit message).
3. Leave a comment on the story with the Gerrit URL of the
specification.
4. Review happens on proposal by infra-core members and others.
5. When ready for final approval, bring forward the proposed item to
the infra meeting.
``openstack-infra/infra-specs`` project.
2. Propose a change to this repository and make sure ``Task:
#<taskid>`` for the corresponding story's initial task is
included as a footer in the commit message (see
``CONTRIBUTING.rst`` for relevant documentation links). This
change should also add an entry for the proposed spec document
in the ``Approved Design Specifications`` section of the
``doc/source/index.rst`` file.
3. Once proposed, members of the community provide feedback through
code review, and the specification should be revised until there
seems to be some reasonable consensus as to its fitness.
4. When ready for final approval, request addition of a call for
votes to the weekly `infra meeting`_ agenda.
5. If agreed by the meeting attendees, the chair will announce an
approval deadline before which members of the `Infrastructure
Council`_ are asked to cast their roll call votes on the proposal
under review.
Once a specification is approved...
1. Update story, copy summary text of specification to there.
2. Leave a comment to the git address of the specification.
1. Update the story, copying summary text of specification to there.
2. Leave a comment linking to the published URL of the specification
on the `specs site`_.
Revisiting Specifications
=========================
@ -32,4 +42,10 @@ need to revisit a specification because something changed, either we
now know more, or a new idea came in which we should embrace, we'll
manage this by proposing an update to the specification in question.
.. _Storyboard: https://storyboard.openstack.org
.. _Storyboard: https://storyboard.openstack.org/
.. _Gerrit: https://review.openstack.org/
.. _infra meeting:
http://eavesdrop.openstack.org/#Project_Infrastructure_Team_Meeting
.. _Infrastructure Council:
https://docs.openstack.org/infra/system-config/project.html#teams
.. _specs site: https://specs.openstack.org/openstack-infra/infra-specs/