search

olivierlacan / keep-a-changelog

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

Questions about `Changed` #636

Open lumynou5 opened 2 months ago

lumynou5 commented 2 months 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 1 month 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 1 month 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 1 month 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.

DJCrashdummy commented 3 weeks ago

i'm not sure if it should be split... and even less about the names. but i'm pretty sure either way, it will confuse some people. 😑

but interestingly - although a different topic - i similarly classified the sections as "warning" and "note" without mentioning it (but by ranking them): https://github.com/olivierlacan/keep-a-changelog/issues/458#issuecomment-2459808902 ...and yes, Changed was/is a pretty hard one to crack. 😜