Referencing issue numbers

[olivierlacan]

Referencing issue numbers

[kyrias]

I generally prefer linking to PRs rather than issues, since the PR shows the change itself, and that would then link to any issue tickets.

[mbrand12]

I think it would be a good idea to reference issues in "Fixed" section since most of the time the issue will cover more in depth info. A working example can be found here:

https://github.com/k0kubun/hamlit/blob/master/CHANGELOG.md

Granted, I agree that the messages them self should be sufficient to explain the fix and only provide the link if the reader of the changelog wants to know more about that issue.

[leoj3n]

I think consistency is all that matters, tbh.

[elyscape]

I'd argue that in that case it probably makes more sense to comment on the issue itself that it's resolved in version X.Y.Z.

[leoj3n]

👍

[olivierlacan]

Not yet. I've seen [#333] commonly used at the end of an entry. That said I'm not sure issues should be referenced in a change log. I say that while there were clearly times when an issue linked to from a (bad) change log entry helped me figure out what the change actually implied.

The problem is that the change log should be self-contained enough. If the log itself doesn't provide sufficient information to understand the nature or consequence of the change, then perhaps the change log entry needs improving.

What do you think?

[lunemec]

I agree with @olivierlacan, one change can affect several issues, and you might end up with lines having [#1234, #234, #1234, #234, #2345, #345 ... ] and this could be very confusing for the reader and making the changelog less readable.

[HolisticDeveloper]

I was asking more from a perspective of using changelogs within commercial development. In some cases, the user of the software may not be able to make the connection between the issue they reported and the change that was required to fix it. Additionally, they will often track an issue number and it might be easier to scan through a changelog to see if that issue number is fixed rather than reading all the descriptions.

Having said that, if you don't feel it fits in with what you want to do for this project then no worries.

[AkenRoberts]

I believe case / ticket references in the changelog can be useful, depending on how the team or project is utilizing the changelog. For our team, the changelog is used as a reference for what's contained in the release. Part of this process involves quality testing the release, and knowing what to test. Case IDs can help with this process, especially since the QA team has the ability to mark a case as "completed" once it has been tested and validated.

I believe a format for a case identifier would be a useful addition to the standard, if anything for the use of parsers that can potentially link to or retrieve additional information about the case being referenced.

Keep in mind that many types of issue trackers exist, not just GitHub!

[mockdeep]

For us linking to a PR could be really helpful to see any discussion that went into the decisions that were made, as well as to potentially further engage. Issues aren't as great, since there are a lot of PRs that come through that don't have a linked issue. Or if an issue was closed by a PR it might be nice to see both: Fix memory leak [#543], Issue [#1001].

[k3b]

In my previous commercial projects the ticket reference was mandatory for every commit using this format:

#ticketid [verb] description

Benefit : the confluence ticket/issue view show all changes (git chagesets with commit messages as link to git repository) that belong to the ticket.

[HolisticDeveloper]

I'm going to mark this closed since this was mostly a discussion and I don't expect any changes to come from it.

[k3b]

closing is ok. For me the closed ticket is a valuable reference for best-practise pro/contra.