Home
About
Data
Processing...
Post
Home
Post
New Library - Bumpcalver
New Library - Bumpcalver
By
Mike Ryan
| Created: 25 Nov, 2024 07:08 PM | Category:
Programming
I prefer calendar versioning over semantic or other types of versioning. My logic for this is simple, "when was the library last updated" or when working with other teams, the business, etc.. it is much easier to talk about a year-month release pattern. So it is not due to some incredible logic, just ease of communication. So I created a library to update different types of files with the yyyy-mm-dd version. I would like to extend to quarters or other patterns of dates, but I am keeping it simplistic to start with. You can get the [BumpCalver library off Pypi](https://pypi.org/project/bumpcalver/) or get the code at [Github](https://github.com/devsetgo/bumpcalver). ----- [](https://pypi.python.org/pypi/bumpcalver/) [](https://pepy.tech/project/bumpcalver) [](https://pepy.tech/project/bumpcalver) [](https://pepy.tech/project/bumpcalver) Support Python Versions  [](https://github.com/astral-sh/ruff) [](./reports/coverage/index.html) [](./reports/coverage/index.html) CI/CD Pipeline: [](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml) [](https://github.com/devsetgo/bumpcalver/actions/workflows/testing.yml) SonarCloud: [](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver) [](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver) [](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver) [](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver) [](https://sonarcloud.io/dashboard?id=devsetgo_bumpcalver) # BumpCalver CLI Documentation ## Note This project should be consider in beta and is not yet ready for production use. ## Overview The **BumpCalver CLI** is a command-line interface for calendar-based version bumping. It automates the process of updating version strings in your project's files based on the current date and build count. Additionally, it can create Git tags and commit changes automatically. The CLI is highly configurable via a `pyproject.toml` file and supports various customization options to fit your project's needs. --- ## Table of Contents - Documentation Site: [BumpCalver CLI](https://devsetgo.github.io/bumpcalver/) - [Installation](#installation) - [Getting Started](#getting-started) - [Configuration](#configuration) - [Example Configuration](#example-configuration) - [Command-Line Usage](#command-line-usage) - [Options](#options) - [Examples](#examples) - [Error Handling](#error-handling) - [Support](#support) --- ## Installation To install the BumpCalver CLI, you can add it to your project's dependencies. If it's packaged as a Python module, you might install it via: ```bash pip install bumpcalver ``` *Note: Replace the installation command with the actual method based on how the package is distributed.* --- ## Getting Started 1. **Configure Your Project**: Create or update the `pyproject.toml` file in your project's root directory to include the `[tool.bumpcalver]` section with your desired settings. 2. **Run the CLI**: Use the `bumpcalver` command with appropriate options to bump your project's version. Example: ```bash bumpcalver --build --git-tag --auto-commit ``` --- ## Configuration The BumpCalver CLI relies on a `pyproject.toml` configuration file located at the root of your project. This file specifies how versioning should be handled, which files to update, and other settings. As an alternative, you can use configuration file named `bumpcalver.toml`. The CLI will look for this file if `pyproject.toml` is not found. ### Configuration Options - `version_format` (string): Format string for the version. Should include `{current_date}` and `{build_count}` placeholders. - `timezone` (string): Timezone for date calculations (e.g., `UTC`, `America/New_York`). - `file` (list of tables): Specifies which files to update and how to find the version string. - `path` (string): Path to the file to be updated. - `file_type` (string): Type of the file (e.g., `python`, `toml`, `yaml`, `json`, `xml`, `dockerfile`, `makefile`). - `variable` (string, optional): The variable name that holds the version string in the file. - `pattern` (string, optional): A regex pattern to find the version string. - `version_standard` (string, optional): The versioning standard to follow (e.g., `python` for PEP 440). - `git_tag` (boolean): Whether to create a Git tag with the new version. - `auto_commit` (boolean): Whether to automatically commit changes when creating a Git tag. ### Example Configuration ```toml [tool.bumpcalver] version_format = "{current_date}-{build_count:03}" timezone = "America/New_York" git_tag = true auto_commit = true [[tool.bumpcalver.file]] path = "pyproject.toml" file_type = "toml" variable = "project.version" version_standard = "python" [[tool.bumpcalver.file]] path = "examples/makefile" file_type = "makefile" variable = "APP_VERSION" version_standard = "default" [[tool.bumpcalver.file]] path = "examples/dockerfile" file_type = "dockerfile" variable = "arg.VERSION" version_standard = "default" [[tool.bumpcalver.file]] path = "examples/dockerfile" file_type = "dockerfile" variable = "env.APP_VERSION" version_standard = "default" [[tool.bumpcalver.file]] path = "examples/p.py" file_type = "python" variable = "__version__" version_standard = "python" ``` --- ## Command-Line Usage The CLI provides several options to customize the version bumping process. ```bash Usage: bumpcalver [OPTIONS] Options: --beta Use beta versioning. --build Use build count versioning. --timezone TEXT Timezone for date calculations (default: value from config or America/New_York). --git-tag / --no-git-tag Create a Git tag with the new version. --auto-commit / --no-auto-commit Automatically commit changes when creating a Git tag. --help Show this message and exit. ``` ### Options - `--beta`: Prefixes the version with `beta-`. - `--build`: Increments the build count based on the current date. - `--timezone`: Overrides the timezone specified in the configuration. - `--git-tag` / `--no-git-tag`: Forces Git tagging on or off, overriding the configuration. - `--auto-commit` / `--no-auto-commit`: Forces auto-commit on or off, overriding the configuration. --- ## Examples ### Basic Version Bump To bump the version using the current date and build count: ```bash bumpcalver --build ``` ### Beta Versioning To create a beta version: ```bash bumpcalver --build --beta ``` ### Specifying Timezone To use a specific timezone: ```bash bumpcalver --build --timezone Europe/London ``` ### Creating a Git Tag with Auto-Commit To bump the version, commit changes, and create a Git tag: ```bash bumpcalver --build --git-tag --auto-commit ``` --- ## Error Handling - **Unknown Timezone**: If an invalid timezone is specified, the default timezone (`America/New_York`) is used, and a warning is printed. - **File Not Found**: If a specified file is not found during version update, an error message is printed. - **Invalid Build Count**: If the existing build count in a file is invalid, it resets to `1`, and a warning is printed. - **Git Errors**: Errors during Git operations are caught, and an error message is displayed. - **Malformed Configuration**: If the `pyproject.toml` file is malformed, an error is printed, and the program exits. --- ## Support For issues or questions, please open an issue on the project's repository. ---
Word Count: 942
Tags: