Breaking changes below v1 bump major version number

[Kurt-von-Laven]

Description

The SemVer spec dictates that: "major version zero (0.y.z) is for initial development" and "Version 1.0.0 defines the public API." A change during the initial development stage may be denoted as breaking, but there is little likelihood that implies the public API is stable. Bumping 0.y.z to 1.0.0 on the first breaking change encourages a common misconception of SemVer, that major version 0 is no different from any other. More importantly, this behavior can cause unstable software to be accidentally, abruptly, and irreversibly declared stable. It can still be helpful to consistently track which commits introduce breaking changes during initial development, and Commitizen supports a very clear syntax for doing that. If folks are not sure what cz bump will do, they can, of course, always run cz bump --dry-run. They may also use cz bump --increment MINOR in lieu of cz bump for breaking changes at major version 0, but this may be a hassle to configure when Commitizen runs in CI.

Steps to reproduce

1. Create a new project with major version 0.
2. Run cz commit.
3. Select feat.
4. Declare the change breaking.
5. Complete the commit.
6. Run cz bump.

Current behavior

cz bump bumps to 1.0.0.

Desired behavior

At major version 0, cz bump bumps the minor version number for all feat changes, breaking or otherwise. Behavior is unchanged when major version > 0.

Screenshots

No response

Environment

Commitizen Version: 2.24.0 Python Version: 3.10.4 (main, Apr 5 2022, 17:28:03) [GCC 11.2.0] Operating System: Linux

[woile]

The request makes sense, but how would the workflow go to bump to v1? At the moment by using breaking change you leave 0.x, if we remove that, you'd be stuck in 0.x, no?

[Kurt-von-Laven]

Good point! That deserves some thought. The first thing that comes to mind for me would be to introduce a new “INITIAL-STABLE-API” footer label. A more flexible option might be to support "INCREMENT-MAJOR," "INCREMENT-MINOR," and "INCREMENT-PATCH" footer labels that override the default bumping behavior for an individual commit. People could run cz bump —increment MAJOR manually, but relying on that alone seems likely to create a lot of confusion.

[E-dC]

Perhaps it would make sense to define an additional cz bump option, something like:

• cz bump --initial-development for CLI and
• initial_development = true for config

This way you could explicitly say to commitizen "No major release yet", and when you're ready to release a stable version, you can just remove initial_development = true.

That could even be an additional question when running cz init.

[woile]

Interesting, I think we could introduce something like that. I would prefer a more meaningful name though.

[E-dC]

A few ideas:

• no_major
• no_major_increment
• no_major_version
• minor_on_breaking_change

[woile]

Those would be confussing for people on >1. Anyway, I'm open to a PR, we could think the name of the config there. skip_major_version_on_breaking_changge_for_initial_development 😅 too long I guess

[Kurt-von-Laven]

I like the direction this is going. A related approach inspired by this discussion would be a max_increment option defaulting to MAJOR. SemVer users beneath v1 could set max_increment = MINOR. Hopefully few users on v1+ would be tempted to set such an option, although we would also want to clarify that in the documentation regardless of the specific approach selected. If someone wanted to use Commitizen for a project that needed to track the major and minor versions of another project, they could even configure max_increment = PATCH. We would need to clearly document what happens if conflicting options are specified (e.g., cz bump --increment MAJOR --max-increment MINOR seems like it should throw an error with a helpful message, and the value of a given argument on the command line should supersede the value in any config file). What would be most consistent with the existing design if someone ran cz bump --max-increment MINOR when a commit since the last release declared a breaking change? My personal instinct would be that the command line would preside in such a case since it presides over feat, fix, refactor, etc. commit message prefixes.

[jenstroeger]

Definitely a required feature, I agree. The semantic-release tool provides a major-on-zero config setting for this purpose.

My personal take on this would be to add a command-line switch --major-version-zero for bump and a configuration setting major_version_zero = true which keeps the major version at zero. Always. It would be the equivalent of

bump_map = {"break" = "MINOR", "new" = "MINOR", "fix" = "PATCH", "hotfix" = "PATCH"}

plus the added assertion that the current major version is zero.

If at some point the software reaches maturity, users can remove that major-version-zero setting using a feat!: commit which would then bump to v1.0.0.

The setting should issue a warning if used for existing versions greater than zero.

[woile]

I really like this proposal @jenstroeger. Anyone wants to pick this up?

[jenstroeger]

I actually need this feature so I can work on a PR.

@Kurt-von-Laven unless you want to, it’s your issue?

[Kurt-von-Laven]

Go for it. Spread a bit thin at the moment.

[jenstroeger]

Alright, I’ll noodle through the issue this week and submit a PR based on comment https://github.com/commitizen-tools/commitizen/issues/501#issuecomment-1255345774 above.