From 962e9086e00e85468c297cce5b16664d9bdbccc2 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Fri, 3 Feb 2017 17:31:51 -0500 Subject: [PATCH] documentation improvements Expand the readme to include more description of the benefits of using reno. Clean up the organization in index.rst. Remove an unused readme.rst from within the documentation tree -- nothing imported it or linked to it. Clean up phrasing and formatting in the usage page. Change-Id: Id3f0b71f199f7ad15d5fc0b3df67e05b7a8f2b19 Signed-off-by: Doug Hellmann --- README.rst | 56 ++++++++++++++++++++++++++++++++------ doc/source/index.rst | 18 +++---------- doc/source/readme.rst | 1 - doc/source/usage.rst | 62 ++++++++++++++++++++++--------------------- 4 files changed, 83 insertions(+), 54 deletions(-) delete mode 100644 doc/source/readme.rst diff --git a/README.rst b/README.rst index 3753eec..bdeaf08 100644 --- a/README.rst +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 2032fee..c77378c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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` - diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3..0000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 268976e..b0ef557 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.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: ... -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