Performence types of changes

[crakjie]

Would it be interesting to have a type of change that impact just performance?.
I saw that on some project and it's nice to scroll a change log and look for performence lines to know if it's good to upgrade or not.

[NateEag]

I suggested using 'Optimize' for such changes.

Even if the project never formally adopts that standard, you could certainly apply the standard to your own changelogs.

[matteoolivi]

IMO "Optimize" is too optimistic, it implies that performance improved. There could be changes that led to performance regressions, and should also be listed. Although I see that if a change leads to a performance regression probably that change goal wasn't altering performance (why making it worse?), but doing something else which is already covered by another entry in the changelog (e.g. add a feature, fix a bug, etc... ).

There might also be cases where the performance improved considerably as a side-effect of a change whose primary concern was not performance. IMO just leaving the information about the performance change "hidden" in the description of that entry could make it harder to discover.

I wonder whether notable performance changes should be listed in isolation no matter what, even if it leads to duplicate entries (e.g. an entry for a change C and a separate entry in a dedicated section for the performance changes that C introduced).

[NateEag]

@matteoolivi I think the changelog is about summarizing change intent, not results.

Many changes could result in performance improvements or regressions, but that isn't their intent, so it's not what we put in the changelog - we say what we were trying to do (like "fix bug X", even though sometimes those changes introduce new bugs themselves).

We do occasionally make changes to a codebase with the sole goal of making something run more quickly. I've not seen a change made with the explicit intent of making something slower.

Hence my suggestion of an "Optimize" verb, because once in a while we do make changes solely to try to speed something up.

[matteoolivi]

@matteoolivi I think the changelog is about summarizing change intent, not results.

Many changes could result in performance improvements or regressions, but that isn't their intent, so it's not what we put in the changelog - we say what we were trying to do (like "fix bug X", even though sometimes those changes introduce new bugs themselves).

@NateEag I disagree, what you describe is what happens most of the times because change intent is all that the change(log) authors are aware of. That is, they don't necessarily know that a performance regression was introduced. But if an intended change resulted in some big unintentional change in user visible behavior and that change gets discovered in my opinion it should be listed in the changelog.

I see that this case however might be rare enough not to deserve dedicated rules on how to track it in a changelog.

[NateEag]

That's a good point, @matteoolivi . Thanks for bringing it up!

I agree that it's rare for such events to happen, but it's definitely worth updating the changelog to note it when they're discovered.

[majormoses]

Ideally we as developers are writing performant code, changing existing code that is suboptimal is IMO already covered under "fixed" by the spec. I have spent many years reading changelogs, I have never seen the suggested field and am not quite grasping where it's unique and frequent enough here that it should get its own header.

[matteoolivi]

I was thinking about the opposite: introducing significant performance regressions. This happened to me in some cases when fixing bugs. The bug fix made the code much slower - to the point that the subset of users using the software at maximum scale had to take some adjustments. I see the argument on not doing this on the grounds that it isn't common enough.

[NateEag]

I'd put both major performance regressions and major correctness regressions under the heading of "Regressions".

I'd do that because I think of changelogs as living documents. They aren't set in stone - if you discover a major bug or issue in an old release, it's worth documenting in the changelog, even a long while after the fact. Yes, it should be in the bug tracker somewhere, so maybe it's not necessary, but it's a way to help people be aware at a glance exactly what changed in a version. It costs almost nothing and adds value for the long tail of software projects and users who only rarely upgrade versions (often, in such cases, to the version in the latest LTS of their OS, which may just wind up being a version with a regression).

Like I said, I don't think most bug / regressions call for that treatment - just major ones, things that would have major impact on most of the software's users.