1=====================================
2 Design Constraints and Requirements
3=====================================
4
5Managing release notes for a complex project over a long period of
6time with many releases can be time consuming and error prone. Reno
7helps automate the hard parts by devising a way to store the notes
8inside the git repository where they can be tagged as part of the
9release.
10
11We had several design inputs:
12
13* Release notes should be part of the git history, so as fixes in
14  master are back-ported to older branches the notes can go with the
15  code change.
16* Release notes may need to change over time, as typos are found,
17  logical errors or confusing language needs to be fixed, or as more
18  information becomes available (CVE numbers, etc.).
19* Release notes should be peer-reviewed, as with other documentation
20  and code changes.
21* Notes are mutable in that a clone today vs a clone tomorrow might
22  have different release notes about the same change.
23* Notes are immutable in that for a given git hash/tag the release
24  notes will be the same. Tagging a commit will change the version
25  description but that is all.
26* We want to avoid merge issues when shepherding in a lot of
27  release-note-worthy changes, which we expect to happen on stable
28  branches always, and at release times on master branches.
29* We want writing a release note to be straight-forward.
30* We do not want release notes to be custom ordered within a release,
31  but we do want the ordering to be predictable and consistent.
32* We must be able to entirely remove a release note.
33* We must not make things progressively slow down to a crawl over
34  years of usage.
35* Release note authors shouldn't need to know any special values for
36  naming their notes files (i.e., no change id or SHA value that has
37  special meaning).
38* It would be nice if it was somewhat easy to identify the file
39  containing a release note on a particular topic.
40* Release notes should be grouped by type in the output document.
41
42  1. New features
43  2. Known issues
44  3. Upgrade notes
45  4. Security fixes
46  5. Bugs fixes
47  6. Other
48
49We want to eventually provide the ability to create a release notes
50file for a given release and add it to the source distribution for the
51project. As a first step, we are going to settle for publishing
52release notes in the documentation for a project.
53
54Assumptions
55-----------
56
57Based on the above, *reno* makes a couple of assumptions about the release
58policy used for a given project. *reno* expects all development, including bug
59fixes, to take place on a single branch, ``master``. If *stable* or *release*
60branches are used to support an older release then development should not take
61place on these branches. Instead, bug fixes should be backported or
62cherry-picked from ``master`` to the given *stable* branch. This is commonly
63referred to as a `trunk-based`_ development workflow.
64
65.. code-block:: none
66   :caption: Trunk-based development. This is what *reno* expects.
67
68    * bc823f0 (HEAD -> master) Fix a bug
69    |
70    | * 9723350 (tag: 1.0.1, stable/1.0) Fix a bug
71    | * 49e2158 (tag: 1.0.0) Release 1.0
72    * | ad13f52 Fix a bug on master
73    * | 81b6b41 doc: Handle multiple branches in release notes
74    |/
75    * 0faba45 Integrate reno
76    * a7beb14 (tag: 0.1.0) Add documentation
77    * e23b0c8 Add gitignore
78    * ff980c7 Initial commit
79
80(where ``9723350`` is the backported version of ``bc823f0``).
81
82By comparison, *reno* does not currently support projects where development is
83spread across multiple active branches. In these situations, bug fixes are
84developed on the offending *stable* or *release* branch and this branch is
85later merged back into ``master``. This is commonly referred to as a
86`git-flow-based`_ development workflow.
87
88.. code-block:: none
89   :caption: git-flow-based development. This is not compatible with *reno*.
90
91    * 7df1078 (HEAD -> master) Merge branch 'stable/1.0'
92    |\
93    | * 9723350 (tag: 1.0.1, stable/1.0) Fix a bug on stable
94    | * 49e2158 (tag: 1.0.0) Release 1.0
95    * | ad13f52 Fix a bug on master
96    * | 81b6b41 doc: Handle multiple branches in release notes
97    |/
98    * 0faba45 Integrate reno
99    * a7beb14 (tag: 0.1.0) Add documentation
100    * e23b0c8 Add gitignore
101    * ff980c7 Initial commit
102
103When this happens, *reno* has no way to distinguish between changes that apply
104to the given *stable* branch and those that apply to ``master``. This is
105because *reno* is *branch-based*, rather than *release-based*. If your project
106uses this workflow, *reno* might not be for you.
107
108More information is available  `here`_.
109
110.. _trunk-based: https://trunkbaseddevelopment.com/
111.. _git-flow-based: http://nvie.com/posts/a-successful-git-branching-model/
112.. _here: https://storyboard.openstack.org/#!/story/1588309
113