olivierlacan / keep-a-changelog

If you build software, keep a changelog.

http://keepachangelog.com

MIT License

6.07k stars 3.63k forks source link

Reference Tasks/Tickets in CHANGELOG #348

Closed HighSoftWare96 closed 1 year ago

HighSoftWare96 commented 4 years ago

I was wondering if, inside the CHANGELOG.md, it is a good practice to reference for each change or for each group of changes to the relative task or ticket or to the epic story. For example with a ticketing application like Atlassian Jira is it a good think referencing the task link (maybe even with markdown badges)?

An example would be like this:

1.0.0 - 2020-05-22

A new feature

[ADDED] Added this thing
[CHANGED] Changed this thing
[FIX] Fixed this other thing

Or if you group first by action type:

1.0.0 - 2020-05-22

Added

A new feature

Added this thing

Fix

Another group

Fixed this thing
Fixed this other thing

holistic-developer commented 4 years ago

I connect changes to the issue tracking system by starting the commit message with the issue key and number. This allows the linkage of changes to tickets as well (at least in jira in combination with bitbucket).

If you do want to make it explicit in you change log as well, i would recommend the second option: Your task is most likely one of the following, but not multiple at once (otherwise i recommend cutting your tasks differently):

A bug → Fix some issue that existed already
A change request / task of an existing requirement → Your issue Changed something that was in the application before
A feature request / story → Your issue Added new functionality to the application that was not there before

olivierlacan commented 1 year ago

As with GitHub Pull Request references, anything that offers further details on the change or a group of changes is fine to link from the changelog as long as it provides better context for the folks reading the changelog.

If it's only there only to reference internal bug tracker links that are either behind the scenes or contain irrelevant information to end-users, I would question the need for systematic inclusions.

To give you an example, I link to PRs when new translations are added to Keep a Changelog (in an Added) section because it's quite likely there will be useful context regarding how the contribution was made, and what choices were made by the contributors. It's also to give contributors indirect credit as well. But it may also allow someone to find potential improvements and suggest them either in the merged pull request, or create a new pull request.