Add `--pin` cli flag to disable auto incrementing of parts.

[dg-pb]

bumpver test '2023.1053-b0' 'YYYY.BUILD[-PYTAGNUM]' --tag-num       # 2023.1054-b0

[mbarkhau]

Yes: The BUILD part will always increment and the logic is that all parts to the right of it are then reset to their default value.

We have a flag --pin-date to handle a similar issue. Perhaps we can add a cli flag which pins all parts unless they are explicitly set to be incremented.

[dg-pb]

bumpver test '2023.1053-b0' 'YYYY.BUILD[-PYTAGNUM]' --tag-num

and

bumpver test '2023.1053-b0' 'YYYY.BUILD[-PYTAGNUM]'

both give the same answer. How do I get '2023.1053-b1' then? What am I missing?

[mbarkhau]

I don't think you can. As I said, the rollover logic causes a reset of the tag number. You would need to pin the build number.

[dg-pb]

But is this a 'right' way for it to be? It would seem sensible if '--tag-num' only incremented PYTAGNUM.

[mbarkhau]

Backwards compatibility is paramount. So yes, this is how it's going to stay.

The only question is if we add a new CLI flag, similar to what we did with --pin-date.

[dg-pb]

That's fair.

In "Pattern Examples" table it is the only one which is PEP compliant and maintains lexicographic ordering. I would guess it is a widely used one? How is it made to function elsewhere? Do you know any resources that aren't using bumpver, but are using this pattern?

I am looking into raw "NUM" now. Is it even possible to use it now? Or is not intended to be used on its own (not part of PYTAGNUM)? bumpver test '2023.1053-0' 'YYYY.BUILD-NUM' --tag-num

I regarding the change, I have a suggestion. There are already many flags to use with PYTAGNUM and adding another one does feel too verbose. After all, ideally it was to function exactly as: bumpver test '1.2.4b0' 'MAJOR.MINOR.PATCH[PYTAGNUM]' --tag-num

What about adding a new pattern part? Say CNUM (Custom number), which acts the same as MAJOR/MINOR/PATCH, except user can specify starting number. Say CNUM1001, would be exactly the same as BUILD, except properly handles --tag-num flag.

Reasoning why it could be a good idea:

1. Doesn't break existing functionality
2. Fixes (if it's broken, I am open to reasoning why it is not) my issue
3. Adds a new functionality, which isn't there. After all, lexicographic ordering isn't exactly maintained, is it? BUILD is in [1001, ..., 22000] and $python -c "print('1002'<'10001')". To a company, which has >10000 builds per month it would provide an option to maintain it. And to a company which has strictly less than 100, would provide an option to have a more concise version. i.e. YYYY.CNUM101. And changing it later to a longer one would still maintain lexicographic ordering (but couldn't parse the old ones with bumpver anymore...).

[mbarkhau]

I'm not a fan of adding a new part. As far as I can tell, NUM can be used as is for the purpose you describe in 3.

I'm currently leaning toward adding a flag that disables all auto incrementing, so that only parts for which an explicit cli flag is provided are incremented. Perhaps --no-auto-incr.

[dg-pb]

Could you provide and example how NUM can be used for the purpose I have described in 3?

Adding a flag would solve my problems, (Well, apart from the fact that I would have to use extensive number of flags to achieve very basic outcome) but this approach sounds a bit hacky, although I appreciate that it can be much easier to achieve (I am not familiar with the workings of a library - just a simple user looking for a quick versioning solution).

[mbarkhau]

I'm sorry, upon reading it again, I'm not sure I understand what you're describing in 3.

[dg-pb]

"A further consideration for the choice of your version_pattern is that it may be processed by tools that do not interpret it as a version number, but treat it just like any other string. It may also be confusing to your users if they a list of version numbers, sorted lexicographically by some tool (e.g. from git tags) and versions are not listed in order of their release: 18.6b4 18.9b0 19.10b0 19.3b0 20.8b0 20.8b1 "

So, supposedly, BUILD tag maintains lexicographic ordering as it starts from 1001. However, it only maintains it up to 10000

$ python -c "print('1001'<'9999')"
True
$ python -c "print('1001'<'10000')"
False

So I appreciate, that it is very unlikely that someone has more than 9000 builds without incrementing any of the higher parts.

However, Providing a new part with starting number of choice, would ensure that there is a definite option for any case possible.

While this would cover such very unlikely case by having so many builds, it would also provide a shorter option for companies, who have less than 900 builds. Then they can start incrementing from 101.

By having such part behave like MAJOR/MINOR/PATCH it would solve the issue that I am having at the same time, without needing extensive number of flags.

[mbarkhau]

I think you've misunderstood how BUILD is incremented. See lexid.

>>> import lexid
>>> lexid.incr("1001")
'1002'
>>> lexid.incr("1002")
'1003'
>>> lexid.incr("1998")
'1999'
>>> lexid.incr("1999")
'22000'
>>> lexid.incr("22000")
'22001'

[dg-pb]

Ok, I see now. It is good to know, I should have read it more thoroughly in the first place. Thanks for taking your time.

Given this is the case, I see that my proposal for new part is not sensible.

New flag does sound more sensible then. Although I wander if there is a solution which does not involve needing 2 long flags for one increment.

[dg-pb]

Although, giving it another thought, new part still makes sense, just not as I described, but identical to BUILD.

And correct me if I am wrong, but it might be even easier to implement it than new flag.

For new flag, new logic is needed to implement.

For such new part all logic is already there: individual incrementing of BUILD and total increment resolution that as of MAJOR/MINOR/PATCH.

Although the new flag might be useful as a temporary solution to cover cases that are not well defined, but what it reads to me is "an ability to increment manually while using the package whose purpose is to increment automatically".

[mbarkhau]

I'm leaning toward a flag cli flag called --pin.

"an ability to increment manually while using the package whose purpose is to increment automatically".

Well, you might be using it as a specialized search and replace tool. Modifying half a dozen files manually can be error prone and so this helps you with that, even if you never want to use auto increment parts (e.g. SemVer).

[dg-pb]

This will work for the time being, but I hope new part as I described can stay as a potential for the future. My projects are still at initial stages and versioning has not yet reached priority list.

When it does, I am most likely aim for auto-incrementing YYYY.BUILD[PYTAGNUM] and would be lovely if I was able to use this package.

$ bumpver test '2023.1053b0' 'YYYY.MAJOR[PYTAGNUM]' --tag-num
New Version: 2023.1053b1

Works like charm, but it lacks lexico...

$ bumpver test '2023.1053b0' 'YYYY.BUILD[PYTAGNUM]' --tag-num
New Version: 2023.1054b0

Has lexico, but doesn't behave in expected manner.

--pin flag solves it, but overcomplicates things from user's perspective. For the long term using such approach would not be satisfiable from my point of view.

Maybe MAJORL part could be of use. In this case, it could be used on its own as a substitute to BUILD, while also providing lexico. to MAJOR.MINOR.PATCH pattern if anyone needs it.

[dg-pb]

Would it be hard to write such extension for your library myself? Does some sort of standard extension interface exist?

[mbarkhau]

I don't see the need for a new part and there is no extension system for new parts. Numbered alpha/beta/rc releases are a perfectly reasonable use case for the --pin flag.