Types of changes - Set order

[shoulders]

On the following page https://keepachangelog.com/en/1.1.0/ you can see a section Types of changes

These types should have a set order in the changelog. Perhaps a note in the section saying insert the following sections in this order in your changelog

[Akkora]

In our team we stumbled upon the same issue. We are using keep-a-changelog, since it defines a lot of things and leads to less discussions. The one regarding types popped up today though.

Are there any plans to add this? A priority like Security first, then breaking changes, added functionality and later fixes?

[SlowMo24]

The order is important because it helps to quickly scan (and write) the changelog as not all releases may contain all change types.

Deciding on an order is of course arbitrary but I would like to suggest an order of importance from things-you-should-note to things-you-might-want-to-know .

1. Security
2. Changed
3. Removed
4. Deprecated
5. Fixed
6. Added

Happy to hear other suggestions!

Another order we might want to suggest is to order items within the change type categories from biggest to smallest (what ever that means e.g. biggest change, biggest addition...). Again this is sometimes arbitrary but it will also help readability.

[shoulders]

@SlowMo24 I like your order of categories, but I would not go for ordering within the categories for the following

• If these are generate by scripts they will be added in order by their GitHub issue
• It would not be clear that these were ordered from biggest to smallest
• Who decides what is biggest and smallest
• This could just simply be left up to the developer
• The ordering would not be obvious at all to the end user reading the changelog.

[SlowMo24]

... but I would not go for ordering within the categories for the following

* If these are generate by scripts they will be added in order by their GitHub issue

* It would not be clear that these were ordered from biggest to smallest

* Who decides what is biggest and smallest

* This could just simply be left up to the developer

* The ordering would not be obvious at all to the end user reading the changelog.

Yes, all your points are correct. Maybe my emphasis was misleading. I meant to suggest this order within the categories in contrast to making it a requirement. E.g the phrase in the keep-a-changelog documentation could be

Items within each category can be ordered by importance based on the developers' judgement to further improve readability.

[DJCrashdummy]

i was about to open an issue about the exact same topic because i wondered if this is a suggested/recommended ranking or not, as i figured out that it is not in alphabetical order because of the Fixed.

so i started using my ole brain and thought about how should these sections be ordered resp. which are more important than others and should catch someones attention first. IMHO the stated ranking could be nearly reversed, except the Fixed should be last or second to last before Added:

• Security is the first thing someone should see and notice! burring it at the end makes absolutely no sense.
• Removed is another really important section you should notice instantly.
• Deprecated is more or less the "light version" of "Removed": important to notice, but doesn't require immediate action.
• Changed... some may argue, that this section is at least more important than "Deprecated". but this section can get pretty big, so that everything underneath it, might be missed if someone just quickly browses through the changelog. not to forget that the first 3 sections are rather exceptional and relatively short, so most of the time this section would still be the first visible and if not, the first lines would still be very noticeable.
  not to mention, that at least semantic versioning would give a clue about bigger breaking changes. and IMHO a breaking change often also triggers an entry in the "Removed" section as a feature isn't available any more (as it used to be).
• Added might be interesting to know what to expect from the release/version.
• Fixed... don't we all hope for every release to fix all known and unknown bugs. 😜 if you are at this section, you are usually looking for something in particular, so it doesn't mater how quickly it catches someones attention.

as mentioned, i have no really strong opinion about if Added or Fixed should be last, but this order feels the most natural to me.

---

additionally, in case of incompatible big changes and not using a semantic versioning (so there is no clue in the first place) using "headlines" like suggested in #616 might be a better way to make people aware of a complete rewrite or the like.