Reference Tasks/Tickets in CHANGELOG

[gbertoncelli]

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]

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]

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.