release: adopt "keep-a-changelog" style in CHANGELOG.md #3531
Description
Until now, we prepared the CHANGELOG entry during the stable version release process.
The CHANGELOG.md file is embedded in the released extension and is also used by VS Marketplace's extension info page
(https://marketplace.visualstudio.com/items/golang.Go/changelog).
The current way has problems:
- We want the release process to involve fewer manual steps and the responsibility to be shared among team members. Writing the CHANGELOG.md makes this step challenging.
- It's better to write the CHANGELOG entry when the notable features/changes/fixes are made. And, the contributor who made the change is the best person to write the note.
- Pre-release extensions are built from the master, often before we write the CHANGELOG entry. That makes it hard for users to learn about notable changes they need to pay attention while using the pre-release versions.
- VS Marketplace seems to use the CHANGELOG.md from the latest version of extension (regardless whether it is pre-release or stable release). That can be confusing.
- The CHANGELOG.md sometimes needs fixes/clarification/edits after publication. In the current way, fixing errors in the CHANGELOG.md requires a new extension version publication, which is most likely unnecessary.
To address the problems, we propose to reorganize how CHANGELOG.md file is maintained.
- Adopt Keep a changelog style - which includes the "Unreleased" section. The section will list notable changes that are still in the pre-release phase.
- Have the CHANGELOG.md in the root of the repo, so it is more visible from the repo.
- Instead of embedding the full copy of the CHANGELOG.md file in the extension, have a static CHANGELOG.md that contains a link to the CHANGELOG.md file in the repo master. Typos and small edits can be made directly on the master and don't require extension publication.
- Recommend contributors to have their notable changes to be documented with their changes.
- The relui-based release automation process will move "Unreleased" entries to the released version section and get copied over to the GH Release page.
- New features and setting changes result in a minor version bump.
- Patch releases should be strictly for fixes in regression and minor changes. CHANGELOG.md will be replaced with the link to the milestone instead.
cc @h9jiang