Verb for improvements

[gramian]

I would like to suggest an additional verb which reflects changes to the code leading to some form of improvement such as better performance, readability, structure etc. This does not seem to be included in the current set of verbs as it does not add a feature, fix a bug or change functionality. Hence, I propose:

IMPROVED

[gsilvapt]

Surely improved is more to the point but it seems Changed targets those type of changes as well. At least judging the examples provided in the website.

[Unreleased]

Changed

• Update and improvement of Polish translation [...]

[gramian]

There are alterations to a source code which do not influence outward facing behavior. Changed to me implies a visible change, likely a breaking change. Improved on the other hand is less strong, and even though it holds a (positive) connotation, it is in my humble opinion more befitting to a non-visible, under-the-hood change.
However, this is a minor detail. Feel free to close this discussion if you see this differently.

[gsilvapt]

I understand your argument and I kind of agree. It's definitely more clear that change was about some kind of improvement.

I think this discussion is healthy and more people should participate or tell what they do in these situations. I myself am not even experienced writing changelogs and a lot of people simply don't write changelogs.

[simkimsia]

I agree with @gramian on this. I actually came here hoping to submit the same suggestion and then I saw this. Adding my +1.

I see IMPROVED as a verb for internal facing enhancements such as

• refactoring code to be cleaner
• improving performance which may not be noticeable to the end users

[lamberss]

I agree with #273, that the change log should be targeting end-users and not collaborators. If a change is not noticeable by the end-user, then I don't think it needs to be mentioned in the change log.

Performance changes should be noticeable to end-users, and I think fit fine in the "Changed" section.

[gramian]

Consider library / toolbox projects: as a user (a developer of a project calling this library) the term CHANGED would suggest a change in interface or something which would require me to adapt my code. IMPROVED on the other hand would hint to me that I do not have to act.

On performance improvements: If, for example a numerical computation runs ten times faster in my compute environment and the log notes CHANGED, I would assume a change in underlying algorithm, which could mean that the solution changes (significantly) and I have to investigate this change. In case of IMPROVED, I would just be happy.

[NateEag]

I would argue for adding multiple new verbs, actually, as there are multiple different improvements that could be made.

"Optimized" is the standard verb for making software faster. I suggest adding it as a change type.

Similarly, I think "Refactored" should be added as a change type, too. It's the standard verb for improving a software module's internals without changing its interface. Not every refactoring should be in the changelog, but I think it would make sense to mention larger ones - it helps people be aware of what areas may have had unintentional changes and bugs added.

"Changed" is always still an option, obviously. I think of it as being primarily relevant for when a user interface has been altered significantly.

[Mouvedia]

Refactored would match the refactor conventional commits type.
Concerning Improved check conventional-commits/conventionalcommits.org#78

[lazlo-bonin]

I've been keeping about six changelogs for production projects for the last three years and this is what keeps me from switching to the Keep A Changelog format. I'm also in favor of more granular verbs than "Changed" for two main reasons:

1. "Changed" is usually a log verb that warns the user about a UX, UI, API or behaviour change they should be made aware of to react accordingly.
2. "Changed" is not an eloquent or clear log verb in and of itself (without reading the entry's text). Users waiting for an optimization or improvement, for example, may skim over it.

In my projects I've frequently used all three of the above suggestions:

• Improved: An existing functionality has been improved, but does not require users to adapt anything on their end. This is a strictly positive type of change.
• Optimized: An existing feature has been made faster, but does not require users to adapt anything on their end. This is a strictly positive type of change. Users waiting for an upgrade due to a performance issue will instantly parse the changelog looking for those entries.
• Refactored: An existing system has been reworked internally, and in theory should not require users to adapt. However, this is a type of change that acts as a warning, because it might result in instability in a part of the software that users were used to rely on.

I think each of these verbs brings significantly more information than "changed". Writing this, I also realize that my underlying reason is that verbs have inherent "values" in the eyes of end-users. Some of them should make the users wary, others shouldn't.

"Positive" verbs include:

• Added
• Improved
• Fixed
• Optimized

"Warning" verbs include:

• Changed
• Refactored
• Deprecated
• Removed

(These are the 8 verbs I used across all my changelogs, and I've never needed more than that.)

[NicoHood]

Any chance to see that in the docs? There is definitely something missing right now.

[Apostolique]

I like Optimized and Refactored, but I'm not convinced on Improved as to me it's synonymous with refactored. There's also some overlap between optimized and refactored, but I think that's ok in most cases.

Does anyone have a good example of a case where improved would be different than a refactor?

[NateEag]

@Apostolique Refactoring.com defines "refactoring" as

a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior.

I see the "Improved" suggestion as being for small tweaks to user interfaces that leave them backwards-compatible with previous versions but make life a little better.

Refactoring is paying down technical debt, changing internals while leaving the interface unchanged.

Suppose I tweak form validation's UX so that in addition to making invalid field borders red, the field labels also become red. That's an "Improvement".

If I change the internal structure of the form validation code to make adding new validation rules easier, but don't actually add any new rules, that's a "refactoring". The UX is unchanged - it just makes the programmers' lives easier in future.

Does that help clarify?

[Apostolique]

Nice! I wasn't thinking of changes like that.

[jagerber48]

It would be nice if keep a changelog gave guidance on what to do about these sorts of changes.

Right now a Refactored or Improved change doesn't have a category it can go into. It could go into Changed, but on the website Changed is defined as "for changes in existing functionality." But a refactoring or improvement might not change user-facing functionality in any way. Unless changing the backend of a feature (refactoring, making code more readable, etc.) is considered a "change in existing functionality" even though it's not user facing.

There are some comments throughout the discussions here that such changes that don't affect the end-user experience (and are more for devs) should not appear in the changelog. That would be ok, but

(1) There is no comment on the keep a changelog webpage to this effect and
(2) If documentation of such changes doesn't go in the changelog, then where does it go? Some of that historical information exists in the commit history, but probably in a fragmented and possibly non-cohesive way.

I think keep a changelog should address these questions.