Reformat changelog to use reflinks in changelog entries

[glensc]

See discussion at #57

[jrfnl]

Much cleaner!

Mind: there is one gotcha - when creating a new release and copying the changelog to it, the links to the contributor pages at the bottom of the file will also need to be copied over to the release text.

Just something to be aware of once this PR has been merged.

[mfn]

Mind: there is one gotcha - when creating a new release and copying the changelog to it, the links to the contributor pages at the bottom of the file will also need to be copied over to the release text.

I think that for that very reason, this change, especially on the changelog, should not be done:

• for the readability of the file aka rendered for the end user: it does not matter
• for maintainers, on a release, it creates additional work => ideally you just copypaste this block to the release page and be done, not fiddle around with links
• (I would argue it's also slightly more maintenance work on a regular basis: adding self-container blocks of markup feels more natural than having to split them up for links)

[glensc]

@jrfnl no, you don't. GitHub formats issues/pull-requests and usernames anyway, without markdown magic required. this is needed only when you want to render the changelog in view file or outside github.

[glensc]

@mfn I very strongly disagree, changelog must be readable without a full bloated browser. the changelog is edited by humans, humans make mistakes, if each entry is 300 bytes long, they don't grasp anymore the noise from the data. so copying a wrong username or ticket link is very easy to make.

and another opinion, maintaining a changelog file is a band-aid of lacking automation that could take pull requests, issues, and their titles, labels and combine up a release note and generate that release notes on release creation.

[mfn]

@glensc

Good points, we've different opinions 👍

and another opinion, maintaining a changelog file is a band-aid of lacking automation that could take pull requests, issues, and their titles, labels and combine up a release note and generate that release notes on release creation.

Agree!

Unfortunately so far I've only seen tools that take literally every commit/PR and add them, making an unreadable mess of things 😢

[glensc]

@mfn no, commits are too granular, and you can't edit them prior to release. but pull requests title, and their labels are a very good fit. you can edit (as a maintainer) them prior to release, and classify each pr/issue of change type.

this idea is so trivial, and yet I have not found a good project to automate this all.

the closest I've come acquainted with is:

• https://github.com/laminas/automatic-releases

anyway, the downside of the release notes manual task topic mentioned here does not apply at all.

here's some older release, using @userhandle and #issue/#pr that need no special formatting:

1. rendered: https://github.com/eventum/eventum/releases/tag/v3.5.6
2. source:
   

[glensc]

@grogy ping. this pr is a response to your wish:

• Add missing reflinks to changelog #57 (comment)

[grogy]

Thanks! It look's too better