feat!: specify commit type semver bump effects

[jasonkuhrt]

Will close #165

This is a backwards compatible change because the the SHOULD qualifer is used rather than MUST. However, I am not sure the weaker form is desirable here.

ISR = INITIAL STABLE RELEASE the proposed indicator for transition from initial development phase to post initial development phase.

• [ ] probably should spec how ISR and ! can play together nicely
• [ ] resolve if we should qualify with SHOULD or MUST
• [x] update examples
• [ ] update summary
• [ ] update to reflect 1.0 spec as per comment below

[jasonkuhrt]

I think SHOULD is not a good idea for this feature. While MUST would probably force quite a few tools to change as a result of this spec change (e.g. https://github.com/relekang/python-semantic-release) it is something that being not uniform across tooling would hurt. For example an accidental 1.0 release might lead to an immutable 1.0 release to a package registry, and various side-effect event triggers.

[JeanMertz]

(note that this PR is based off of beta 4, while 1.0 stable has since been released, my comment relates to the stable version of the spec, not the one present in this PR)

If there is an INITIAL STABLE RELEASE indication at the very beginning of the body section, or at the beginning of a line in the footer section [..]

There is no such thing (any more) as "the footer section". You either have one or more (well-defined) footers, or you have none. A well-defined footer is formatted (according to the spec) as follows:

Each footer MUST consist of a word token, followed by either a :<space> or <space># separator, followed by a string value (this is inspired by the git trailer convention).

For example, if you want to define a breaking change, you must add a description like this (or use ! in the header):

BREAKING CHANGE: the cause, fallout and/or recourse of this breaking change goes here

So we either make INITIAL STABLE RELEASE be a valid footer similar to breaking change, or we only allow it in the body (but that would be the first addition to the spec that makes the body anything other than free-form text).

I'm personally in favour of making this similar to BREAKING CHANGE and only allow this as a footer, just to keep the spec easier, and limit the amount of exceptions that exist to the current format.

[bcoe]

@jasonkuhrt @JeanMertz is this a feature that we could potentially support with the existing footer, e.g., Initial-Stable-Release: brief description of what this means for folks, I'm concerned about adding features like this to the spec, because it might bloat the specification significantly, and I've been trying to think more in the abstract, e.g., make sure the footer can support various interesting use cases like this.

As an example, for my own purposes I use the footer Release-As: v1.3.2, which allows you to override the next version of a library that will be released -- this is useful for my tooling at work, but I wouldn't define it in the spec... perhaps we could document these useful extensions somewhere outside the main specification?

[jasonkuhrt]

@JeanMertz thanks for the feedback, at first glance, totally agree. Going to add a todo item to the PR to address it.

@bcoe

perhaps we could document these useful extensions somewhere outside the main specification?

Sort of like what GraphQL Cursor Connections is to GraphQL. Makes sense to me.

But,

I would make the case that because the semantics before and after 1.x.x are enshrined in Semver, so to should they be enshrined by conventional commit.

[bcoe]

@jasonkuhrt sorry for the slow response, haven't had the time I'd like to dedicate to this project.

I'm still on the fence about adding more complexity to the spec ... but this is just my opinion.

What I think could be helpful to this project, would be a better process for how we discuss potential additions to the specification, so that when one maintainer disagrees it doesn't hold up PRs for months.

We're at the point where conventional commits is used by a lot of folks, and we could use a better defined process around discussing potential inclusions to the specification, e.g., maybe a regular meeting with some interested folks (we do this for Node.js, I know npm has a similar meeting).

[jasonkuhrt]

@bcoe np totally understand... been there. Cool, I'd be interested in attending such a thing. My team is building dripip which is deeply tied to conventional commit semantics.