That can also be applied in the code base for deprecation messages. It would really be easier to contribute for newcomers with help on these subjects.

My suggestion would be to use this rule for UPGRADE/CHANGELONG files:

• First letter in capital letters Added x
• Always end with a dot Removed y.

And for deprecation messages this variant:

• X is deprecated since Symfony 4.4, use Y instead.

I agree with you @yceruto.

The goal would be to make a list of common actions and their associated messages, such as :

Removed a class and it has no new alternative -> Removed X.
Removed a class and it has a new alternative -> Removed X, use Y instead.
Removed a method -> Removed X::method().
Made a class final -> Made X final.
Added a new method, class, interface, etc. etc. etc.

We will never cover everything but every new entry in this doc would make our messages more consistent and the review process less arbitrary and faster.

ideally we let fabbot do some normalization concerning dots, capitals, linebreaks, indenting etc.

@fancyweb I've given up doing comments on this topic and I let people choose whatever they like (as this is not that important). But if we like to standardize on something, here are the rules I used at the beginning of this long story:

• Lower case first word (which is a verb) -> added XXX
• Never end with a dot

I forgot to mention that the 2 rules I've given above are consistent with the commit messages I'm using.

I guess people started to use uppercase words and dots when sentences became longer or when entries had more than one sentence. Thus, if we wanted to go for consistency here, we will probably have to go with full sentences (i.e. uppercased first word and terminating dots).

ideally we let fabbot do some normalization concerning dots, capitals, linebreaks, indenting etc.

Yes! @fabpot Is that technically possible? And where is the source code? 😁

Please create a simple command that would fix the files, I'll be able to add it to fabbot afterward.

Of course, please run this command on all existing files in the repo to validate it does its job correctly.

Ideally, we would also need a checker that checks that:

• when a feature or a deprecation is submitted, CHANGELOG is updated
• when a deprecation is submitted, both UPGRADE files are changed (current+next major)
• when one UPGRADE is patched, both should be (did you forget to update ...)

The output of this command should be a series of messages + affected files, that we would then reuse in the fabbot report (see existing reports for inspiration, the format is pretty simple)

we should assume each entry can be multiline and needs to be e.g. re-indented as a whole

e.g. nested lists (https://github.com/symfony/symfony/blob/4.4/UPGRADE-5.0.md#serializer) and overall the before/after examples

perhaps KISS and reformat using some markdown parser, to guarantee markdown input/output :)

And please, forbid trailing spaces to avoid such diff

Glad all upgrade- & change logs are in markdown. We could configure a markdown parser that let's us create rules on the different markdown elements. The reason for a markdown parser is to have control over all semantics. Just an idea, maybe it is overkill.

There are maybe more things you want to check or do on the upgrade- & change logs (if applicable).

• capitalize the first letter of headings
• run php-cs-fixer on code blocks
• find dead links

There are markdown linters available but we could write a program in the likes of php-cs-fixer that could be dev-required when publishing a release.

$ md-style-fixer fix

Edit: It's a shame I skipped passed @ro0NL comment when I made this comment. I agree on using a markdown parser :)