Why Do We Recommend `improvement` As A Type

[hutson]

Continuing the conversation from - #66 (comment)

Why do we recommend improvement as a type, and how is improvement better than using other types that signify improvements noticeable to downstream consumers, such as perf?

[damianopetrungaro]

As you can see I do not agree with the usage of refactor with a BREAKING CHANGE: into it, it's a contradiction imho 😄

I think it's more about lexical meaning of the words.

performance -> it's about performance
refactor -> it's about refactoring and it SHOULD NOT introduce BC
improvement -> it's like a refactor with interal BC.

I am totally open about discussing to remove/change it.

[Mouvedia]

In short improvement covers refactors that are not performance improvements.
e.g. readability, dead code removal (for compiled languages), algorithm replacement
Which means that the refactor type will only cover refactors that have a negative or neutral impact.

Would JSDoc comments be covered by docs?
What would be the scope of improvement?
Do you have other examples?
Unless we provide a clear definition of improvement we should drop it and limit ourselves to these.

[damianopetrungaro]

@Mouvedia we should NOT depend on external tools to decide about which type use.

See that the specs only support feat&fix and the usage of improvement is already described in the specs

 We also recommend improvement for commits that improve a current implementation without adding a new feature or fixing a bug

what we can do is add an example and add a section to the FAQ.
Or maybe rephrase the current explanation.

[Mouvedia]

Recommendations should not conflict with existing conventions that's all I am saying or it should perfectly cover the existing ones. If the lines are blurred it would introduce uncertainty and that's not desired.

[damianopetrungaro]

@Mouvedia @hbetts any update on this?

[Mouvedia]

1. we need use cases (Iv come up with some)
2. check if these are not already covered by more common types
3. if so, does having a more generic type like improvement an improvement over multiple types (perf, refactor, etc.)?
4. if there are cases left after 3, ask ourselves if it is still warranted
5. if it is, settle on a shortname: Is there an abbr for improvement? #66

[AoDev]

Hi,

A long time ago I submitted a question about the meaning of feat, here for context: #26

I just recently discovered the new "improvement" tag recommendation. Maybe it came from my original question(?) That said, to answer @Mouvedia questions:

Since my own question, I have been using the tag "imp", as "improvement", in all my projects.
The typical usage of this tag is when I improve the internal libraries of my apps. Libraries that could well be standalone and published as separate packages, but not worth the hassle until a second project requires them.

Cases where I do this:

• Any added functionality to "internal" libraries.
• New UI framework / generic UI components
• New features under feature flag: until the end-user sees it, it is not "feat"
• Subtle improvement in UI that is not worth considering a "feat", nor a "fix"

Example:

asyncUtils.js (an already existing collection of utilities to manage async code)

I find myself needing a new async utility to create a new feature, that would lead to two commits:

• imp(asyncUtils): added new function...
• feat(app): new feature that uses the new async utility

In summary: any added functionality to the "internals" of the app or library that is irrelevant to the end-user. They don't qualify as feat nor refactor.

I have been doing this for one year now. It works pretty well because I can generate changelog for end-users from feat and fix while keeping track of internal improvements and better split commits. And I find it funny, it makes me think of fairies. :P

[Mouvedia]

Alright here's my take based on your description:

• doesn't represent immediate changes for the user
• doesn't improve performance by itself
• doesn't modify an existing feature
• adds an inactive internal functionality
• always represents a step towards another type (feat, refactor, perf, etc.)

@AoDev Anything to add?

[AoDev]

@Mouvedia Yes that's a good definition of what I have in my head. Especially your last point is spot on I would say.

[Mouvedia]

This shit is goddamn narrow in scope. Would internal be more encompassing and easier to describe?

[AoDev]

I don't think it's a "goddamn narrow in scope".

If I look at my last project (medium size SPA)

Commits count go like this:
imp: 86
refactor: 72
feat: 70
fix: 41

It's the most used tag. Obviously it depends on app architecture. Personally I set a clear line between business logic (would lead to feat) and generic stuff (leads to imp).

[damianopetrungaro]

Closing this due to inactivity.

Feel free to re-open it if needed! 😄