keep-a-changelog
keep-a-changelog copied to clipboard
olivierlacan
Performence types of changes
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.
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.
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).
@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 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.
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.