Improve the CHANGELOG file

[jrfnl]

History

Originally, the changelog was maintained in a package.xml file, which was a requirement for releasing to PEAR.

With the move from the squizlabs repo to this repo and the dropping of support for PEAR, the changelog was moved to a CHANGELOG.md file, which was based on the work previously done for this for the 4.0 branch (commits bce4cf5, aedf523 and 4783156) and updated for any missing releases.

As things are, the changelog currently contains issue references which are not links, which makes the changelog not very user friendly.

For the 3.8.0 release, I've already added links for issues referenced and while that is a start, a lot more can be improved.

What I'd like to see improved

1. Contributor handles should be links.
   As there are a lot of repeat contributors, I think an alphabetically ordered link list at the very bottom of the changelog for this would be best as it will prevent duplicate references.
   This part has been addressed via PR Changelog: add links to contributors #243.
2. All issue/PR references should be links.
   The links for these should be added in a link list below each release, like done for the 3.8.0 release.
   Keep in mind that issue/PR references could be references to this repo, to the squizlabs repo, or to the PEAR repo. See Changelog: update link lists to prevent duplicate link definitions #410 for the link patterns to use.
   This part has been addressed via a range of PRs linked to this ticket.
3. Use proper MarkDown markup for the texts in the changelogs.
4. Check the text for spelling and grammar errors.

How to contribute

Note: these tasks do not have to be executed in one go. They can be done bit by bit starting with the more recent changelogs and working back to the older ones.

Small commits/PRs addressing the above action items for one or two releases at a time can keep this ticket moving forward without all the work having to be done in one go/the burden of executing this task falling on one person.

If you are interested in contributing to this task, leave a comment on this ticket with details on what you will be working on (to prevent duplicate work being done by multiple contributors).

[rodrigoprimo]

I can help. I will start with version 3.7.2, and after the PR is approved, I can work on more versions.

[rodrigoprimo]

Next, I will work on versions 3.7.1 and 3.7.0.

[rodrigoprimo]

I will now tackle versions 3.6.2, 3.6.1, and 3.6.0.

[rodrigoprimo]

Claiming 3.5.0 - 3.5.8

[rodrigoprimo]

Claiming 3.4.2 - 3.4.0

[rodrigoprimo]

Claiming 2.9.2 and 3.3.2 - 3.3.0.

[rodrigoprimo]

Claiming 3.2.3 - 3.2.0

[rodrigoprimo]

Claiming 3.1.1 - 3.1.0

[rodrigoprimo]

Claiming 3.0.2 - 3.0.0 and 2.9.1

[rodrigoprimo]

Claiming 3.0.0RC4 - 3.0.0a1

[rodrigoprimo]

Claiming 2.9.0 - 2.8.0

[rodrigoprimo]

Claiming 2.7.1 - 2.6.0

[rodrigoprimo]

Claiming 2.5.1 - 2.3.0

[rodrigoprimo]

Claiming 2.2.0 - 2.0.0RC2

[rodrigoprimo]

Claiming 2.0.0RC1 - 1.5.0

[rodrigoprimo]

As discussed with @jrfnl, I will prepare a PR adding links to issues in all the remaining versions.

[rodrigoprimo]

Use proper MarkDown markup for the texts in the changelogs.

@jrfnl, do you have an approach in mind for checking if the changelog is using proper MarkDown? Maybe we could use https://github.com/DavidAnson/markdownlint-cli2 as this is already being used in the PHPCSUtils repository? Is it worth setting up a GH action to lint the MarkDown files in this repository going forward?

[jrfnl]

Use proper MarkDown markup for the texts in the changelogs.

@jrfnl, do you have an approach in mind for checking if the changelog is using proper MarkDown? Maybe we could use https://github.com/DavidAnson/markdownlint-cli2 as this is already being used in the PHPCSUtils repository? Is it worth setting up a GH action to lint the MarkDown files in this repository going forward?

Well, there are two separate tasks here:

1. Set up a workflow with markdownlint + possibly also Remark. I'm already working on that and expect to pull a PR for it soonish.
2. Going through the text and applying markdown to the (unformatted) text.

Task 2 is the zinger as [1] can check markdown syntax, but will only find things if there is syntax to check.

Keep in mind, that the original changelog was in a package.xml file and couldn't contain any formatting.
A minimal conversion was done when the changelog was moved to the CHANGELOG.md file, i.e. headers were annotated with ## markers, but that's about it.

Over the past few months, between you and me, we've added markdown links to all contributor names and all issue references, which is a great improvement already.

However, I have a feeling the changelog will become more readable when references to CLI arguments - -e - or token names - T_CLASS - are enclosed in backticks and I can see this also for sniff name references when the sniff name is not on a line by itself.

There may also be changelog entries which could benefit from bold or italicized text to give the text the right attention/emphasis and I imagine breaking changes, especially when not in a major, could be annotated with a :warning: icon.

What do you think ?

[rodrigoprimo]

Thanks for the additional details, and for working on task 1.

However, I have a feeling the changelog will become more readable when references to CLI arguments - -e - or token names - T_CLASS - are enclosed in backticks and I can see this also for sniff name references when the sniff name is not on a line by itself.
There may also be changelog entries which could benefit from bold or italicized text to give the text the right attention/emphasis and I imagine breaking changes, especially when not in a major, could be annotated with a ⚠️ icon.
What do you think ?

I agree that the changes you are suggesting will make the changelog more readable, and I see that you have already used them in the changelog for the most recent versions which is great.

That being said, in my opinion, those changes are a nice to have improvement but not a super important one. Thus I'm unsure if it is worth investing the time to change this for the old versions. Especially for changes that require more manual interventions and reading the whole changelog. Maybe we can at least give this a try and see what can be changed automatically/semi-automatically?

[jrfnl]

@rodrigoprimo I agree it's not a high-priority improvement, but I do think it's important. Readability is a form of accessibility and I value accessibility of the project.

I also think it's the kind of task which would allow someone who is not familiar with the code of PHPCS and wants to contribute to the project, a chance to make a valuable improvement.

[rodrigoprimo]

Those are good points that you raised.

If no one else volunteers (I will wait a few weeks to give others the opportunity to help here), I can continue working on this issue and see what can be updated automatically/semi-automatically.