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