Package: bumpsemver
bumpsemverCurrent version: 1.0.6A utility to simplify the version bumping for git repos.This application is a rework of the famousbumpversiontool. Theoriginal reposeems like abandoned. Several fundamental changes are
introduced, which make the fork-and-extend approach infeasible:dropped Python 2 supportboosted the test coverage to 95%+dropped many irrelevant features to reduce complexity. (e.g. customized version component support)introduced JSON support to make it work for package-lock.json, YAML support to make it work for Ansible playsnarrowed the versioning scheme to semver-onlyInstallationpip3installbumpsemverUsageThis application supports both the CLI mode and config file mode.Command Line Interfacebumpsemver[options]part[file]options(optional)Most of the configuration values described below can also be given as an option on the command-line.
Additionally, the following options are available:--dry-runDon't touch any files, just pretend. Best used with--verbose.--allow-dirtyNormally, bumpsemver will abort if the working directory is dirty to protect
yourself from releasing unversioned files and/or overwriting unsaved changes.
Use this option to override this check.--verbosePrint useful information to stderr-h, --helpPrint help and exitpartrequiredThe part of the version to increase. As we support semver only, the valid values include:major,minor, andpatch.For example, bumping filesrc/VERSIONfrom 0.5.1 to 0.6.0:bumpsemver--current-version0.5.1minorsrc/VERSIONfile(optional)default: noneThe file that will be modified.If not given, the list of[bumpsemver:file:…]sections from the configuration file will be used. If no files are
mentioned on the configuration file either, then no files will be modified.For example, bumping filesetup.pyfrom 1.1.9 to 2.0.0:bumpsemver --current-version 1.1.9 major setup.pyConfiguration fileOptions on the command line take precedence over those from the config file, which take precedence over those from the
defaults.Example.bumpsemver.cfg:[bumpsemver]current_version=0.2.9commit=Truetag=True[bumpsemver:file:README].bumpsemver.cfg-- Global configurationGeneral configuration is grouped in a[bumpsemver]section.current_versionrequireddefault: noneThe current version of the software package before bumping.Also available as CLI argument--current-version(e.g.bumpsemver --current-version 0.5.1 patch)tag = (True | False)(optional)default: False (Don't create a git tag)Whether to create a git tag, that is the new version, prefixed with the character "r". Don't forget togit-pushwith the--tagsflag.Also available as CLI argument--tagor--no-tag.sign_tags = (True | False)(optional)default: False (Don't sign tags)Whether to sign tags.Also available as CLI argument--sign-tagsor--no-sign-tags.tag_name =(optional)default:v{new_version}The name of the tag that will be created. Only valid whentag = True.It can be a template using thePython Format String Syntax.Available in the template context arecurrent_versionandnew_versionas well ascurrent_[part]andnew_[part](e.g. 'current_major' or 'new_patch'). You can also use the variablesnoworutcnowto get a current timestamp.
Both accept datetime formatting (when used like as in{now:%d.%m.%Y}).Also available as CLI argument--tag-name, for example:bumpsemver --tag-name 'release-{new_version}' patchIn addition, it is also possible to provide a tag message by using CLI--tag-message TAG_MESSAGE. Example usage:bumpsemver --tag-name 'release-{new_version}' --tag-message "Release {new_version}" patchIf neither tag message or sign tag is provided, we use alightweighttag in git. Otherwise, we utilize anannotatedgit tag. Read more about Git tagginghere.commit = (True | False)(optional)default:False (Don't create a commit)Create a commit using git when true.Also available as CLI argument--commitor--no-commit.message =(optional)default:[OPS] bumped version: {current_version} → {new_version}The commit message to use when creating a commit. Only valid when using--commit/commit = True.It can be a template using thePython Format String Syntax.Available in the template context arecurrent_versionandnew_versionas well ascurrent_[part]andnew_[part](e.g. 'current_major' or 'new_patch'). You can also use the variablesnoworutcnowto get a current timestamp.
Both accept datetime formatting (when used like as in{now:%d.%m.%Y}).Also available as CLI argument--message, for example:bumpsemver --tag-name 'release-{new_version}' patchIn addition, it is also possible to provide a tag message by using CLI--tag-message TAG_MESSAGE. Example usage:bumpsemver --message '[{now:%Y-%m-%d}] Jenkins Build {$BUILD_NUMBER}: {new_version}' patch.bumpsemver.cfg-- File specific configurationThis configuration is in the section:[bumpsemver:file:…]or[bumpsemver:json:…]Note: The configuration file format requires each section header to be unique. If you want to process a certain file
multiple times (e.g. multiple location to be replaced separately), you may append a description between parens to thefilekeyword:[bumpsemver:file (special one):…]. It does not matter what inside the parens, just make it unique.
e.g.[bumpsemver:file(1):README.md]search=current version: {current_version}replace=current version: {new_version}[bumpsemver:file(2):README.md]search=**Version: {current_version}**replace=current version: {new_version}search =default:{current_version}Template string how to search for the string to be replaced in the file. Useful if the remotest possibility exists that
the current version number might be present multiple times in the file and you mean to only bump one of the occurrences.replace =default:{new_version}Template to create the string that will replace the current version number in the file.Given thisrequirements.txt:Django>=1.5.6,<1.6
    MyProject==1.5.6using the following.bumpsemver.cfgwill ensure only the line containingMyProjectwill be changed:[bumpsemver]current_version=1.5.6[bumpsemver:file:requirements.txt]search=MyProject=={current_version}replace=MyProject=={new_version}With[bumpsemver:file:…], the specified file is processed as plain text file, which in fact makes this application
programming language neutral. However, it will be very error prone for complex file for examplepackage-lock.json.For randomly sampled 30 projects written in node.js/TypeScript, the classicalbumpversionor the renovatedbump2versionboth made
100% mistakes which changed something shouldn't be changed. A typical and relatively complex React projects contains 1000+ npm packagesindirectly. There are too many "version": "1.2.3" in that file. To address this issue,bumpsemveradded the support of json file.To use it:[bumpsemver:json:package-lock.json]jsonpath=versionValue of the parameterjsonpathis aJSONPathstring. For the typicalpackage.jsonorpackage-lock.json, usingversionor its jQuery-style alternative$.versionis sufficient.
Otherwise, anything can be selected with JSONPath is support, so, nothing we can't do. The underlying JSONPath processor
isjsonpath-ng. Checkout their document for some examples and hints.The suffix is also supported for json file:[bumpsemver:json(1):example.json]jsonpath=version[bumpsemver:json( same file):example.json]jsonpath=dependencies[2].*.version[bumpsemver:json (once again):example.json]jsonpath=dependencies[0].*.lodash.dependencies[1].versionComparably, YAML is supported for the same reason that we should support native JSON, like[bumpsemver:yaml:playbook.yml]yamlpath=versionOR[bumpsemver:yaml(1):playbook.yml]yamlpath=*.vars.project_version[bumpsemver:yaml( same file):playbook.yaml]yamlpath=*.vars.version[bumpsemver:yaml (once again):playbook.yaml]yamlpath=*.vars.app_versionPlease note that we useyamlpathinstead ofjsonpathhere.yamlpathis not a popular "standard" widely adopted. For complex scenarios, it makes sense to test the expression withyamlpath clibefore putting anything in the config file.TestTest in Docker container (recommended):maketestLocal test in the working environment (not recommended):toxTo test the compatibility with a specific version of Python, put the version(s) into./python-versions.txtone version
per line. Then run:maketest