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:
parent
2c0cdd2738
commit
df438a7370
|
@ -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
|
||||
-------------------
|
||||
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue