Azure / Azure/azure-functions-core-tools

Switch to CHANGELOG model

Open
#5,411 0 comments 0 reactions 0 assignees View on GitHub
area: engineering enhancement needs-discussion v5
Dominant language
C#
Stars
1.5k
Forks
498
Avg merge
5d 4h
Merged PRs (30d)
15

Description

### Description

This work item if for us to have a conversation about if we should switch to the change log model instead of release notes. My main motivations for us moving in this direction are as follows:

1. All of a version's history stays visible and in one place instead of scattered per release. The only place right now to check previous notes is to find the different releases.
2. Less merge friction! This is a big one as we constant have to address release note merge conflicts and this slows us down. We can use a fragment-based tool (changesets/towncrier), which allows you to add a small file per PR that's later compiled into the changelog
3. Better tooling support, auto-generators (like release-please, changesets, semantic-release, git-cliff, towncrier) read/write a single changelog and can cut releases from it.
4. Better audit/discoverability. A single linear log is easier to grep for "when did behavior X change?" than walking per-release files.
5. Lower maintenance overhead. We don't have to keep updating and resetting release notes.

If we make the change here, it might be worth applying this to all of our managed repos. This would also require making changes to some of our release pipelines that reset and touch release notes.

PR here: https://github.com/Azure/azure-functions-core-tools/pull/5317 (closed but can be revived)

Contributor guide

Open the contributing guide

Research direction

Start by reviewing closed PR #5317 and the release pipelines that reset or touch release notes. Compare the current release-note flow with the proposed single CHANGELOG model; done requires a decided approach and corresponding updates across managed repositories and pipelines.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.