Changed semantics

[themerius]

Hi there,

we have the following groups:

• Group changes to describe their impact on the project, as follows:
  • Added for new features. (+MINOR)
  • Changed for changes in existing functionality. (+MINOR or +MAJOR)
  • Deprecated for once-stable features removed in upcoming releases. (+MINOR)
  • Removed for deprecated features removed in this release. (+MAJOR)
  • Fixed for any bug fixes. (+PATCH)
  • Security to invite users to upgrade in case of vulnerabilities. (+PATCH)

I've added here which version number each group affects. For Changed it is possible to have altered existing functionality in such a way that you must increment MAJOR, but you can also have changes which only have to increment MINOR.

For example:

• MINOR: You've altered a existing functionality in such a way, that it is faster or it is slightly reconfigured or refactored. The interface hasn't changed, so it would be an overkill to increment MAJOR?!
• MAJOR: You've altered the functionality in an API incompatible way.

It may be useful to distinguish Changed changes for MINOR or MAJOR, so that the reader sees this immediately? Maybe it is useful to add to the spec something like Changed minor or Adjustment or Improvement to point out its an API compatible change in existing functionality?

[mbrand12]

Or maybe just putting the changes in the order from most important (major) to least important (patch) in the group changes and just having a blank line between those sub groups if necessary. This ensures that the major changes are read fist. I think that it is important not to have to many groups or sub groups.

Also we already have a [breaking] tag for changes that break the established api, though I don't know weather that is officially included in the spec. I also use a [feature] tag to bring attention to the major additions (functionality) that are included for the first time.

[themerius]

I haven't found a definition of a [breaking] tag or the like in the spec. I'll claim that Adjustment or Improvement would be much clearer and more formal. Such tags you can easily forget to add.

[mbrand12]

My bad, it was discussed in #41 and not a part of the spec, for some reason I just accepted it as a part of the spec (since it makes sense to me).

[zerok]

@themerius What is the motivation behind this 3-way-split? Do you use this information for instance to generate a new version number (based on SemVer) or is this purely information? I'm asking because personally I've so far only seen a benefit in the "breaking" aspect of this in my own workflow. This section would also be the one I'd be looking at when auto-updating a dependency, for instance :-)

[themerius]

@zerok I think with such an approach it is more clear. Also for automated processing. You can see in my initial post, that CHANGED serves two meanings whereas all other groups serve only one meaning.

Therefore I think it is nice to have a either a less powerful CHANGED (minor) term or a more powerful CHANGED (major) term. Like ADJUSTMENT for a minor change. Or tags like @mbrand12 mentioned.

[Art4]

@themerius Please consider also point 4 of the semver specification.

4. Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable

So Removed can be used for deprecated features removed in a MAJOR release and MINOR release in development.

[patrickblackjr]

I use a Improved tag sometimes as well, I like my users to know when something is changed for the better, not just changed.

[ScottFreeCode]

I think the relationship of most of these to semantic versioning concepts is fairly obvious and does not, in general, need to be spelled out. (Although we could debate whether Changed is appropriate for changes that retain backwards compatibility or if such changes are really Added to the functionality, even if they aren't adding a whole new feature.) I would, however, like to see a recommendation to order the groups by 1) security first because it's security, 2) the backwards-incompatible and then 3) the backwards-compatible. (I also don't care that much about categorizing things into major and minor in an ordinary, non-semantic-versioning sense of how big a deal they are, because that's better judged by the user anyway with knowledge of how the changes affect them.)

[gilmrjc]

I think this issue should be closed, and keep conversation on #41. About the order, I feel you should put breaking changes first, non-breaking changes after and security in its own section.

I guess the main problem with the proposed semantics is that people want to be more specific than they should. Breaking vs non-breaking changes can be addressed at a UPDATING file or section inside documentation. For me this information should be properly documented outside the change log and inside it could fit as an optional tag, not a requirement.

[cdbennett]

@gilmrjc Maybe sometimes people want to be too specific, or have too many different classifications for changes (Changed, Added, ...) but one of the most important things to find from the change log is whether there are any breaking changes in a new release, and if so, whether they affect your specific situation.

From keepachangelog.com:

When people upgrade from one version to another, it should be painfully clear when something will break. It should be possible to upgrade to a version that lists deprecations, remove what's deprecated, then upgrade to the version where the deprecations become removals.

If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.