dodgem 1.3.1

Version bumper for Python.

dodgem

Version bumper for Python project files.
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • Example: Bump Minor Version
   • Example: From Commit Message
   • Example: Custom Tags
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Sometimes you need to bump the version in your Python project files automatically. For example, you might:

• Have a CI/CD pipeline, and want to automatically bump the patch version of your library on merge to your develop branch
• Have a workflow (e.g. on Bitbucket Pipelines, GitHub actions etc.) that allows developers to automatically perform version bumps by including tags in their commit message (e.g. [major], [minor])
• Just want to reduce the chances of human error when bumping version numbers manually

Dodgem is a command-line utility for doing all of the above, and a bit more, aiming to eventually cover as many Python project file formats as possible, but currently supporting:

• setuptools (setup.py) with the version= named argument
• pyproject.toml managed by the Poetry dependency manager

Named after (version) bumper cars which are also sometimes called dodgems in some dialects of English.

(back to top)

Built With

This project uses:

• Click for its CLI
• Poetry for dependency management
• Blessings for colorized and formatted CLI output

(back to top)

Getting Started

Getting started is straightforward. Dodgem aims to automatically detect as much as possible.

Prerequisites

You'll need Python 3.7 or newer with pip to install Dodgem.

Installation

Install Dodgem using pip or your favourite Python dependency manager and you're done.

pip3 install dodgem

Test your installation with:

dodgem --help

You should see help documentation printed.

(back to top)

Usage

You can use dodgem --help for detailed information on using the utility:

Usage: dodgem [OPTIONS]

  Bump version numbers in a project file.

Options:
  --file TEXT              The file to parse (defaults to automatic
                           detection).
  --file-type TEXT         The file type to parse (defaults to automatic).
  --file-format TEXT       The file format to parse (defaults to automatic).
  --commit-message TEXT    The commit message to infer the version bump from.
  --no-auto-patch          If given, disables automatic patch version bump if
                           commit message provided.
  --major-tag TEXT         The commit message tag indicating a major version
                           bump.
  --minor-tag TEXT         The commit message tag indicating a minor version
                           bump.
  --patch-tag TEXT         The commit message tag indicating a patch version
                           bump.
  --prerelease-tag TEXT    The commit message tag indicating a prerelease
                           version bump.
  --ignore-tag-case        Ignores capitalization in commit message tags.
  --quiet                  Suppresses all extraneous output.
  --pep-440                Use PEP-440 for version strings.
  --bump-major             If given, performs a major version bump.
  --bump-minor             If given, performs a minor version bump.
  --bump-patch             If given, performs a patch version bump.
  --bump-prerelease        If given, performs a prerelease version bump.
  --bump-build             If given, performs a build version bump.
  --prerelease-token TEXT  The prerelease token to append.
  --build-token TEXT       The build token to append.
  --dry                    If given, does not write the version change to
                           disk.
  --help                   Show this message and exit.

Example: Bump Minor Version

Bump the minor version of your project like this:

dodgem --bump-minor

If you don't want to commit the change to disk, use --dry like so:

dodgem --bump-minor --dry

If the informational output given by the CLI is getting in the way of downstream processing, use --quiet:

dodgem --bump-minor --quiet

Example: From Commit Message

Dodgem can bump your project version based on a commit message. By default.

• If the message contains [major] then a major version bump will be performed
• If the message contains [minor] then a minor version bump will be performed
• Otherwise, a patch version bump will be performed

For example, to use your last git commit message to bump your projects version.

dodgem --commit-message="$(git log -1)"

Example: Custom Tags

If the default [major] and [minor] tags don't suit you, and you'd perfer (major), (minor) and an explicit (patch) tag:

dodgem --commit-message="$(git log -1)" --major-tag='(major)' --minor-tag='(minor)' --patch-tag='(patch)' --no-auto-patch

(back to top)

Roadmap

• Support setuptools (setup.py)
• Support Poetry
• Support prerelease/build versions (shoutout to @mitchelkoster for the feature idea)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Any contributions are very welcome. Please fork the project and open a PR, or open an issue if you've found a bug and/or would like to suggest a feature.

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Saul Johnson - @lambdacasserole - [e-mail]

Project Link: https://github.com/lambdacasserole/dodgem

(back to top)

Acknowledgments

The following resources are awesome:

• Best-README-Template was used for this readme
• tomlkit was used for parsing TOML in a way that preserves comments, order, formatting etc.
• semver was used for parsing and bumping semver numbers

Shoutout to @mitchelkoster for contributing a load of feature ideas, and rooting out a bunch of bugs and edge cases!

(back to top)