I added a new command, `flub generate:releaseNotes`, to generate our
release notes from input changesets. This command serves as a
replacement for the `generate:upcoming` command. I used this to
semi-manually generate [the 2.1 release
notes](https://github.com/microsoft/FluidFramework/blob/main/RELEASE_NOTES/2.1.0.md)
and explore what additional metadata is needed to produce the output we
want.
In this implementation, we can add a second front-matter section to each
changeset with the additional metadata we want. For example:
```md
---
"@fluid-experimental/property-query": minor
---
---
section: fix
includeInReleaseNotes: false
---
```
The `section` ultimately represents a top-level section in the release
notes. The sections and their headings are configurable in the root
fluidBuild config. I added a release notes section for the SharedTree
DDS because it is undergoing enough changes that a whole section is
warranted, but over time the sections can change as our needs change.
Within each section, changes are sorted based on the date the changeset
was created. This should mean that the oldest changes are listed first,
but when changesets are added late then that won't be true.
Changes can be sorted before others in a section by setting the
`highlight` field to true. Within a section, highlighted changes will be
listed first.
The `includeInReleaseNotes` field can be used to omit a change from the
release notes. This can be used in cases where a change should be noted
in the individual package changelogs, but isn't really relevant at the
release note level. A major dependency update is an example of such a
change.
### About the metadata approach
I'm not sure this is the best approach for metadata, but one advantage
is that the existing changeset tools don't completely choke on the input
with errors like:
> Error: "blood-moon-rising" changeset mentions a release for a package
"includeInReleaseNotes" but such a package could not be found.
That said, we'd still need to do some processing ourselves to prevent
the second front-matter section from making it into the changelogs. So
bottom line, there is more design work to do, and perhaps there will be
little value in maintaining compatibility with the existing tools if our
requirements aren't themselves compatible with those tools. As it is, I
was able to use this to generate the notes and maintain them by manually
adding the additional metadata, which will then be removed before merge
so the downstream changelog tools work as expected.
If we imagine a small group of folks managing the release note content,
we may be able to punt on adding the metadata at changeset creation
time. Regardless, the person generating the notes can always make
metadata adjustments at the last minute to affect the notes output.
### Primary packages
Each change has a "primary package" which is the first package listed in
the front matter, but that isn't really used in the current
implementation. I'm leaning towards generic "sections" as being more
useful than package groupings. Especially if the sections can be defined
per-release so we can create a package-level section if we want, like I
did for tree here.
The implementation is deliberately simplistic and should be considered
an MVP. The markdown output is generated with a string builder rather
than an AST.
### Guidelines for reviewers
When reviewing, I suggest looking at [these draft 2.2 release
notes](https://github.com/tylerbutler/FluidFramework/blob/relnotes-2.2/RELEASE_NOTES/2.2.0.md),
which were created using this tool.
[AB#9063](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/9063)
---------
Co-authored-by: Alex Villarreal <716334+alexvy86@users.noreply.github.com>
Co-authored-by: Craig Macomber (Microsoft) <42876482+CraigMacomber@users.noreply.github.com>
Co-authored-by: jzaffiro <110866475+jzaffiro@users.noreply.github.com>
f85a3d2e1e