From 6bf26590856199b6e0f1e983d31c3da20439eb24 Mon Sep 17 00:00:00 2001 From: Jeremy Stanley Date: Thu, 6 Dec 2018 13:48:13 +0000 Subject: [PATCH] Overhaul instructions in README.rst for clarity 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 --- README.rst | 38 +++++++++++++++++++++++++++----------- 1 file changed, 27 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 5eff210..00c3248 100644 --- a/README.rst +++ b/README.rst @@ -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: 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: + #`` 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/