search

olivierlacan / keep-a-changelog

If you build software, keep a changelog.
http://keepachangelog.com
MIT License
6.11k stars 3.62k forks source link

Questions about `Changed` #636

Open lumynou5 opened 1 month ago

lumynou5 commented 1 month ago

In my opinion, these categories have two kinds: note and warning. (The words are picked from compiler message. I just don't know better words.)

For example, Added is a "note". User doesn't need to know what's added to upgrade safely. Fixed is also a "note". Although a fix might change behavior, the behavior is incorrect, unexpected, and/or different from the documentation.

In the other hand, Deprecated and Removed are "warnings". They indicate to user preparation is needed.

However, Changed seems very wide, including various big and small changes. Changes to functionality, behavior, and interface are "warnings" without a doubt, but there are also other kinds of changes in this category. A common one is optimization, which doesn't added new thing, fix a bug, or change any behavior but improve the performance. Optimization seems not changes any public interface but it does matter and users care, unlike really "invisible" ones such as changes to unit test and CI.

It seems inconvenient to find a change fast because Changed has a such vary importance, and makes bumping semantic version numbers harder—other categories are obvious; Fixed increases patch version, Added increases minor version, and Removed increases major version, etc.

Do I understand Changed wrong? Where should I put optimization?

william-andersson commented 2 weeks ago

I agree. Maybe changes could be split up into Changed and Updated? I regularly make changes to the code that does not change existing functionality... Maybe there could be a category for 'note' or 'cleanup' too?

lumynou5 commented 2 weeks ago

@william-andersson

That could be a solution, and looks like:

The only problem is its name. Updated is as abstract and obscure as Changed, people might mix up.

william-andersson commented 2 weeks ago

You are absolutely right. Maybe Refactor would be a better word for it? This is mentioned at https://common-changelog.org/ Refactor could also be used for code cleanup.