# How to produce release notes for GAP essentially automatically

(This text arose from discussions and experiments during the
GAP Days "Spring" in February 2021.)

## What are GAP release notes?

For each release of GAP, we provide **release notes** in the file
`CHANGES.md` of the GAP root directory. This file contains one section
for each release.

The content of the release notes is partially generated by hand, and
partially with the help of scripts. This file is intended to explain how
to properly update the release notes.


## How shall GAP release notes look?

The aim of GAP release notes is to give users an overview of
**relevant** changes since the previous version. This means that this
overview does not show a complete list of **all** changes (if one is
interested in a complete list then one can consult the history on
github), but rather a curated one.

A file with release notes that is intended to be **read** should be as
**concise** as possible. At the same time, we need to minimize the work
required to update these release notes for practical reasons.

We aim to achieve this by generating the bulk of the release notes
automatically from a list of all merged pull requests that belong to the
release in question and are regarded as relevant for the release notes.
Relevance is determined by assigning suitable labels to the pull
request. For most of the relevant pull request, a single line is added
to the release notes, containing the number (as a link to the pull
request in github) and the title of the pull request. Pull requests with
related topics are grouped together under suitable subheadings, again
based on its labels. These groups are ordered according to decreasing
"severity". Of course it is not possible to define such a general linear
ordering, but we want each pull request to appear **only once** in the
release notes, not in several groups according to several aspects it
belongs to.

Besides the list of relevant pull requests, the release notes contain also the lists of changed GAP packages:
- omitted packages (which had been distributed with the previous GAP version but are not distributed with the current one),
- changed packages (which are distributed with both the previous and the current GAP version, but with different package versions),
- new packages (which had not been distributed with the previous GAP version but are distributed with the current one).

For each package in question, there is one entry that shows package name (with a link to the package homepage), version, authors, abstract,

Note that the information about packages cannot be extracted from pull requests. It depends on the archives of packages that are distributed with GAP.
(Since the release of GAP 4.11.1, scripts in `dev/releases` can be used to extract the metadata of all packages that belong to a given version of GAP or to a given package archive, hence the differences between two releases can be computed.)


## How are release notes created from the GitHub pull requests?

The main idea is to use the *labels* that are assigned to the pull requests.
Currently the following labels are regarded as relevant for the creation of release notes.

- Pull requests with the label `release notes: not needed` shall **not** be listed in the release notes.
  Thus the release notes are composed from all those merged pull requests that belong to the release in question (are assigned to the release branch or have a `backport-to-...-DONE` label for the release) AND do NOT have the label `release notes: not needed`.

- For pull requests with the label `release notes: use title`, the text for the release notes is given by the title of the pull request.
  For all other pull requests, the text for the release notes can be extracted from the pull request body.  The pull request template (see `.github/pull_request_template.md`) contains the markers `## Text for release notes` and `## (End of text for release notes)`, thus the relevant text is expected between these markers, and can be extracted automatically.

- Up to now, also the labels `release notes: needed` and `release notes: added` have been used.
  The first one means that the text for release notes can be found in the body and has not yet been added to `CHANGES.md`, the second one means that the text has been added to `CHANGES.md`.
  I think that these two labels are obsolete in the new workflow where one can automatically create the current state of the `CHANGES.md` section about the forthcoming release **at any time**.

- The above labels describe whether a pull request is relevant at all, and if yes then how it is treated.
  The script `release_notes.py` groups the pull request based on labels in a list called  `prioritylist`. Each pull request gets assigned to the **first** group/subheading that corresponds to one of its labels. This list can be adjusted over time as needed. Note that any such ordering is always a compromise, there is no best way to do it.

- For empty groups of pull requests, the subheading need not appear in `CHANGES.md`.

- The three sections on changes packages in the forthcomiing release (see above) will appear below the groups of pull requests that are defined by the above labels.
  (There will be a script that extracts the information from suitable text files related to the package archives.)


## How to deal with github pull requests in a release notes friendly way?

The following is intended for those who create or review pull requests.

- If your pull request should not be mentioned in the release notes then add the label `release notes: not needed`, and you are done.

- Otherwise, try to find a short title that describes the pull request in the release notes; use appropriate markup in the title (e.g., backquotes for surrounding function names).  In this case, add the label `release notes: use title`.

- Otherwise, make sure that the body of the pull request contains the relevant text below the line `## Text for release notes`.
  (In the old workflow, the label `release notes: needed` should be added. I think this should be abolished.)

- Choose as many suitable (release notes relevant) labels as you want. Keep in mind that the pull request will appear just in the first applicable group of pull requests in `CHANGES.md`.

