matrixfurry.com
The open source OpenXR runtime
1# Usage of Proclamation to maintain changelogs
2
3This file:
4
5```txt
6SPDX-License-Identifier: CC0-1.0
7SPDX-FileCopyrightText: 2020 Collabora, Ltd. and the Proclamation contributors
8```
9
10This project uses the [Proclamation][] tool to maintain changelogs. Contributors
11to this project do not need to use Proclamation, but they are asked to write a
12fragment for the changelog describing their change. See below for more details.
13
14- Directory to run Proclamation in: `doc/changes`
15 - Config file: default name (`.proclamation.json`)
16- Location of the per-changelog-section directories: `doc/changes`
17
18[Proclamation]: https://gitlab.com/proclamation/proclamation
19
20## Table of Contents
21
22- [Quick Start Instructions for Contributors](#quick-start-instructions-for-contributors)
23- [About Proclamation and Usage Instructions](#about-proclamation-and-usage-instructions)
24 - [Fragments](#fragments)
25 - [References](#references)
26 - [Sections](#sections)
27- [Configuration](#configuration)
28- [Sample Usage Workflow](#sample-usage-workflow)
29 - [During Development](#during-development)
30 - [Preparing for a Release](#preparing-for-a-release)
31
32## Quick Start Instructions for Contributors
33
34- Get a merge/pull request number for your change: this might involve pushing it
35 as a WIP.
36- Create a file in the appropriate section's directory, named `mr.YOURNUMBER.md`
37- In that file, briefly describe your change as you would like it describe in
38 the changelog for the next release.
39- If your changes affect multiple sections, you can have a file in each section
40 describing the section-specific changes.
41- If your change resolves an issue or otherwise references some issue or
42 merge/pull request, you can add those references to the beginning of your
43 changelog fragment. See the full instructions below regarding
44 [References](#references).
45
46## About Proclamation and Usage Instructions
47
48The "Proclamation" tool assembles changelogs, which incorporate fragments of
49changelog text added by the author of a change in a specific location and
50format.
51
52### Fragments
53
54Each change should add a changelog fragment file, whose contents are
55Markdown-formatted text describing the change briefly. Reference metadata will
56be used to automatically add links to associated issues/merge requests/pull
57requests, so no need to add these in your fragment text. The simplest changelog
58fragment contains one line of Markdown text describing the change:
59
60```md
61Here the author of a change has written some text about it.
62```
63
64### References
65
66The changelog fragment system revolves around "references" - these are issue
67reports, pull requests, or merge requests associated with a
68change. Each fragment must have at least one of these, which forms the main part
69of the filename. If applicable, additional can be added within the file - see
70below for details.
71
72This portion of the Proclamation system is intentionally left very flexible,
73since there are very many ways of organizing and managing a project. By default,
74references are delimited by the `.` character. The first two fields have some
75conventional meaning, while any additional fields are up to the user and are
76only used if a custom template is supplied by a project.
77
78The format of references in general is:
79
80```txt
81<ref_type>.<number>
82```
83
84where
85
86- `ref_type` is "issue", "mr", or "pr"
87- `number` is the issue, MR, or PR number
88- any additional `.`-delimited tokens are passed on to the template in the
89 `service_params` list.
90
91Your changelog fragment filename is simply the "main" reference with the `.md`
92extension added. (You can also use `.rst` or `.txt` as your extension in your
93project.)
94
95To specify additional references in a file, prefix the contents of the changelog
96fragment with a block delimited before and after by `---`, with one reference on
97each line. (This can be seen as a very minimal subset of "YAML Front Matter", if
98you're familiar with that concept.) For example:
99
100```md
101---
102- issue.35
103- mr.93
104---
105Here the author of a change has written some text about it.
106```
107
108There are provisions for providing your own reference parser if this format is
109entirely unusable, but they're underdeveloped. (Most use cases found by the
110original author can actually be accommodated by changing the template and
111specifying `.`-delimited fields in references.) If this functionality is
112interesting to you, get involved in the development of Proclamation and help
113finish it!
114
115### Sections
116
117Changelog fragments are organized into sections, each of which should have its
118own directory. These might be "type-of-change" sections (e.g. new feature,
119bugfix, etc). Alternately, they might be logical sub-projects - it's permissible
120to have multiple projects configured in one config file and repo with
121partially-overlapping sections. (This is actually a part of one of the
122originally motivating use cases for this tool.)
123
124Every file whose filename parses and meets some basic checks will be used! (You
125do need to add e.g. an `.md` file extension to files for them to parse as
126references.) Having a `changes/your_section_name` directory for each section is
127recommended. You can provide a `README.md` file with a modified subset of this
128file in that directory, as guidance to contributors to your project.
129(`README.md` won't parse as a reference, so it will not be treated as a
130changelog fragment.)
131
132Use whatever works for your project. Right now, all changelog fragments must be
133in a section, sections must be a single directory, and sections may not be
134nested. If you'd like to loosen these assumptions, get involved in the development of Proclamation and help!
135
136## Configuration
137
138Your project should have a configuration file: the default name is
139`.proclamation.json`. The top level object can either be a project config object
140directly, or contain a member named "projects" with an array of project config
141objects.
142
143You can look at the config file for this project for guidance, since it's a
144pretty simple use case of this tool. (Proclamation was designed to handle more
145elaborate use-cases than this.)
146
147- Project attributes:
148 - `project_name` - Required. Used to form the heading in the default template,
149 etc.
150 - `base_url` - Technically optional, but required if you're using the default
151 template. Passed to the template which may use it to form reference links.
152 - `news_filename` - Optional, in case your changelog isn't called NEWS.
153 - `sections` - Required: contains an object. The key names are the section
154 names (used by the default template for section headers), while the values
155 are objects. Sections might be logical sub-projects, or alternately
156 categories of changes (feature, bug fix, etc), it's up to you.
157 - The only key valid right now in the child of the section is `directory`,
158 which indicates the directory to search for changelog fragments.
159 - `template` - Optional. The name of a Jinja2 template for a single release's
160 changelog section. `base.md` comes with Proclamation and is used by default.
161 Your custom template might inherit from this if you only need to change a
162 few small details. Evaluated relative to the current working directory when
163 you run Proclamation.
164 - `insert_point_pattern` - Useful mainly if you're not using the default
165 template. The first match of this regex will be considered the first line of
166 a release entry, and your new release will be put in your changelog file
167 before it. Default works with the default template (looks for a second-level
168 Markdown heading).
169 - `extra_data` - Any extra data you'd like to pass along to your custom
170 template.
171
172## Sample Usage Workflow
173
174Note that the base `proclamation` script and all its subcommands have help,
175accessible through `-h` or `--help`. The guidance in this section of the README
176is intentionally minimal, to avoid contradicting the online help which remains
177up-to-date implicitly. This is also only the simplest, minimal way to perform
178these operations: if your project is more complex, there may already be more
179features to support your needs in the command line help.
180
181### During Development
182
183As changes get submitted to your project, have each change author create a
184changelog fragment file. Since these are all separate files, with names made
185unique by your issue/repo tracker, there won't be merge conflicts no matter what
186order they're merged in. (This is the central benefit of Proclamation, and its
187inspiration, towncrier, over having each contributor edit CHANGES as part of
188their submission.)
189
190At any time you can run `proclamation draft` to preview the release portion that
191would be added to your changelog if you released at that time.
192
193### Preparing for a Release
194
195When you're ready to perform a release, you'll want to run Proclamation to
196update your changelog, then remove the fragments that you've incorporated into
197the regular changelog. You can use a command like the following:
198
199```sh
200proclamation build YOUR_NEW_VERSION
201```
202
203to preview the full file on screen. When you're ready to actually perform the
204update, run something like:
205
206```sh
207proclamation build YOUR_NEW_VERSION --delete-fragments --overwrite
208```
209
210to overwrite your changelog file with the updated one and delete the used
211changelog fragments.
212
213You're welcome to manually edit the new (or old!) changelog entries as desired:
214as long as the `insert_point_pattern` (by default, `^## .*`) can still match,
215Proclamation will not be confused.
216
217Finally, make sure the deletion of the fragments and the update of the changelog
218has been checked in to your version control system.