Decouple search & replace from version bump

[kdeldycke]

• bump-my-version version: 0.5.0
• Python version: 3.11.4
• Operating System: macOS Ventura 13.4

Description

I'd like to discuss a use-case about my release workflow for Python packages.

The essential steps boils down to:

1. Prepare a release: consist in hard-coding of current version and other strings in some files
2. Tag with git, proceed to build and publish the Python package (not bump-my-version's business)
3. Post version bump with bump-my-version patch

I'm looking for a clean way to implement step #1 with bump-my-version.

I currently I have a chain of find, sed and perl CLIs to essentially perform a search and replace. BTW, that's where I need to fetch the current version, as discussed in #15.

Ideally, I would like to have a bump-my-version prepare-release shortcut, that would invoke a custom set of search/replace patterns under a custom prepare-release ID. That would be an addition to the default major/minor/patch subcommands.

I'm pretty sure bump-my-version doesn't support that use case. So I choose to call that feature search & replace without version bump or search & replace sub-group in this issue title. Feel free to change it if it makes more sense.

What I Did

Before bump-my-version, I used to rely on a quirk from bump2version. Which consisted in performing an adhoc search and replace using the CLI:

$ bumpversion --verbose --no-configured-files --search "/workflows/main/" --replace "/workflows/v{current_version}/" no-bump ./.github/workflows/tests.yaml
Reading config file .bumpversion.cfg:
[bumpversion]
current_version = 2.15.0
allow_dirty = True

[bumpversion:file:./changelog.md]
search = [{current_version} (unreleased)](
replace = [{new_version} (unreleased)](

Attempting to increment part 'no-bump'
Values are now: major=2, minor=15, patch=0
New version will be '2.15.0'
Asserting files ./.github/workflows/tests.yaml contain the version string...
Writing to config file .bumpversion.cfg:
[bumpversion]
current_version = 2.15.0
allow_dirty = True

[bumpversion:file:./changelog.md]
search = [{current_version} (unreleased)](
replace = [{new_version} (unreleased)](


current_version=2.15.0
allow_dirty=True
new_version=2.15.0
Would prepare Git commit
Would add changes in file './.github/workflows/tests.yaml' to Git
Would add changes in file '.bumpversion.cfg' to Git
Would commit to Git with message 'Bump version: 2.15.0 → 2.15.0'
Would tag 'v2.15.0' with message 'Bump version: 2.15.0 → 2.15.0' in Git and not signing

This would update the strings in my ./.github/workflows/tests.yaml file without bumping the internal version number.

Note how I used the no-bump version part, which doesn't exist anywhere in my configuration. That is the quirk I relied on, because bump2version was silently ignoring that random string.

Of course the exact same pattern doesn't work with bump-my-version:

$ bump-my-version --verbose --no-configured-files --search "/workflows/main/" --replace "/workflows/v{current_version}/" no-bump ./.github/workflows/tests.yaml
Starting BumpVersion 0.5.0                                                                                                                                                                                          
Reading config file pyproject.toml:                                                                                                                                                                                 
Specified version (2.17.3) does not match last tagged version (2.17.2)                                                                                                                                              
                                                                                                                                                                                                                    
 Usage: bump-my-version [OPTIONS] [ARGS]...                                                                                                                                                                         
                                                                                                                                                                                                                    
 Try 'bump-my-version --help' for help.                                                                                                                                                                                                                                                                                                                                                  
╭─ Error ──────────────────────────╮
│ Unknown version part: no-bump    │
╰──────────────────────────────────╯

[kdeldycke]

Digging into past forks, I found related issues:

• How to keep the metadata part when bumping version? peritus/bumpversion#205: which points to the need of a bumpversion release shortcut
• Allow executing only a subset peritus/bumpversion#38: Some workflows require an intermediate step between changing the version strings

[coordt]

@kdeldycke I need help understanding your 3 steps. I'm sure I'm missing something.

• What is the difference between steps 1 and 3?
• Is this about workflow (the steps to release) or managing parts of the version? Looking at the first fork you mentioned seems more version-part-management, but the second fork seems to be about workflow steps.

[kdeldycke]

• What is the difference between steps 1 and 3?

Before performing step 1#, I have links pointing to the main development branch. Like in my changelog where I have: https://github.com/kdeldycke/workflows/compare/v2.7.0...main. I cannot tag a release with this link, as I want to freeze it and point it to the stable tag. I.e. I want to transform that URL to https://github.com/kdeldycke/workflows/compare/v2.7.0...v2.8.0.

And there is dozen links of that kind, pointing to binary build, documentation, milestones, GitHub release, ... All must be frozen to the version I'm going to tag and push in step 2#. That is the role of step 1# and the release preparation.

Then, in step 3#, I need to revert back these frozen URLs to have them point back to the development branch. For my changelog it would be https://github.com/kdeldycke/workflows/compare/v2.8.0...main, now that the v2.8.0 tag exists.

In my most complex project, it would look like this:

• Step 1# - Prepare the release by freezing URLs and set current date: kdeldycke/meta-package-manager@b402b95
• Step 2# - Post-release version bump with bump-my-version patch: kdeldycke/meta-package-manager@1687f38

[kdeldycke]

• Is this about workflow (the steps to release) or managing parts of the version? Looking at the first fork you mentioned seems more version-part-management, but the second fork seems to be about workflow steps.

I mentioned these 2 issues because the 2 concepts are quite intertwined.

In the first link peritus/bumpversion#205, the user is introducing an artificial release version part, so he can insert a new, intermediate release action, in the middle of the traditional patch/minor/major cycle.

The problem is he cannot bend the version part definition in [bumpversion:part:release] to its need of replacing the constant -SNAPSHOT+4.2.1 suffix by +4.2.1 on bumpversion release invokation. And back to -SNAPSHOT+4.2.1 on bumpversion patch.

It seems the version part bump is tightly coupled with the search and replace set, so it is hard to implement this workaround. Hence my link to peritus/bumpversion#38, which seems to indicate the original author of bumpversion was aware of that need. As he proposed to implement execution of replacement subset as a way to address that.

[coordt]

Does this encapsulate your use case:

• Decouple bump-my-version's search and replace functionality from the version incrementing
• Allow users to execute the search and replace independently from version incrementing.

If so, and considering issue #15, I'm considering dividing bump-my-version into subcommands to make using the features easier.

What are your thoughts on this?

[kdeldycke]

Hmm... Let me check.

Yes. That would perfectly work. That's an excellent idea! 😍

Decoupling the two actions would cover for my use-case but also those hinted at elsewhere in tickets from past projects.

I'm pretty sure there are a lot of details to think of but even a first rough implementation would give a lot of flexibility to other users.

Now I don't know how hard it would be to implement, and how it would fit current bump-my-version internals. But I'm ready to beta-test the feature and provide feedbacks.

[coordt]

@kdeldycke Take a #30 to see if it works for you. I still need to add tests, but I hoped you could help me with that by finding any edge cases.

[kdeldycke]

@kdeldycke Take a #30 to see if it works for you. I still need to add tests, but I hoped you could help me with that by finding any edge cases.

Thanks @coordt for the 0.7.0 release! I'll try that out and report issues as I encounter them!