openstack/openstack-manuals
Code Issues Proposed changes

[contrib] Update docs review content

Browse Source 
Make it less specific to openstack-manuals.

Change-Id: I58100b7ffd3aeca82be8fec1d27ba06e90a2994f
This commit is contained in:
Petr Kovar 2018-01-22 19:34:13 +01:00
parent 776b064571
commit 199e68f895
6 changed files with 65 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/doc-contrib-guide/source/doc-tools/template-generator.rst
View File

@ -42,12 +42,12 @@ Here are a few representative files under ``www/``:
* ``de``
* ``index.html`` -- list of guides translated into $LANG*
* ``index.html`` -- list of guides translated into $LANG
* ``errorpage.html``
* ``mitaka`` -- newer series have more complex page organizations; each
directory is not identical*
directory is unique
* ``admin``
@ -57,7 +57,13 @@ Here are a few representative files under ``www/``:
* ``index.html``
* ``de``
* ``index.html`` -- landing page for $series docs translated into $LANG
* ``index.html``
* ``language-bindings.html``
* ``projects.html``
* ``user``
* ``index.html``
@ -91,7 +97,7 @@ Here are a few representative files under ``www/``:
* ``index.html``
* ``project-data`` -- YAML files with data about projects in each series
* ``project-data`` -- YAML files with data about projects in each $series
* ``latest.yaml``
* ``mitaka.yaml``
@ -102,7 +108,7 @@ Here are a few representative files under ``www/``:
* ``schema.yaml``
* ``redirect-tests.txt`` -- input file for `whereto <http://whereto.readthedocs.io/en/latest/>`_
to test .htaccess;
to test ``.htaccess``;
see http://files.openstack.org/docs-404s/ for a list of recent 404
errors
* ``static`` -- contains files that are not templates (CSS, JS,
@ -387,8 +393,8 @@ Common tasks
How would I change a page?
--------------------------
1. Look for the TEMPLATE_FILE value in the page source to find which
file produces the page
1. Look for the ``TEMPLATE_FILE`` value in the page source to find which
file produces the page.
The source for https://docs.openstack.org/pike/ shows:
@ -440,7 +446,7 @@ modify it.
How does the final release process work?
----------------------------------------
See :ref:`release-task-detail`.
See :doc:`../release/taskdetail`.
Testing the build
-----------------

5
doc/doc-contrib-guide/source/docs-builds.rst
View File

@ -24,8 +24,9 @@ create content and contribute to the documentation.
Building output locally
~~~~~~~~~~~~~~~~~~~~~~~
You can use Linux, MacOS, or Windows to build the Sphinx documentation
everywhere in OpenStack.
Although you can use Linux, MacOS, or Windows to build locally the Sphinx
documentation for OpenStack, Linux is the preferred build environment as it
offers the most complete support for documentation building.
OpenStack project and documentation repositories use a ``tox.ini`` file with
specific sections that run jobs using the `Tox

6
doc/doc-contrib-guide/source/docs-review-guidelines.rst
View File

@ -193,9 +193,9 @@ wait for the next proposal run.
The proposal job will update the patch with the next run.
If you cannot fix the problem, ask for help on the mailing lists:
* openstack-i18n: translation failures
* openstack-doc: requirements failures, glossary sync failures,
and common content sync failures.
* openstack-i18n@lists.openstack.org: translation failures
* openstack-dev@lists.openstack.org: requirements failures, glossary sync
failures, and common content sync failures.
Considerations for documentation aligned with release cycles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

69
doc/doc-contrib-guide/source/docs-review.rst
View File

@ -12,32 +12,27 @@ Reviewing documentation
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
<https://is.gd/openstackdocsreviewreloaded>`_. 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
<https://is.gd/openstackdocsreviewreloaded>`_ or the appropriate list of
Gerrit reviews for repositories with documentation.
The Documentation Program Dashboard only lists changes to repositories that
are managed by the Documentation project or the project's subteams. The
Dashboard 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 in
OpenStack, see `Code Review
<https://docs.openstack.org/infra/manual/developers.html#code-review>`_.
Repositories and core team
~~~~~~~~~~~~~~~~~~~~~~~~~~
The OpenStack Documentation team is core for the openstack-manuals,
openstackdocstheme, and openstack-doc-tools projects.
The Documentation team is core for a number of repositories managed by the
Documentation project subteams. A list of those subteams is available from
:doc:`team-structure`.
For the following repositories that are part of the Documentation program,
special rules apply:
* docs-specs: has a separate core team,
see :doc:`docs-specs <blueprints-and-specs>` section.
* 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.
* contributor-guide, 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
`Group openstack-doc-core
<https://review.openstack.org/#/admin/groups/30,members>`_.
For the security-doc repository, the rule is that each patch needs an approval
by a Docs core and a Security core.
Reviewing a documentation patch
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -48,8 +43,13 @@ and `Code Review Guidelines
<https://docs.openstack.org/infra/manual/developers.html#code-review>`_.
Once done, follow the steps below to submit a patch review.
#. Go to the `Documentation Program Dashboard
#. If you want to review patches for the repositories managed by the
Documentation project or the project's subteams, go to the
`Documentation Program Dashboard
<https://is.gd/openstackdocsreviewreloaded>`_.
To review patches for project teams' repositories, use the list of Gerrit
changes for the appropriate project.
#. Select a patch set.
#. Click a file that was uploaded to view the changes side by side.
#. If you see some inconsistencies or have questions to the patch owner,
@ -78,6 +78,11 @@ Once done, follow the steps below to submit a patch review.
`Peer Review
<https://docs.openstack.org/infra/manual/developers.html#peer-review>`_
.. note::
The following information only applies to repositories managed by the
Documentation project.
Achieving core reviewer status
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -98,23 +103,23 @@ recognizing valuable team members.
The process is:
* Every month (usually on the 1st), the documentation PTL draws the top 12
names from the `Stackalytics <http://stackalytics.com/>`_ report for
openstack-manuals:
* Every month (usually on the 1st), the documentation PTL draws the top
committers and reviewers from the `Stackalytics <http://stackalytics.com/>`_
report for openstack-manuals:
* `openstack-manuals Stackalytics
<http://stackalytics.com/?module=openstack-manuals&metric=commits>`_
* 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 added or removed will be contacted personally before
changes are made.
* The PTL then consults the existing core team and the OpenStack community
with a list of names to be removed from and added to the core list. This is
done in public by using the openstack-dev@lists.openstack.org mailing list
as the primary communication channel. Cores who are being 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.
with a justification sent to the openstack-dev@lists.openstack.org mailing
list. Three +1 votes from other existing core team members must be achieved
for approval.
Core reviewer responsibilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

4
doc/doc-contrib-guide/source/release.rst
View File

@ -8,7 +8,9 @@ This section describes the tasks that need to be completed to publish the
documentation for an OpenStack release. It is intended to be used by the
PTL and release managers.
Pike release managers are Chason Chan and Petr Kovar.
The current release manager for Documentation is listed on the
`Cross Project Liaisons wiki page
<https://wiki.openstack.org/wiki/CrossProjectLiaisons#Release_management>`_.
.. toctree::
:maxdepth: 2

7
doc/doc-contrib-guide/source/team-structure.rst
View File

@ -27,8 +27,13 @@ with their respective leads:
The current list of docs cores for openstack-manuals, openstackdocstheme,
and openstack-doc-tools repositories can be found at
https://review.openstack.org/#/admin/groups/30,members.
The api-site, contributor-guide, docs-specs, security-doc, training-guides,
and training-labs repositories have separate core teams.
and training-labs repositories have separate core teams but also include the
openstack-manuals core team.
The docs-specs repository has a separate core team, see
:doc:`blueprints-and-specs` for details.
The cross-project liaisons (CPLs) assist with subject matter questions,
reviews, doc bug triaging, and patching docs.