Merge "documentation improvements"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
9c21b477a3
56
README.rst
56
README.rst
|
|
@ -1,18 +1,58 @@
|
|||
===============================
|
||||
reno -- Release Notes Manager
|
||||
===============================
|
||||
=========================================
|
||||
reno: A New Way to Manage Release Notes
|
||||
=========================================
|
||||
|
||||
Reno is a release notes manager for storing release notes in a git
|
||||
repository and then building documentation from them.
|
||||
Reno is a release notes manager designed with high throughput in mind,
|
||||
supporting fast distributed development teams without introducing
|
||||
additional development processes. Our goal is to encourage detailed
|
||||
and accurate release notes for every release.
|
||||
|
||||
.. image:: http://governance.openstack.org/badges/reno.svg
|
||||
:target: http://governance.openstack.org/reference/tags/index.html
|
||||
Reno uses git to store its data, along side the code being
|
||||
described. This means release notes can be written when the code
|
||||
changes are fresh, so no details are forgotten. It also means that
|
||||
release notes can go through the same review process used for managing
|
||||
code and other documentation changes.
|
||||
|
||||
Reno stores each release note in a separate file to enable a large
|
||||
number of developers to work on multiple patches simultaneously, all
|
||||
targeting the same branch, without worrying about merge
|
||||
conflicts. This cuts down on the need to rebase or otherwise manually
|
||||
resolve conflicts, and keeps a development team moving quickly.
|
||||
|
||||
Reno also supports multiple branches, allowing release notes to be
|
||||
back-ported from master to maintenance branches together with the
|
||||
code for bug fixes.
|
||||
|
||||
Reno organizes notes into logical groups based on whether they
|
||||
describe new features, bug fixes, known issues, or other topics of
|
||||
interest to the user. Contributors categorize individual notes as they
|
||||
are added, and reno combines them before publishing.
|
||||
|
||||
Notes can be styled using reStructuredText directives, and reno's
|
||||
Sphinx integration makes it easy to incorporate release notes into
|
||||
automated documentation builds.
|
||||
|
||||
Notes are automatically associated with the release version based on
|
||||
the git tags applied to the repository, so it is not necessary to
|
||||
track changes manually using a bug tracker or other tool, or to worry
|
||||
that an important change will be missed when the release notes are
|
||||
written by hand all at one time, just before a release.
|
||||
|
||||
Modifications to notes are incorporated when the notes are shown in
|
||||
their original location in the history. This feature makes it possible
|
||||
to correct typos or otherwise fix a published release note after a
|
||||
release is made, but have the new note content associated with the
|
||||
original version number. Notes also can be deleted, eliminating them
|
||||
from future documentation builds.
|
||||
|
||||
Project Meta-data
|
||||
=================
|
||||
|
||||
.. image:: http://governance.openstack.org/badges/reno.svg
|
||||
:target: http://governance.openstack.org/reference/tags/index.html
|
||||
|
||||
* Free software: Apache license
|
||||
* Documentation: http://docs.openstack.org/developer/reno
|
||||
* Source: http://git.openstack.org/cgit/openstack/reno
|
||||
* Bugs: http://bugs.launchpad.net/reno
|
||||
* IRC: #openstack-release
|
||||
* IRC: #openstack-release on freenode
|
||||
|
|
|
|||
|
|
@ -1,12 +1,7 @@
|
|||
.. reno documentation master file, created by
|
||||
sphinx-quickstart on Tue Jul 9 22:26:36 2013.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
.. include:: ../../README.rst
|
||||
|
||||
Welcome to reno's documentation!
|
||||
========================================================
|
||||
|
||||
Contents:
|
||||
Contents
|
||||
========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
@ -18,10 +13,3 @@ Contents:
|
|||
contributing
|
||||
history
|
||||
examples
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`search`
|
||||
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
.. include:: ../../README.rst
|
||||
|
|
@ -7,8 +7,8 @@ Creating New Release Notes
|
|||
|
||||
The ``reno`` command line tool is used to create a new release note
|
||||
file in the correct format and with a unique name. The ``new``
|
||||
subcommand combines a random suffix with a "slug" value to make the
|
||||
new file with a unique name that is easy to identify again later.
|
||||
subcommand combines a random suffix with a "slug" value to create
|
||||
the file with a unique name that is easy to identify again later.
|
||||
|
||||
::
|
||||
|
||||
|
|
@ -32,19 +32,19 @@ being installed globally. For example
|
|||
|
||||
releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml
|
||||
|
||||
The ``--edit`` option enables to edit the note just after its creation.
|
||||
The ``--edit`` option opens the new note in a text editor.
|
||||
|
||||
::
|
||||
|
||||
$ reno new slug-goes-here --edit
|
||||
... Open your editor (defined with EDITOR environment variable) ...
|
||||
... Opens the editor set in the EDITOR environment variable, editing the new file ...
|
||||
Created new notes file in releasenotes/notes/slug-goes-here-95915aaedd3c48d8.yaml
|
||||
|
||||
|
||||
By default the new note is created under ``./releasenotes/notes``. Use
|
||||
the ``--rel-notes-dir`` to change the parent directory (the ``notes``
|
||||
subdirectory is always appended). It's also possible to set a custom
|
||||
template to create notes (see `Configuring Reno`_ ).
|
||||
By default, the new note is created under ``./releasenotes/notes``.
|
||||
The ``--rel-notes-dir`` command-line flag changes the parent directory
|
||||
(the ``notes`` subdirectory is always appended). It's also possible to
|
||||
set a custom template to create notes (see `Configuring Reno`_ ).
|
||||
|
||||
Editing a Release Note
|
||||
======================
|
||||
|
|
@ -123,8 +123,8 @@ entirely.
|
|||
other:
|
||||
- Add other notes here, or remove this section.
|
||||
|
||||
Formatting
|
||||
----------
|
||||
Note File Syntax
|
||||
----------------
|
||||
|
||||
Release notes may include embedded `reStructuredText`_, including simple
|
||||
inline markup like emphasis and pre-formatted text as well as complex
|
||||
|
|
@ -155,25 +155,20 @@ that is checked out). To limit the report to a subset of the available
|
|||
versions on the branch, use the ``--version`` option (it can be
|
||||
repeated).
|
||||
|
||||
Notes are output in the order they are found by ``git log`` looking
|
||||
over the history of the branch. This is deterministic, but not
|
||||
necessarily predictable or mutable.
|
||||
Notes are output in the order they are found when scanning the git
|
||||
history of the branch using topological ordering. This is
|
||||
deterministic, but not necessarily predictable or mutable.
|
||||
|
||||
Configuring Reno
|
||||
================
|
||||
|
||||
Reno looks for an optional ``config.yml`` file in your release notes
|
||||
directory. This file may contain optional flags that you might use with a
|
||||
command. If the values do not apply to the command, they are ignored in the
|
||||
configuration file. For example, a couple reno commands allow you to specify
|
||||
|
||||
- ``--branch``
|
||||
- ``--earliest-version``
|
||||
- ``--collapse-pre-releases``/``--no-collapse-pre-releases``
|
||||
- ``--ignore-cache``
|
||||
- ``--stop-at-branch-base``/``--no-stop-at-branch-base``
|
||||
|
||||
So you might write a config file (if you use these often) like:
|
||||
Reno looks for an optional ``config.yml`` file in the release notes
|
||||
directory. If the values in the configuration file do not apply to
|
||||
the command being run, they are ignored. For example, some reno
|
||||
commands take inputs controlling the branch, earliest revision, and
|
||||
other common parameters that control which notes are included in the
|
||||
output. Because they are commonly set options, a configuration file
|
||||
may be the most convenient way to manage the values consistently.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -186,15 +181,22 @@ So you might write a config file (if you use these often) like:
|
|||
<template-used-to-create-new-notes>
|
||||
...
|
||||
|
||||
These will be parsed first and then the CLI options will be applied after
|
||||
the config files.
|
||||
Many of the settings in the configuration file can be overridden by
|
||||
using command-line switches. For example:
|
||||
|
||||
- ``--branch``
|
||||
- ``--earliest-version``
|
||||
- ``--collapse-pre-releases``/``--no-collapse-pre-releases``
|
||||
- ``--ignore-cache``
|
||||
- ``--stop-at-branch-base``/``--no-stop-at-branch-base``
|
||||
|
||||
Debugging
|
||||
=========
|
||||
|
||||
The way release notes are included into sphinx documents may mask where
|
||||
formatting errors occur. To generate the release notes manually, so that
|
||||
they can be put into a sphinx document directly for debugging, run:
|
||||
The true location of formatting errors in release notes may be masked
|
||||
because of the way release notes are included into sphinx documents.
|
||||
To generate the release notes manually, so that they can be put into a
|
||||
sphinx document directly for debugging, use the ``report`` command.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue