Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

[PROPOSAL] Introduce in automatically generated release notes

See original GitHub issue

Proposal in one sentence

Enable the automation of release notes generations for OpenSearch-Dashboards repo

What problem are you trying to solve?

Currently, both Release Notes and CHANGELOG are updated mainly by manual efforts.

For the Release Notes, each release would required a PR to add respective markdown notes file to release-notes folder :
- Folder path : https://github.com/opensearch-project/OpenSearch-Dashboards/tree/main/release-notes.
- Example release note PR for v1.3.6 : https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2480
- Example release note PR for v2.3.0 : https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2318
For the CHANGELOG, even worse, it requires a direct update in the CHANGELOG file literally in every single PR :
- Example PR : https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2668
- Example PR : https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2652
- Example PR : https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2673

These manual updates are introducing in unnecessary burdens into each and every single release and PR, which is not serving the best interest of the OSD project and the whole community. We need to improve our current process and make the sharing of release/change information smoother and less-painful for both our consumers and contributors.

Why should we solve it?

Release Notes / CHANGELOG are important, we definitely need to have a clear and concise way of telling people what has changed, when the changes happened and more details (like PR link) whenever needed. Yet the collection of these information should be in a much smarter, or in another word, automatic way. The current manual process should be revised ASAP, given some specific reasons including :

The current manual way is Time-consuming
- For Release Notes, each release manager will need to spend a significant time preparing the release notes file, by either comparing commits or retrieving the data from CHANGELOG. Comparing commits definitely sounds horrible, and getting data from the CHANGELOG may sound straightforward, but in real we are just shifting the burden from release managers to each individual PR contributors (by asking them to update the CHANGELOG in every PR). Based on the previously generated release notes it may take at least 30min ~ 1hour just to put the information together in one PR (tagging each release manager just to get more accurate data)
- For CHANGELOG, the content update itself may be not intense but process-wise it’s taking more efforts since the PR number is required in each changed items as a reference, and usually the PR number won’t be secured until the PR is created (next PR number can be retrieved through github API call, but still, extra work). Given this there are lots of forced commits after the PR generation which is just to get the CHANGELOG file updated, for example :
The current manual way is prone to Human Errors
- We are all human beings and Human beings make errors. While we stay inclusive when human errors happened, it’s better for us to find an automatic way to minimize the chance of its happening. Recently I have learned this story from @ashwin-pc 's sharing and would like to share it here as well as an example that how could we create and maintain a good and better community as a whole :
  - Basically for this PR https://github.com/opensearch-project/OpenSearch-Dashboards/pull/2091, our contributor here had all the changes ready, yet later an entry in CHANGELOG is required, the contributor made the change yet didn’t sign off the very commit (cause usually we ask all commits to be signed). We made decisions as this is OK since the squash commit would have the signoff.
  - Yet, to dive deep, why can’t we just let each contributor to stay focused on their actual changes and just leave the maintenance work of changelog to us (maintainers , release managers and uhh enthusiastic contributors…)

How do you propose to solve it?

One word - Automation

Specifically, enable the automation of release notes generations, which is a native github offering (ref doc : https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes）

Kudos to @seraphjiang as first proposed and implemented this feature in the dashboards-anywhere repo : https://github.com/opensearch-project/dashboards-anywhere/pull/90

Here is proposed improvement steps in detail :

Create a new file .github/release.yml to enable the automation for release notes generation
Define and update the label template in .github/release.yml (we can reuse the format in our current CHANGELOG file)
Create / update label suites if needed
Test the updates (in a fork), by creating testing releases and make sure release notes are generated as expected

Once the automation is tuned as expected, next step is proposed :

Remove the CHANGELOG update requirement in each individual PR
Update the CHANGELOG based on the automatically generated release notes
Release Notes preparation is still a mandatory step in the release process, yet this time it would fully depend on the automation process instead of manual efforts.