Add mention of releasenotes to the PTI

We expect this of OpenStack projects now. Be explicit about it.

Use the same overall structure as is used for Sphinx. Because we expect
reno requirements to be a much more consistent set, make listing them
explicitly in the repo optional. A reno releasenotes job should be able
to know what it needs to install to generate reno docs without any
specific instructions from the repo itself.

Change-Id: I1cfa2216451d056c1bdedd67186131c5e0901ecb
This commit is contained in:
Monty Taylor 2017-10-05 13:13:45 -05:00
parent 2c0cdd2738
commit df438a7370
No known key found for this signature in database
GPG Key ID: 7BAE94BC7141A594
4 changed files with 73 additions and 0 deletions

View File

@ -18,6 +18,7 @@ The following tasks are required for every project. Every project must:
- Generate a code coverage report
- Generate a source tarball
- Generate documentation
- Generate releasenotes
The following are other common tasks, which may not be relevant for every
project:
@ -66,6 +67,37 @@ emitted into ``doc/build``.
Language specific instructions supplement these and are in addition to them.
Release Notes
-------------
OpenStack uses `reno <https://docs.openstack.org/reno/latest/>`_ for generating
release notes regardless of programming language.
To support releasenotes generation, projects should:
* Have releasenotes documentation source in ``releasenotes/``
* Configure ``openstackdocstheme`` to be used in
``releasenotes/source/conf.py``.
* Optionally list distro package pre-reqs for dependencies in ``bindep.txt``
using the ``releasenotes`` tag.
* Optionally list requirements needed in ``releasenotes/requirements.txt``.
The list of requirements is:
* Sphinx
* reno
* openstackdocstheme
Assuming requirements have been properly installed, the following command
should work with no addiitonal setup and should result in the releasenotes
being emitted into ``releasenotes/build/html``.
.. code-block:: bash
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html \
releasenotes/source releasenotes/build/html
Language specific instructions supplement these and are in addition to them.
Linux Distributions
-------------------

View File

@ -234,6 +234,9 @@ Release notes
OpenStack uses Reno to manage release notes. This uses Sphinx to generate
the final HTML documentation.
In addition to the normal PTI :ref:`pti-documentation` requirements, for
developer convenience, Go projects are recommended to provide:
:code:`make releasenotes`
Generate HTML release notes

View File

@ -157,6 +157,28 @@ into the :code:`npm run document` command. Additional logic needed around
Sphinx generation should go into Sphinx plugins which should be listed in
``doc/requirements.txt``.
Generate Release Notes
======================
:Command: :code:`npm run releasenotes`
OpenStack uses `reno <https://docs.openstack.org/reno/latest/>`_ for generating
release notes.
In addition to the normal PTI :ref:`pti-documentation` requirements, Javascript
projects are recommended to provide an :code:`npm run releasenotes` command for
developer convenience that should:
* Either install any needed distro dependencies from the ``releasenotes`` tag
in ``bindep.txt`` or emit an error if they are not installed.
* Install Python dependencies for Sphinx from
``releasenotes/requirements.txt``.
* Execute: ``sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html``
The project infrastructure will not use :code:`npm run releasenotes` to build
the release notes. Therefore it is **STRONGLY** discouraged for people to put
additional logic into the :code:`npm run releasenotes` command. Additional
logic needed should go into reno.
.. _NPM package scripts: https://docs.npmjs.com/misc/scripts
.. _ESLint: http://eslint.org
.. _eslint-config-openstack: http://git.openstack.org/cgit/openstack/eslint-config-openstack

View File

@ -132,3 +132,19 @@ The project infrastructure will not use ``tox -edocs`` to build the
documentation. Therefore it is **STRONGLY** discouraged for people to put
additional logic into the command section of that tox environment. Additional
logic needed around Sphinx generation should go into Sphinx plugins.
Release Notes
-------------
As a convenience for developers, it is recommended that projects provide
a ``releasenotes`` environment for tox that will run
.. code-block:: bash
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html \
releasenotes/source releasenotes/build/html
The project infrastructure will not use ``tox -ereleasenotes`` to build the
documentation. Therefore it is **STRONGLY** discouraged for people to put
additional logic into the command section of that tox environment. Additional
logic needed around releasenotes generation should go into reno.