Only track release notes in one place

[binste]

We currently track release notes in 2 places, the documentation and in GitHub Releases. The docs use restructured text whereas GitHub Releases uses Markdown so we can't just copy-paste content from one into the other but it requires a rewrite. In addition, as it's easier to add images and do formatting in Markdown, the GH Releases pages of the last few releases look much better and are more extensive than what we have in the docs. Thanks @mattijn for taking the time every release to write this!

How about we only maintain the release notes in GitHub Releases? We can simply link to it from the documentation. No information gets lost and it's easier for us to maintain and we can write better release notes which is beneficial for users.

I'm happy to create a PR for the docs and to make sure that everything is captured in GitHub Releases. Thoughts?

[mattijn]

I'm okay with either choice.
I agree that the release notes in the Altair docs are limited.

As a user, I often check the Altair docs but not so much the GitHub release page.

But it's really helpful for users to see detailed explanations of the changes in each release.

Right now, there's some repetition on the GitHub page with the auto-generated release description at the bottom.

Maybe we should only have auto-generated release notes on GitHub and more detailed docs on Altair's page.

I like that I can just keep scrolling through the Altair docs' release notes to see all the changes for multiple versions.

But I get your point that using the GitHub page is easier for maintainers and that therefore we actually write more documentation.

Like I said, I'm fine either way..

[joelostblom]

I'm in favor of maintaining release notes just in one place and I don't have a strong preference where that is. A few thoughts/considerations:

• Like @mattijn mentioned, I do also like having most/all notes on one page to be able to search through them quickly with ctrl + f. I guess on GH pages we can still see several releases per page which is pretty good.
• An advantage of GitHub is that we can link PRs and usernames more easily.
• I like the workflow where each PR also includes a line in the changelog/release file of what was changed, so that we don't have to go through and recall what's new in the end just before making a release (although it's harder to add images this way compared to just copy-paste into GH releases). But maybe this is less of an issue than I make it in my head.
• I think the Altair docs look nicer than the GH release page, but this is minor.

None of these are deal-breakers, and I'm generally in favor of most things we do to facilitate maintenance =)

[jonmmease]

I don't have strong opinions on this, so happy to defer to others who have thought about it more carefully

[binste]

Pro Altair docs:

• All on one page, easier to ctrl+f
• Look a bit nicer, but then again we don't put images in there and do less formatting so that effect might be negated

Pro of GH pages:

• Can link PRs and usernames more easily
• Easier to write and format as it's markdown which makes it easier for us to write longer release notes
• Easier to include images

For me the pros of the GH pages outweigh. Biggest one is that I think it leads to higher-quality release notes as shown in the last few versions.

As a user, I often check the Altair docs but not so much the GitHub release page.
To address this, I'd suggest that we keep the navigation bar entry in the docs and link to the GH releases.

I like the workflow where each PR also includes a line in the changelog/release file of what was changed, so that we don't have to go through and recall what's new in the end just before making a release (although it's harder to add images this way compared to just copy-paste into GH releases). But maybe this is less of an issue than I make it in my head.

Same! I also find this very convenient. How about we have a section in the RELEASING.md file where we can throw in release notes between versions and then as part of the releasing process, the maintainer doing the release would write some proper release notes based on this, potentially including images and code snippets?

[joelostblom]

How about we have a section in the RELEASING.md file where we can throw in release notes between versions and then as part of the releasing process, the maintainer doing the release would write some proper release notes based on this, potentially including images and code snippets?

I'm on board with that. As long as we keep track of it somewhere on a per PR basis, I don't mind exactly where that is.

[joelostblom]

A thought related to this discussion is whether we want to consider having our PR titles follow the conventional commits guidelines (short version here). I haven't used these previously myself, and it seems a bit cumbersome to follow it for every single commit on a branch, but for the PR titles it could be useful since these are the commit messages that get squashed into the main branch. It is what Vega-Lite follows as well.

For example, for some of our recent commits, this would change from:

Add timeseries filtering example to illustrate subsetting of columns from selector values (#3357)
Fix anywidget deprecation warning (#3364)
Open charts in the default browser with `open_editor` method (#3358)
Indicate that CompositeMarkDef can be used in addition to MarkDef (#3266)
Upgrade to Vega-Lite 5.17.0 (#3367)
Add additional 5.3 changelog entries (#3372)
Add note about conda "all" installation and how to install without optional dependencies (#3373)
Update README badges to reflect updated tool chain (#3374)

to (I find the title easier to read when capitalized, but it's technically optional):

docs: Add timeseries filtering example to illustrate subsetting of columns from selector values (#3357)
fix: Fix anywidget deprecation warning (#3364)
feat: Open charts in the default browser with `open_editor` method (#3358)
docs: Indicate that CompositeMarkDef can be used in addition to MarkDef (#3266)
chore: Upgrade to Vega-Lite 5.17.0 (#3367)
chore: Add additional 5.3 changelog entries (#3372)
docs: Add note about conda "all" installation and how to install without optional dependencies (#3373)
chore: Update README badges to reflect updated tool chain (#3374)

We could create PR templates for the most common keywords (fix, feat, chore, docs?) to encourage using these and optionally the CI VL has to enforce (but maybe the CI is overkill for now).

This could also be helpful when generated the release notes, and we would not have to add to the changelog/releasing file for each PR (which is easy to miss) as long as each PR title is descriptive (we still elaborate with images etc when writing the full release notes). Since we already use "squash and merge" we already have a link in the title.

Edit: GH's own automated release notes feature might be all we need to create a draft from the PR titles that we then expand on with images etc.
If we have these qualifiers (bug:, feat:, etc) first in each PR title, then we could generate a draft of the release notes using release-it (which is what VL uses and there is also a gh action, but again maybe overkill for us) or locally with the following (which outputs the commits messages sorted by the first word and then chronologically): git log --reverse --oneline --pretty=format:"%s" $(git describe --tags --abbrev=0 --match "v[0-9]*")..main | sort -k1,1 -s

I don't want to introduce something that is laborious to follow, but I'm thinking just prefix the PR titles would not add any additional time-consuming tasks for us, while still bringing some value in terms of what I described above. Thoughts?

[binste]

Big +1 from me for using this in PR titles (not individual commits in a branch). I also think that, as you mentioned, the automated release notes are then a great first draft which can be refined. It also gets us to consistently show everything in the release notes.

I'd be on board with having a CI check. Some examples are VL as you mentioned as well as Ibis