openstack/reno
Code Issues Proposed changes

move design docs out of readme

Browse Source 
Change-Id: Ifbb9b38f54bec735c1cf5993bfa7c66cb9cf903d
This commit is contained in:
Doug Hellmann 2015-09-22 21:37:38 +00:00
parent 4da5fb4e8b
commit d34cdd6209
3 changed files with 53 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
README.rst
View File

@ -5,58 +5,6 @@
Reno is a release notes manager for storing release notes in a git
repository and then building documentation from them.
Design
======
Managing release notes for a complex project over a long period of
time with many releases can be time consuming and error prone. Reno
helps automate the hard parts by devising a way to store the notes
inside the git repository where they can be tagged as part of the
release.
We had several design inputs:
* Release notes should be part of the git history, so as fixes in
master are back-ported to older branches the notes can go with the
code change.
* Release notes may need to change over time, as typos are found,
logical errors or confusing language needs to be fixed, or as more
information becomes available (CVE numbers, etc.).
* Release notes should be peer-reviewed, as with other documentation
and code changes.
* Notes are mutable in that a clone today vs a clone tomorrow might
have different release notes about the same change.
* Notes are immutable in that for a given git hash/tag the release
notes will be the same. Tagging a commit will change the version
description but that is all.
* We want to avoid merge issues when shepherding in a lot of
release-note-worthy changes, which we expect to happen on stable
branches always, and at release times on master branches.
* We want writing a release note to be straight-forward.
* We do not want release notes to be custom ordered within a release,
but we do want the ordering to be predictable and consistent.
* We must be able to entirely remove a release note.
* We must not make things progressively slow down to a crawl over
years of usage.
* Release note authors shouldn't need to know any special values for
naming their notes files (i.e., no change id or SHA value that has
special meaning).
* It would be nice if it was somewhat easy to identify the file
containing a release note on a particular topic.
* Release notes should be grouped by type in the output document.
1. New features
2. Known issues
3. Upgrade notes
4. Security fixes
5. Bugs fixes
6. Other
We want to eventually provide the ability to create a release notes
file for a given release and add it to the source distribution for the
project. As a first step, we are going to settle for publishing
release notes in the documentation for a project.
Project Meta-data
=================

52
doc/source/design.rst Normal file
View File

@ -0,0 +1,52 @@
=====================================
Design Constraints and Requirements
=====================================
Managing release notes for a complex project over a long period of
time with many releases can be time consuming and error prone. Reno
helps automate the hard parts by devising a way to store the notes
inside the git repository where they can be tagged as part of the
release.
We had several design inputs:
* Release notes should be part of the git history, so as fixes in
master are back-ported to older branches the notes can go with the
code change.
* Release notes may need to change over time, as typos are found,
logical errors or confusing language needs to be fixed, or as more
information becomes available (CVE numbers, etc.).
* Release notes should be peer-reviewed, as with other documentation
and code changes.
* Notes are mutable in that a clone today vs a clone tomorrow might
have different release notes about the same change.
* Notes are immutable in that for a given git hash/tag the release
notes will be the same. Tagging a commit will change the version
description but that is all.
* We want to avoid merge issues when shepherding in a lot of
release-note-worthy changes, which we expect to happen on stable
branches always, and at release times on master branches.
* We want writing a release note to be straight-forward.
* We do not want release notes to be custom ordered within a release,
but we do want the ordering to be predictable and consistent.
* We must be able to entirely remove a release note.
* We must not make things progressively slow down to a crawl over
years of usage.
* Release note authors shouldn't need to know any special values for
naming their notes files (i.e., no change id or SHA value that has
special meaning).
* It would be nice if it was somewhat easy to identify the file
containing a release note on a particular topic.
* Release notes should be grouped by type in the output document.
1. New features
2. Known issues
3. Upgrade notes
4. Security fixes
5. Bugs fixes
6. Other
We want to eventually provide the ability to create a release notes
file for a given release and add it to the source distribution for the
project. As a first step, we are going to settle for publishing
release notes in the documentation for a project.

2
doc/source/index.rst
View File

@ -11,7 +11,7 @@ Contents:
.. toctree::
:maxdepth: 2
readme
design
installation
usage
contributing