[Proposal] Maintain a changelog for OSD repo

[noCharger]

Hi Team,

When I was driving the OSD 2.3.0 release, I had to review all the changes made between the current release branch and the previous one in order to write release notes. The process could be expedited if we kept a CHANGELOG, where the commit owner added context each time a PR was merged to the main branch, even though it's good to gain knowledge for myself reading PRs. In addition, we can automate the release notes PR cut by obtaining data from CHANGELOG.md.

Notes: OpenSearch repo is also following this practice https://github.com/opensearch-project/OpenSearch/blob/main/CHANGELOG.md

Ref: https://keepachangelog.com/en/1.0.0/

Thanks,
Louis

[ruanyl]

Totally agree that writing CHANGELOG at the point when making a release could be frustrating because the people drafting the release may not have a full context of the commits.

I have a proposal here #2189 about fully automating the release process which includes the CHANGELOG generating.

The idea is to ensure each PR contains a description file to state what/why changes, a GitHub bot can do the PR verification to make sure the description file exists. It is good because the reviewers can not only comment on the actual code but also on the descriptions.

When preparing a new release, these description files are "consumed" to generate the CHANGELOG automatically.

[ahopp]

I like the outcome but not super invested in the mechanism. @ruanyl your recommendation in #2189 seems sound to me and automated seems better than manual. @kavilla @ashwin-pc any thoughts on the mechanism proposed?

[ashwin-pc]

I agree that automated is better than manual, but for reasons like those called out by @prudhvigodithi in #2189, we may need an interim solution like that suggested by @noCharger.

I love the idea of a CHANEGLOG.md. In addition to that, we must also:

1. Backfill the changelog for all prior releases.
2. Add to the PR checklist a step to make sure that the CHANGELOG.md is updated if necessary

This being said, let's continue the discussion for an automated process in #2189 to see how we can get around those limitations and how to prioritize it.

[kavilla]

Hey yall!

I like it. I had an idea to keep track of release-notes once branching. But at least keeping a change log as OpenSearch does will solve this problem and make things a lot more easier for releasing and can be reviewed ahead of time.

@tmarkley also created an issue here: #591

@ashwin-pc for:

1. Backfill the changelog for all prior releases.

Do you mean like all major, minor, and patch versions?

[joshuarrrr]

I'm also onboard, although I understand this issue to be a dupe of #591, where the first incremental step is the initial generation of CHANGELOG.md. Changes to processes, workflows, or automation can follow later.

[ashwin-pc]

Do you mean like all major, minor, and patch versions?
Ideally yes. But as Josh mentioned creating the initial file.

I also like how the PR template for OpenSearch has a checklist item for the changelog. Something we should consider too.

@joshuarrrr yeah this is a dupe. @noCharger lets close this and continue the discussion on #591

[seraphjiang]

I'm proposing deprecating changelog file which cause more issue than the benefit. we should figure out better solution to generate release note for sure.

opensearch-project/OpenSearch#4769

opensearch-project/OpenSearch#1868

FYI

@noCharger @ruanyl @ahopp @ashwin-pc @kavilla @joshuarrrr

cc: @dblock

[ashwin-pc]

@seraphjiang can we wait on a path forward before deprecating? That seems to be the case but just making sure.