From b3ba9020bd19e829a02bc0173ebb45f436e5cf68 Mon Sep 17 00:00:00 2001 From: Lana Brindley Date: Mon, 25 Jul 2016 13:17:48 +1000 Subject: [PATCH] Contributor Guide miscellaneous process updates Working from the Newton docs deliverables list from the Austin Summit: * Who should follow this guide? * Introduction of a minimal review time? * Section about contribution recommendations: what devs should contribute, review expectations of docs, expected turn-around time, etc. * How to deprecate/remove docs? * Also define which are continuous-release, versioned, etc. Change-Id: I9df39977a8e9ca81960c6ee8840e864054d9b1d2 --- .../source/blueprints-and-specs.rst | 12 ++ doc/contributor-guide/source/docs-review.rst | 109 ++++++++++++------ doc/contributor-guide/source/index.rst | 4 +- .../source/quickstart/developers.rst | 28 +++++ .../source/quickstart/first-timers.rst | 2 +- .../source/quickstart/new-projects.rst | 11 +- 6 files changed, 122 insertions(+), 44 deletions(-) diff --git a/doc/contributor-guide/source/blueprints-and-specs.rst b/doc/contributor-guide/source/blueprints-and-specs.rst index 5e05ea2131..af824e2c34 100644 --- a/doc/contributor-guide/source/blueprints-and-specs.rst +++ b/doc/contributor-guide/source/blueprints-and-specs.rst @@ -51,6 +51,18 @@ To patch for the release-specific documentation, you should generally patch to master branch with "backport: xxxx" (for example, backport: kilo) in the commit message. +For these guides, the docs.openstack.org site defaults to the current release, +with the previous two releases being available under the ``More Releases +& Languages`` drop-down. At release time, the documentation release team +will update the default page to the new release, and remove the link to +the oldest release. These docs are still available online for people who +have direct URLs to the content, but they are no longer linked from the +main site. For books written in DocBook XML, these old versions are clearly +marked with the release name in red down the left-hand margin. We are +currently developing a similar method of marking older books written in RST. +The core team tracks usage of older versions, and as usage falls, can +remove them entirely. + Installation Guides ------------------- diff --git a/doc/contributor-guide/source/docs-review.rst b/doc/contributor-guide/source/docs-review.rst index 9785a4ec15..83c6bb5909 100644 --- a/doc/contributor-guide/source/docs-review.rst +++ b/doc/contributor-guide/source/docs-review.rst @@ -9,14 +9,13 @@ Reviewing documentation docs-review-guidelines.rst -OpenStack documentation is treated like code. -We follow the standard code review process. -To see what documentation changes are ready for review, use the -`Documentation Program Dashboard `_. -It is organized in groupings based on the audience for the documentation. -To see current proposed changes, make sure you register and -log into https://review.openstack.org. -For more details on the review process, see `Code Review +OpenStack documentation is treated in the same way as code, and follows the +standard code review process. To see what documentation changes are ready for +review, use the `Documentation Program Dashboard +`_. It is organized in groups based on the +audience for the documentation. To see current proposed changes, make sure +you register and log into https://review.openstack.org. For more details on +the review process, see `Code Review `_. Repositories and core team @@ -33,8 +32,8 @@ special rules apply: * security-doc: has a separate core team consisting of Docs team members and Security team members. The rule here is that each patch needs an approval by a Docs core and a Security core. -* training-guides: has a separate core team. -* training-labs: has a separate core team. +* training-guides and training-labs: have separate core teams, but also + includes the openstack-manuals core team. The current list of docs cores for openstack-manuals can be found at https://review.openstack.org/#/admin/groups/30,members. @@ -78,32 +77,23 @@ Once done, follow the steps below to submit a patch review. `Peer Review `_ -Achieving a core reviewer status -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Achieving core reviewer status +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Core reviewers are able to +2 and merge content into the projects they -have the core status in. Core status is granted to **those who have not +have core status in. Core status is granted to those who have not only done a sufficient quantity of reviews, but who also have shown care -and wisdom in those reviews**. Becoming a core reviewer also carries with -it a responsibility: you are now the **guardian of the gate**, and -it is up to the core team to ensure that nothing unfavorable gets through, -without discouraging contributions. -The core reviewer's role is complex, and having a great core team is -crucial to the success of any OpenStack project. +and wisdom in those reviews. -With great power comes great responsibility. - -For this reason, we want to ensure that we have a suitably small team of -core reviewers, but that each core reviewer we have is active and engaged. -In order to do this, we changed the process for achieving core reviewer -status to ensure there was a good mix between a statistics-based and -nomination-based approach. This means a couple of things: - -* The core team changes slightly faster than before, with inactive core - team members being removed and new, active core team members being added - on a more regular basis. -* Now, the existing core team can act faster on recognizing valuable team - members. +The core reviewer's role is complex, and having a great core team is crucial +to the success of any OpenStack project. The documentation team aims to have +a suitably small team of core reviewers, with each core reviewer being active +and engaged. The process for appointing core reviewers aims to ensure there +is a good mix between a statistics-based and nomination-based approach. To +this end, the core team changes relatively quickly, with inactive core team +members being removed and new, active core team members being added on a +regular basis. This also allows the existing core team to act quickly on +recognizing valuable team members. The process is: @@ -117,9 +107,62 @@ The process is: * The PTL then consults the existing core team with a list of names to be removed from and added to the core list. Once an agreement is reached, the changes are made and advertised to the main documentation mailing list. - Cores who are being removed will be contacted personally before removal. + Cores who are being added or removed will be contacted personally before + changes are made. * Existing core team members can nominate a new core member at any time, with a justification sent to the existing core team: openstack-doc-core@lists.launchpad.net. Three +1 votes from other existing core team members must be achieved for approval. + +Core reviewer responsibilities +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Becoming a core reviewer carries with it a responsibility: you are now the +guardian of the gate, and it is up to the core team to ensure that nothing +unfavorable gets through, without discouraging contributions. + +General instructions for being a core reviewer are located in the +`Core Reviewer's Guide +`_. +This section is for openstack-manuals core reviewers. + +In almost all cases, patches can be merged with at least one +1 vote, and +two +2 votes. The second +2 vote is usually the one that will also merge the +patch (often referred to as a +2A vote). There are very few exceptions to +this rule within documentation, the main one being extraordinary +circumstances where a patch has broken the build and a fix is required very +quickly. In this case, you should still seek out another core team member +if possible, and make some kind of contact with the PTL so that they are +aware of the problem. + +If you are a core team member, but don't feel you understand the subject +matter of a patch well enough to confidently merge it, vote +1 and mention +your reasons. Being overly cautious is better than being overly confident. + +Try not to merge a patch too quickly, even if it strictly has the correct +number of votes. Allowing a patch to sit for a couple of days is generally +helpful, in order to ensure enough people have seen the change. It can also +be valuable to add speciality team leads or other subject matter experts +to patches where you feel more specialized knowledge is required to make +a good decision. + +A note on review rigor: There are very few guidelines about what a good patch +looks like, but the general approach is that if it's technically accurate and +better than the existing content, then it should be approved. The main things +to look for: + +* General spelling and grammar. +* Technical accuracy. Where possible, test commands on your own VM to make + sure they're accurate. Check any related bugs and mailing list conversation + to see if there's anything else you might need to take into account. +* The 'is it better than what we have already' test. Check the diff, or look + at the current document on the doc site, and determine if the changes are + an improvement. Provide corrections in-line for the author to fix if + there's more than a couple of errors. If there's just one or two really + minor changes (or in a situation where the writer has explicitly asked for + editorial assistance), consider checking out the patch and editing it + yourself. + +And, as a final note: Be nice. Be helpful. It is your job as a core reviewer +to help people get patches merged, not block them. diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst index 7ca7f724ea..2630eeb579 100644 --- a/doc/contributor-guide/source/index.rst +++ b/doc/contributor-guide/source/index.rst @@ -5,8 +5,8 @@ OpenStack Documentation Contributor Guide Abstract ~~~~~~~~ -This guide provides detailed instructions on the documentation contribution -workflow and conventions to be considered by all contributors. Please +This guide provides detailed instructions on the contribution workflow and +conventions to be considered by all documentation contributors. Please follow these guidelines to keep the documentation structure, style, and syntax consistent. diff --git a/doc/contributor-guide/source/quickstart/developers.rst b/doc/contributor-guide/source/quickstart/developers.rst index cc0be8c558..ddfefdbd38 100644 --- a/doc/contributor-guide/source/quickstart/developers.rst +++ b/doc/contributor-guide/source/quickstart/developers.rst @@ -13,3 +13,31 @@ Many of these types of changes are handled automatically by ``openstack-doc-tools``, and published to the Configuration Reference and Command-Line Reference. For more information about these automated tools, see the :ref:`doc-tools` chapter. + +If you are contributing documentation to the main openstack-manuals +repository, there are a few things you can do to help your patch merge +quickly and easily: + +* Contact your project's documentation `cross-project liaison + `_. + They can help you with finding the appropriate book to add your patch, and + the relevant people to review your patch once you have written it. +* If you are not confident in your written English skills, feel free to + add a note that you are happy to have editorial assistance on the patch. + This will encourage writers to check out your patch and correct any + spelling or grammar mistakes, rather than just adding comments for you + to fix yourself. +* If you know which book you want to modify, get in contact with the + appropriate speciality team, listed at :doc:`../team-structure`. They + can help you determine where the content should live, and also give you + details about upcoming changes to the architecture of those books that + might affect your new documentation. +* If you are intending to make a very large change, such as an entirely + new section or chapter, or documenting a new project, the core team might + ask you to create a blueprint and specification for the change. If you are + unsure whether your change will require a blueprint or specification, ask + on the mailing list for guidance. +* If you want to create a new Installation Tutorial for your big tent + project, see :doc:`../project-install-guide`. +* Remember, you can always contact the documentation team through our mailing + list, or on IRC. diff --git a/doc/contributor-guide/source/quickstart/first-timers.rst b/doc/contributor-guide/source/quickstart/first-timers.rst index 446dbdae42..70f8166e9e 100644 --- a/doc/contributor-guide/source/quickstart/first-timers.rst +++ b/doc/contributor-guide/source/quickstart/first-timers.rst @@ -5,7 +5,7 @@ First timers ============ One of the best ways to start contributing to OpenStack documentation -is to walk through the Installation guide and complete it by hand. +is to walk through the Installation Tutorial and complete it by hand. Keep notes as you go, and offer suggestions for improvement by filing documentation bugs at Launchpad. diff --git a/doc/contributor-guide/source/quickstart/new-projects.rst b/doc/contributor-guide/source/quickstart/new-projects.rst index 546b1ca9a3..d74af72362 100644 --- a/doc/contributor-guide/source/quickstart/new-projects.rst +++ b/doc/contributor-guide/source/quickstart/new-projects.rst @@ -19,11 +19,6 @@ Any configuration options or command line tools should be documented using the automated ``openstack-doc-tools``. For more information about these automated tools, see the :ref:`doc-tools` chapter. -To create your Installation documentation in accordance with the OpenStack -Foundation Project Navigator, begin by drafting and polishing it in your -developer documentation repository. This is considered 'official' Installation -documentation for the purposes of the Navigator. Once you have a good amount -of quality content, open a conversation with the openstack-manuals team about -inclusion in the top level documentation directory. The docs team will then be -able to work with you to determine your specific documentation needs, and the -best way to include your project in openstack-manuals. +To create an Installation Tutorial in accordance with the OpenStack +Foundation Project Navigator, follow the instructions at +``project-install-guide``.