Release notes automation and integration

[tisonkun]

Motivation

Currently, our changelog page doesn't have real change logs but links to the latest roadmap and biweekly report.

From another perspective, our patch releases do not provide comprehensive release notes for users, like:

• https://docs.pingcap.com/tidb/stable/release-notes
• https://trino.io/docs/current/release.html

Thus, I suppose we resolve these two issues:

1. Remove/Move irrelevant content from the changelog page.
2. Integrate our release process with release notes generation and publish on the changelog/release-note page.

Proposal

Doc site structure

Update the current structure:

Changelog
| - Overview (contains a link to Roadmap)
| - Biweekly Reports

to:

Roadmap (Top-level entry. Keep the latest, add links to previous)
Releases
| - All releases (Portal page. A list of all releases and link to their release notes. If one has a release blog, add a link to the blog also)
| - v0.8.0 (YYYY-MM-DD)
| - v0.7.1 (YYYY-MM-DD)
| - v0.7.0 (YYYY-MM-DD)
...
| - v0.x.y (to be determined up to which version, or just start from new versions)

Release note generation and publish

Generation

This is a part that needs to be determined. And I'd prefer to delegate the choose to RMs at least for the first few releases.

These release notes can be referred:

• https://docs.pingcap.com/tidb/stable/release-7.5.1
• https://trino.io/docs/current/release/release-442.html

To be clear, separate the updates into a few sections with human-readable changelog messages. Highlight the important updates, esp. critical fixes, breaking changes, and deprecations.

We have a few tools to help:

• GitHub Releases auto release note generation. It's actually customizable with https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#configuring-automatically-generated-release-notes
• git-cliff that can be more flexible.

Note

All of this release notes things doesn't change how we make GitHub releases now. Whether the GitHub releases page should be left as is or changed, is not included in this proposal.

Publish

It should be the same as the current docs update process. That is, the RM revises release notes, sends a patch to add a new page under Releases/vX.Y.Z, and pings @nicecui and @GreptimeTeam/marketing for review.

Open questions

1. What version of the release notes we'd like to trace back to? Or we start from the new versions.
2. How do we generate release notes quickly and comprehensively?
3. How do we handle the versioned doc site? (I suggest either build a version-agnostic section, or like TiDB, old versions keep old release notes. And both TiDB and Trino archive versions very old, we can do it periodically.)

[tisonkun]

cc @fengjiachun @MichaelScofield @waynexia @sunng87 @killme2008 Please drop a comment for your opinions. Hopefully, the process should be activated from v0.8.0.

cc @Wenjie0329 @nicecui @alili for your information.

[fengjiachun]

LGTM, we can start from the new versions?

[orhun]

Hey, maintainer of git-cliff here 👋🏼 Happy to help with any customizations/tweaks if you decide to go with git-cliff here!

[tisonkun]

@fengjiachun GreptimeTeam/docs#862 is ready for review as a sample of release note. I suggest we catch up release notes for 0.7.0 and 0.7.1 so that in the next version we know what should be focused and possibly improved.

[tisonkun]

@orhun Thank you! Let me try it out first. I'll ping you if there is any uncertain :P

[sunng87]

How do we handle the versioned doc site? (I suggest either build a version-agnostic section, or like TiDB, old versions keep old release notes. And both TiDB and Trino archive versions very old, we can do it periodically.)

Some of the content has to be moved out to be version-agnostic, like changelog, faq and all cloud docs (cloud can be considered as rolling-release). Not 100% sure if it's possible with our doc site. Perhaps we can use symbolic link for that?

[tisonkun]

Perhaps we can use symbolic link for that?

Ref - GreptimeTeam/docs#871

Seems lint-staged doesn't like symlink.

[tisonkun]

Closed as resolved.