Support placeholders for local version bumping

[adamcunnington-gdt]

Local versions do not have to consist of pure numbers - according to either Semantic Version Specification or PEP 440.

It is common to use things like branch names or long/short commit SHAs in local version identifiers. It would be great if commitizen would be smart enough to allow me to bump a local version based on some pattern containing placeholders that commitizen is capable of replacing.

If not, a workaround would be to allow me to specify the entire version manually - I opened a separate issue for that here. Other than that, I don't think there is a workaround right now and I am not able to use commitizen for my dev versions.

[Lee-W]

Sorry, I'm a bit confused. Is it a duplicate issue to #435?

[adamcunnington-gdt]

No. Not at all.

The local version label is the bit after the +

For example, in the following version string,
X.Y.Z+foo.bar
foo.bar is the local version label

foo.bar need not be integers (although they can be). They can be strings and this is common seeing as local version labels are often used to provide descriptive context. This issue is asking for placeholder strings for example (at least these) {{ branch }} and {{ short-commit }} and {{ long-commit }}.

The desired behaviour would be that you could specify this placeholder in some config and then when calling cz bump --local-version, non-integer parts would simply be updated. Integer parts would continue to be incremented. Here are some examples:

Current Version: 1.0.0+foo.1.0
Local Version Pattern: {{ branch }}.1.0
Expected Version after cz bump --local-version: foo.2.0

Current Version: 1.0.0+foo.1c002d
Local Version Pattern: {{ branch }}.{{ short-commit }}
Expected Version after cz bump --local-version: foo.d92197

P.s. it's not clear to me what logic you use to increment different parts of the local version. Docs just talk about +0.1.0 becoming +0.2.0 so that's the example i've used above.

[Lee-W]

Got your point. I'm okay with this one. But need @woile 's thought as well

[woile]

I like this idea. I'm not a user of local-versions per-se, and I'd like to avoid any breaking change for people who are already using it.
So I guess as long as the current tests pass we are good to go.

I guess we could make new tag_formats including the new variables?

[tool.commitizen]
tag_format = "v$major.$minor.$patch$prerelease+$branch-$shortcommit-$longcommit-$localversion"

Would something like that work for you?

[adamcunnington-gdt]

@woile thanks for the response.

Sort of but 2 things to clarify:

1. I see this pertaining to the local version portion only (everything after the +. I'm not quite sure specifically what $localversion relates to in your example).
2. This needs to affect the actual version, not just the tag_format.

I think instead, something like this might be better

[tool.commitizen]
version = 1.0.0
local_version_format = "$branch-$shortcommit"
tag_format = "v$major.$minor.$patch+$branch-$shortcommit" # deliberately not trying to expand $local_version_format here because $local_version_format might be overridden by some CLI arg

The way this would work with the above example is something like this cz bump --local-version which would do:
1.0.0 -> 1.0.0+foo-d92197
Probably --local-version-format can also be specified when doing a bump too (as an override).

There is still the brainfart of compatibility between PEP440 and SemVer to sort though. If you gave me the above, I still couldn't use it because I need 1.0.0.dev0+foo-d92197 and I can't add the .dev0 bit in my version identifier until you solve this problem. My short term workaround is just to set dev versions manually - which I'd like to do via commitizen - which is what #435 is about.

[adamcunnington-gdt]

@woile what do you think? what are the next steps?

[woile]

Local versions are specified in pep440#localversions and if we were to make changes, it should continue to work. Maybe it's not necessary to add them as part of the tag_format.
localversions in semver are just part of the metadata, so it also shouldn't be problem in the future if semver is supported, right?

I like your proposal, as long as the current --local-version keeps working as well.
We can also start this with a draft an start commenting on it.
Would that work okay for you @adamcunnington-gdt ?

Sorry for the late replies, I've been quite busy lately

[adamcunnington-gdt]

Sure, I think so.

[adamcunnington-mlg]

Could this be picked up in upcoming sprint?

[Lee-W]

Sure! Feel free to pick it up anytime 👍

[woile]

Closing as there has not been enough interest for this feature. Feel free to open a new issue with the full proposal discussed here.