BumpCalver Library

Description	Simple Calendar Versioning Library
Author(s)	Mike Ryan
Repository	https://github.com/devsetgo/bumpcalver
Copyright	Copyright © 2024 - 2025 Mike Ryan

Support Python Versions

CI/CD Pipeline:

SonarCloud:

BumpCalver CLI Documentation¶

Note¶

This project should be consider in beta as it could have bugs due to being only a few months old.

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
Installation
Getting Started
Command-Line Usage
Options
Error Handling
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:

pip install bumpcalver

Note: Replace the installation command with the actual method based on how the package is distributed.

Getting Started¶

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.
Run the CLI: Use the bumpcalver command with appropriate options to bump your project's version.

Example:

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.
date_format (string): Format string for the date. Supports various combinations of year, month, day, quarter, and week.
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, properties, env, setup.cfg).
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¶

[tool.bumpcalver]
version_format = "{current_date}-{build_count:03}"
date_format = "%y.%m.%d"
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"

[[tool.bumpcalver.file]]
path = "sonar-project.properties"
file_type = "properties"
variable = "sonar.projectVersion"
version_standard = "default"

[[tool.bumpcalver.file]]
path = ".env"
file_type = "env"
variable = "VERSION"
version_standard = "default"

[[tool.bumpcalver.file]]
path = "setup.cfg"
file_type = "setup.cfg"
variable = "metadata.version"
version_standard = "python"

Date Format Examples¶

The date_format option allows you to customize the date format used in version strings. Here are some examples of how to format dates:

%Y.%m.%d - Full year, month, and day (e.g., 2024.12.25)
%y.%m.%d - Year without century, month, and day (e.g., 24.12.25)
%y.Q%q - Year and quarter (e.g., 24.Q1)
%y.%m - Year and month (e.g., 24.12)
%y.%j - Year and day of the year (e.g., 24.001 for January 1st, 2024)
%Y.%j - Full year and day of the year (e.g., 2024.001 for January 1st, 2024)
%Y.%m - Full year and month (e.g., 2024.12)
%Y.Q%q - Full year and quarter (e.g., 2024.Q1)

Refer to the Python datetime documentation for more format codes.

Supported File Types¶

BumpCalver supports version management for the following file types:

Core File Types¶

python - Python files with version variables (e.g., __version__ = "1.0.0")
toml - TOML configuration files (e.g., pyproject.toml)
yaml - YAML configuration files
json - JSON configuration files (e.g., package.json)
xml - XML configuration files

Infrastructure Files¶

dockerfile - Docker files with ARG or ENV variables
makefile - Makefiles with version variables

Configuration Files¶

properties - Java-style properties files (e.g., sonar-project.properties)
Format: key=value
Example: sonar.projectVersion=2025.02.02
env - Environment variable files (e.g., .env)
Format: KEY=value or KEY="value"
Example: VERSION=2025.02.02
setup.cfg - Python setup configuration files
Supports both dot notation (metadata.version) and simple keys (version)
Example: version = 2025.02.02 in [metadata] section

Command-Line Usage¶

The CLI provides several options to customize the version bumping process.

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:

bumpcalver --build

Beta Versioning¶

To create a beta version:

bumpcalver --build --beta

Specifying Timezone¶

To use a specific timezone:

bumpcalver --build --timezone Europe/London

Creating a Git Tag with Auto-Commit¶

To bump the version, commit changes, and create a Git tag:

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.

Quick Start¶

Install¶

pip install bumpcalver

Usage¶

Initialize Configuration¶

Create a pyproject.toml file in your project's root directory with the following content:

tool.bumpcalver]
version_format = "{current_date}-{build_count:03}"
date_format = "%y.%m.%d"
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 = "sonar-project.properties"
file_type = "properties"
variable = "sonar.projectVersion"
version_standard = "default"

[[tool.bumpcalver.file]]
path = ".env"
file_type = "env"
variable = "VERSION"
version_standard = "default"

[[tool.bumpcalver.file]]
path = "setup.cfg"
file_type = "setup.cfg"
variable = "metadata.version"
version_standard = "python"

This configuration tells BumpCalver how to format your version strings, which timezone to use, and which files to update.

Basic Version Bump¶

To bump the version using the current date and build count:

bumpcalver --build

This command will:

Increment the build count for the current date.
Update the __version__ variable in version.py and src/module_name/__init__.py.
Use the timezone specified in your configuration (UTC in this case).

Beta Versioning¶

To create a beta version:

bumpcalver --build --beta

This will prefix your version with beta-, resulting in a version like beta-2023-10-05-001.

Specify Timezone¶

To use a specific timezone (overriding the configuration):

bumpcalver --build --timezone Europe/London

Create a Git Tag with Auto-Commit¶

To bump the version, commit changes, and create a Git tag:

bumpcalver --build --git-tag --auto-commit

This command will:

Update the version as before.
Commit the changes to Git.
Create a Git tag with the new version.

Additional Options¶

Disable Git Tagging:

bumpcalver --build --no-git-tag

Disable Auto-Commit:

bumpcalver --build --no-auto-commit

Create Custom Date Formats¶

The date_format option in the configuration file allows you to customize the date format used in version strings. Here are some examples of how to format dates:

%Y.%m.%d - Full year, month, and day (e.g., 2024.12.25)
%y.%m.%d - Year without century, month, and day (e.g., 24.12.25)
%y.Q%q - Year and quarter (e.g., 24.Q1)
%y.%m - Year and month (e.g., 24.12)
%y.%j - Year and day of the year (e.g., 24.001 for January 1st, 2024)
%Y.%j - Full year and day of the year (e.g., 2024.001 for January 1st, 2024)
%Y.%m - Full year and month (e.g., 2024.12)
%Y.Q%q - Full year and quarter (e.g., 2024.Q1)

See Documentation¶

For more examples and advanced usage, please refer to the full documentation or visit the project's repository.

Note: Replace # with the actual link to your documentation or repository.

Example `version.py` File¶

Ensure that your version.py file (or the file specified in your configuration) contains the version variable:

__version__ = "0.1.0"

After running bumpcalver --build, it will be updated to:

__version__ = "2023-10-05-001"

Integrate with Your Project¶

You can import the version into your application as needed:

from version import __version__

print(f"Current version: {__version__}")

Summary¶

With BumpCalver, you can automate version management based on the calendar date and build counts, ensuring consistent and meaningful version numbers across your project.

Timezones¶

Here is a list of all timezones that can be utilized. You can search for a specific timezone by typing in the search bar.

Timezone	UTC Offset
Africa/Abidjan	UTC+00:00
Africa/Accra	UTC+00:00
Africa/Addis_Ababa	UTC+03:00
Africa/Algiers	UTC+01:00
Africa/Asmara	UTC+03:00
Africa/Asmera	UTC+03:00
Africa/Bamako	UTC+00:00
Africa/Bangui	UTC+01:00
Africa/Banjul	UTC+00:00
Africa/Bissau	UTC+00:00
Africa/Blantyre	UTC+02:00
Africa/Brazzaville	UTC+01:00
Africa/Bujumbura	UTC+02:00
Africa/Cairo	UTC+03:00
Africa/Casablanca	UTC+01:00
Africa/Ceuta	UTC+02:00
Africa/Conakry	UTC+00:00
Africa/Dakar	UTC+00:00
Africa/Dar_es_Salaam	UTC+03:00
Africa/Djibouti	UTC+03:00
Africa/Douala	UTC+01:00
Africa/El_Aaiun	UTC+01:00
Africa/Freetown	UTC+00:00
Africa/Gaborone	UTC+02:00
Africa/Harare	UTC+02:00
Africa/Johannesburg	UTC+02:00
Africa/Juba	UTC+02:00
Africa/Kampala	UTC+03:00
Africa/Khartoum	UTC+02:00
Africa/Kigali	UTC+02:00
Africa/Kinshasa	UTC+01:00
Africa/Lagos	UTC+01:00
Africa/Libreville	UTC+01:00
Africa/Lome	UTC+00:00
Africa/Luanda	UTC+01:00
Africa/Lubumbashi	UTC+02:00
Africa/Lusaka	UTC+02:00
Africa/Malabo	UTC+01:00
Africa/Maputo	UTC+02:00
Africa/Maseru	UTC+02:00
Africa/Mbabane	UTC+02:00
Africa/Mogadishu	UTC+03:00
Africa/Monrovia	UTC+00:00
Africa/Nairobi	UTC+03:00
Africa/Ndjamena	UTC+01:00
Africa/Niamey	UTC+01:00
Africa/Nouakchott	UTC+00:00
Africa/Ouagadougou	UTC+00:00
Africa/Porto-Novo	UTC+01:00
Africa/Sao_Tome	UTC+00:00
Africa/Timbuktu	UTC+00:00
Africa/Tripoli	UTC+02:00
Africa/Tunis	UTC+01:00
Africa/Windhoek	UTC+02:00
America/Adak	UTC-09:00
America/Anchorage	UTC-08:00
America/Anguilla	UTC-04:00
America/Antigua	UTC-04:00
America/Araguaina	UTC-03:00
America/Argentina/Buenos_Aires	UTC-03:00
America/Argentina/Catamarca	UTC-03:00
America/Argentina/ComodRivadavia	UTC-03:00
America/Argentina/Cordoba	UTC-03:00
America/Argentina/Jujuy	UTC-03:00
America/Argentina/La_Rioja	UTC-03:00
America/Argentina/Mendoza	UTC-03:00
America/Argentina/Rio_Gallegos	UTC-03:00
America/Argentina/Salta	UTC-03:00
America/Argentina/San_Juan	UTC-03:00
America/Argentina/San_Luis	UTC-03:00
America/Argentina/Tucuman	UTC-03:00
America/Argentina/Ushuaia	UTC-03:00
America/Aruba	UTC-04:00
America/Asuncion	UTC-04:00
America/Atikokan	UTC-05:00
America/Atka	UTC-09:00
America/Bahia	UTC-03:00
America/Bahia_Banderas	UTC-06:00
America/Barbados	UTC-04:00
America/Belem	UTC-03:00
America/Belize	UTC-06:00
America/Blanc-Sablon	UTC-04:00
America/Boa_Vista	UTC-04:00
America/Bogota	UTC-05:00
America/Boise	UTC-06:00
America/Buenos_Aires	UTC-03:00
America/Cambridge_Bay	UTC-06:00
America/Campo_Grande	UTC-04:00
America/Cancun	UTC-05:00
America/Caracas	UTC-04:00
America/Catamarca	UTC-03:00
America/Cayenne	UTC-03:00
America/Cayman	UTC-05:00
America/Chicago	UTC-05:00
America/Chihuahua	UTC-06:00
America/Ciudad_Juarez	UTC-06:00
America/Coral_Harbour	UTC-05:00
America/Cordoba	UTC-03:00
America/Costa_Rica	UTC-06:00
America/Creston	UTC-07:00
America/Cuiaba	UTC-04:00
America/Curacao	UTC-04:00
America/Danmarkshavn	UTC+00:00
America/Dawson	UTC-07:00
America/Dawson_Creek	UTC-07:00
America/Denver	UTC-06:00
America/Detroit	UTC-04:00
America/Dominica	UTC-04:00
America/Edmonton	UTC-06:00
America/Eirunepe	UTC-05:00
America/El_Salvador	UTC-06:00
America/Ensenada	UTC-07:00
America/Fort_Nelson	UTC-07:00
America/Fort_Wayne	UTC-04:00
America/Fortaleza	UTC-03:00
America/Glace_Bay	UTC-03:00
America/Godthab	UTC-01:00
America/Goose_Bay	UTC-03:00
America/Grand_Turk	UTC-04:00
America/Grenada	UTC-04:00
America/Guadeloupe	UTC-04:00
America/Guatemala	UTC-06:00
America/Guayaquil	UTC-05:00
America/Guyana	UTC-04:00
America/Halifax	UTC-03:00
America/Havana	UTC-04:00
America/Hermosillo	UTC-07:00
America/Indiana/Indianapolis	UTC-04:00
America/Indiana/Knox	UTC-05:00
America/Indiana/Marengo	UTC-04:00
America/Indiana/Petersburg	UTC-04:00
America/Indiana/Tell_City	UTC-05:00
America/Indiana/Vevay	UTC-04:00
America/Indiana/Vincennes	UTC-04:00
America/Indiana/Winamac	UTC-04:00
America/Indianapolis	UTC-04:00
America/Inuvik	UTC-06:00
America/Iqaluit	UTC-04:00
America/Jamaica	UTC-05:00
America/Jujuy	UTC-03:00
America/Juneau	UTC-08:00
America/Kentucky/Louisville	UTC-04:00
America/Kentucky/Monticello	UTC-04:00
America/Knox_IN	UTC-05:00
America/Kralendijk	UTC-04:00
America/La_Paz	UTC-04:00
America/Lima	UTC-05:00
America/Los_Angeles	UTC-07:00
America/Louisville	UTC-04:00
America/Lower_Princes	UTC-04:00
America/Maceio	UTC-03:00
America/Managua	UTC-06:00
America/Manaus	UTC-04:00
America/Marigot	UTC-04:00
America/Martinique	UTC-04:00
America/Matamoros	UTC-05:00
America/Mazatlan	UTC-07:00
America/Mendoza	UTC-03:00
America/Menominee	UTC-05:00
America/Merida	UTC-06:00
America/Metlakatla	UTC-08:00
America/Mexico_City	UTC-06:00
America/Miquelon	UTC-02:00
America/Moncton	UTC-03:00
America/Monterrey	UTC-06:00
America/Montevideo	UTC-03:00
America/Montreal	UTC-04:00
America/Montserrat	UTC-04:00
America/Nassau	UTC-04:00
America/New_York	UTC-04:00
America/Nipigon	UTC-04:00
America/Nome	UTC-08:00
America/Noronha	UTC-02:00
America/North_Dakota/Beulah	UTC-05:00
America/North_Dakota/Center	UTC-05:00
America/North_Dakota/New_Salem	UTC-05:00
America/Nuuk	UTC-01:00
America/Ojinaga	UTC-05:00
America/Panama	UTC-05:00
America/Pangnirtung	UTC-04:00
America/Paramaribo	UTC-03:00
America/Phoenix	UTC-07:00
America/Port-au-Prince	UTC-04:00
America/Port_of_Spain	UTC-04:00
America/Porto_Acre	UTC-05:00
America/Porto_Velho	UTC-04:00
America/Puerto_Rico	UTC-04:00
America/Punta_Arenas	UTC-03:00
America/Rainy_River	UTC-05:00
America/Rankin_Inlet	UTC-05:00
America/Recife	UTC-03:00
America/Regina	UTC-06:00
America/Resolute	UTC-05:00
America/Rio_Branco	UTC-05:00
America/Rosario	UTC-03:00
America/Santa_Isabel	UTC-07:00
America/Santarem	UTC-03:00
America/Santiago	UTC-03:00
America/Santo_Domingo	UTC-04:00
America/Sao_Paulo	UTC-03:00
America/Scoresbysund	UTC-01:00
America/Shiprock	UTC-06:00
America/Sitka	UTC-08:00
America/St_Barthelemy	UTC-04:00
America/St_Johns	UTC-02:30
America/St_Kitts	UTC-04:00
America/St_Lucia	UTC-04:00
America/St_Thomas	UTC-04:00
America/St_Vincent	UTC-04:00
America/Swift_Current	UTC-06:00
America/Tegucigalpa	UTC-06:00
America/Thule	UTC-03:00
America/Thunder_Bay	UTC-04:00
America/Tijuana	UTC-07:00
America/Toronto	UTC-04:00
America/Tortola	UTC-04:00
America/Vancouver	UTC-07:00
America/Virgin	UTC-04:00
America/Whitehorse	UTC-07:00
America/Winnipeg	UTC-05:00
America/Yakutat	UTC-08:00
America/Yellowknife	UTC-06:00
Antarctica/Casey	UTC+08:00
Antarctica/Davis	UTC+07:00
Antarctica/DumontDUrville	UTC+10:00
Antarctica/Macquarie	UTC+10:00
Antarctica/Mawson	UTC+05:00
Antarctica/McMurdo	UTC+13:00
Antarctica/Palmer	UTC-03:00
Antarctica/Rothera	UTC-03:00
Antarctica/South_Pole	UTC+13:00
Antarctica/Syowa	UTC+03:00
Antarctica/Troll	UTC+02:00
Antarctica/Vostok	UTC+05:00
Arctic/Longyearbyen	UTC+02:00
Asia/Aden	UTC+03:00
Asia/Almaty	UTC+05:00
Asia/Amman	UTC+03:00
Asia/Anadyr	UTC+12:00
Asia/Aqtau	UTC+05:00
Asia/Aqtobe	UTC+05:00
Asia/Ashgabat	UTC+05:00
Asia/Ashkhabad	UTC+05:00
Asia/Atyrau	UTC+05:00
Asia/Baghdad	UTC+03:00
Asia/Bahrain	UTC+03:00
Asia/Baku	UTC+04:00
Asia/Bangkok	UTC+07:00
Asia/Barnaul	UTC+07:00
Asia/Beirut	UTC+03:00
Asia/Bishkek	UTC+06:00
Asia/Brunei	UTC+08:00
Asia/Calcutta	UTC+05:30
Asia/Chita	UTC+09:00
Asia/Choibalsan	UTC+08:00
Asia/Chongqing	UTC+08:00
Asia/Chungking	UTC+08:00
Asia/Colombo	UTC+05:30
Asia/Dacca	UTC+06:00
Asia/Damascus	UTC+03:00
Asia/Dhaka	UTC+06:00
Asia/Dili	UTC+09:00
Asia/Dubai	UTC+04:00
Asia/Dushanbe	UTC+05:00
Asia/Famagusta	UTC+03:00
Asia/Gaza	UTC+03:00
Asia/Harbin	UTC+08:00
Asia/Hebron	UTC+03:00
Asia/Ho_Chi_Minh	UTC+07:00
Asia/Hong_Kong	UTC+08:00
Asia/Hovd	UTC+07:00
Asia/Irkutsk	UTC+08:00
Asia/Istanbul	UTC+03:00
Asia/Jakarta	UTC+07:00
Asia/Jayapura	UTC+09:00
Asia/Jerusalem	UTC+03:00
Asia/Kabul	UTC+04:30
Asia/Kamchatka	UTC+12:00
Asia/Karachi	UTC+05:00
Asia/Kashgar	UTC+06:00
Asia/Kathmandu	UTC+05:45
Asia/Katmandu	UTC+05:45
Asia/Khandyga	UTC+09:00
Asia/Kolkata	UTC+05:30
Asia/Krasnoyarsk	UTC+07:00
Asia/Kuala_Lumpur	UTC+08:00
Asia/Kuching	UTC+08:00
Asia/Kuwait	UTC+03:00
Asia/Macao	UTC+08:00
Asia/Macau	UTC+08:00
Asia/Magadan	UTC+11:00
Asia/Makassar	UTC+08:00
Asia/Manila	UTC+08:00
Asia/Muscat	UTC+04:00
Asia/Nicosia	UTC+03:00
Asia/Novokuznetsk	UTC+07:00
Asia/Novosibirsk	UTC+07:00
Asia/Omsk	UTC+06:00
Asia/Oral	UTC+05:00
Asia/Phnom_Penh	UTC+07:00
Asia/Pontianak	UTC+07:00
Asia/Pyongyang	UTC+09:00
Asia/Qatar	UTC+03:00
Asia/Qostanay	UTC+05:00
Asia/Qyzylorda	UTC+05:00
Asia/Rangoon	UTC+06:30
Asia/Riyadh	UTC+03:00
Asia/Saigon	UTC+07:00
Asia/Sakhalin	UTC+11:00
Asia/Samarkand	UTC+05:00
Asia/Seoul	UTC+09:00
Asia/Shanghai	UTC+08:00
Asia/Singapore	UTC+08:00
Asia/Srednekolymsk	UTC+11:00
Asia/Taipei	UTC+08:00
Asia/Tashkent	UTC+05:00
Asia/Tbilisi	UTC+04:00
Asia/Tehran	UTC+03:30
Asia/Tel_Aviv	UTC+03:00
Asia/Thimbu	UTC+06:00
Asia/Thimphu	UTC+06:00
Asia/Tokyo	UTC+09:00
Asia/Tomsk	UTC+07:00
Asia/Ujung_Pandang	UTC+08:00
Asia/Ulaanbaatar	UTC+08:00
Asia/Ulan_Bator	UTC+08:00
Asia/Urumqi	UTC+06:00
Asia/Ust-Nera	UTC+10:00
Asia/Vientiane	UTC+07:00
Asia/Vladivostok	UTC+10:00
Asia/Yakutsk	UTC+09:00
Asia/Yangon	UTC+06:30
Asia/Yekaterinburg	UTC+05:00
Asia/Yerevan	UTC+04:00
Atlantic/Azores	UTC+00:00
Atlantic/Bermuda	UTC-03:00
Atlantic/Canary	UTC+01:00
Atlantic/Cape_Verde	UTC-01:00
Atlantic/Faeroe	UTC+01:00
Atlantic/Faroe	UTC+01:00
Atlantic/Jan_Mayen	UTC+02:00
Atlantic/Madeira	UTC+01:00
Atlantic/Reykjavik	UTC+00:00
Atlantic/South_Georgia	UTC-02:00
Atlantic/St_Helena	UTC+00:00
Atlantic/Stanley	UTC-03:00
Australia/ACT	UTC+10:00
Australia/Adelaide	UTC+09:30
Australia/Brisbane	UTC+10:00
Australia/Broken_Hill	UTC+09:30
Australia/Canberra	UTC+10:00
Australia/Currie	UTC+10:00
Australia/Darwin	UTC+09:30
Australia/Eucla	UTC+08:45
Australia/Hobart	UTC+10:00
Australia/LHI	UTC+10:30
Australia/Lindeman	UTC+10:00
Australia/Lord_Howe	UTC+10:30
Australia/Melbourne	UTC+10:00
Australia/NSW	UTC+10:00
Australia/North	UTC+09:30
Australia/Perth	UTC+08:00
Australia/Queensland	UTC+10:00
Australia/South	UTC+09:30
Australia/Sydney	UTC+10:00
Australia/Tasmania	UTC+10:00
Australia/Victoria	UTC+10:00
Australia/West	UTC+08:00
Australia/Yancowinna	UTC+09:30
Brazil/Acre	UTC-05:00
Brazil/DeNoronha	UTC-02:00
Brazil/East	UTC-03:00
Brazil/West	UTC-04:00
CET	UTC+02:00
CST6CDT	UTC-05:00
Canada/Atlantic	UTC-03:00
Canada/Central	UTC-05:00
Canada/Eastern	UTC-04:00
Canada/Mountain	UTC-06:00
Canada/Newfoundland	UTC-02:30
Canada/Pacific	UTC-07:00
Canada/Saskatchewan	UTC-06:00
Canada/Yukon	UTC-07:00
Chile/Continental	UTC-03:00
Chile/EasterIsland	UTC-05:00
Cuba	UTC-04:00
EET	UTC+03:00
EST	UTC-05:00
EST5EDT	UTC-04:00
Egypt	UTC+03:00
Eire	UTC+01:00
Etc/GMT	UTC+00:00
Etc/GMT+0	UTC+00:00
Etc/GMT+1	UTC-01:00
Etc/GMT+10	UTC-10:00
Etc/GMT+11	UTC-11:00
Etc/GMT+12	UTC-12:00
Etc/GMT+2	UTC-02:00
Etc/GMT+3	UTC-03:00
Etc/GMT+4	UTC-04:00
Etc/GMT+5	UTC-05:00
Etc/GMT+6	UTC-06:00
Etc/GMT+7	UTC-07:00
Etc/GMT+8	UTC-08:00
Etc/GMT+9	UTC-09:00
Etc/GMT-0	UTC+00:00
Etc/GMT-1	UTC+01:00
Etc/GMT-10	UTC+10:00
Etc/GMT-11	UTC+11:00
Etc/GMT-12	UTC+12:00
Etc/GMT-13	UTC+13:00
Etc/GMT-14	UTC+14:00
Etc/GMT-2	UTC+02:00
Etc/GMT-3	UTC+03:00
Etc/GMT-4	UTC+04:00
Etc/GMT-5	UTC+05:00
Etc/GMT-6	UTC+06:00
Etc/GMT-7	UTC+07:00
Etc/GMT-8	UTC+08:00
Etc/GMT-9	UTC+09:00
Etc/GMT0	UTC+00:00
Etc/Greenwich	UTC+00:00
Etc/UCT	UTC+00:00
Etc/UTC	UTC+00:00
Etc/Universal	UTC+00:00
Etc/Zulu	UTC+00:00
Europe/Amsterdam	UTC+02:00
Europe/Andorra	UTC+02:00
Europe/Astrakhan	UTC+04:00
Europe/Athens	UTC+03:00
Europe/Belfast	UTC+01:00
Europe/Belgrade	UTC+02:00
Europe/Berlin	UTC+02:00
Europe/Bratislava	UTC+02:00
Europe/Brussels	UTC+02:00
Europe/Bucharest	UTC+03:00
Europe/Budapest	UTC+02:00
Europe/Busingen	UTC+02:00
Europe/Chisinau	UTC+03:00
Europe/Copenhagen	UTC+02:00
Europe/Dublin	UTC+01:00
Europe/Gibraltar	UTC+02:00
Europe/Guernsey	UTC+01:00
Europe/Helsinki	UTC+03:00
Europe/Isle_of_Man	UTC+01:00
Europe/Istanbul	UTC+03:00
Europe/Jersey	UTC+01:00
Europe/Kaliningrad	UTC+02:00
Europe/Kiev	UTC+03:00
Europe/Kirov	UTC+03:00
Europe/Kyiv	UTC+03:00
Europe/Lisbon	UTC+01:00
Europe/Ljubljana	UTC+02:00
Europe/London	UTC+01:00
Europe/Luxembourg	UTC+02:00
Europe/Madrid	UTC+02:00
Europe/Malta	UTC+02:00
Europe/Mariehamn	UTC+03:00
Europe/Minsk	UTC+03:00
Europe/Monaco	UTC+02:00
Europe/Moscow	UTC+03:00
Europe/Nicosia	UTC+03:00
Europe/Oslo	UTC+02:00
Europe/Paris	UTC+02:00
Europe/Podgorica	UTC+02:00
Europe/Prague	UTC+02:00
Europe/Riga	UTC+03:00
Europe/Rome	UTC+02:00
Europe/Samara	UTC+04:00
Europe/San_Marino	UTC+02:00
Europe/Sarajevo	UTC+02:00
Europe/Saratov	UTC+04:00
Europe/Simferopol	UTC+03:00
Europe/Skopje	UTC+02:00
Europe/Sofia	UTC+03:00
Europe/Stockholm	UTC+02:00
Europe/Tallinn	UTC+03:00
Europe/Tirane	UTC+02:00
Europe/Tiraspol	UTC+03:00
Europe/Ulyanovsk	UTC+04:00
Europe/Uzhgorod	UTC+03:00
Europe/Vaduz	UTC+02:00
Europe/Vatican	UTC+02:00
Europe/Vienna	UTC+02:00
Europe/Vilnius	UTC+03:00
Europe/Volgograd	UTC+03:00
Europe/Warsaw	UTC+02:00
Europe/Zagreb	UTC+02:00
Europe/Zaporozhye	UTC+03:00
Europe/Zurich	UTC+02:00
Factory	UTC+00:00
GB	UTC+01:00
GB-Eire	UTC+01:00
GMT	UTC+00:00
GMT+0	UTC+00:00
GMT-0	UTC+00:00
GMT0	UTC+00:00
Greenwich	UTC+00:00
HST	UTC-10:00
Hongkong	UTC+08:00
Iceland	UTC+00:00
Indian/Antananarivo	UTC+03:00
Indian/Chagos	UTC+06:00
Indian/Christmas	UTC+07:00
Indian/Cocos	UTC+06:30
Indian/Comoro	UTC+03:00
Indian/Kerguelen	UTC+05:00
Indian/Mahe	UTC+04:00
Indian/Maldives	UTC+05:00
Indian/Mauritius	UTC+04:00
Indian/Mayotte	UTC+03:00
Indian/Reunion	UTC+04:00
Iran	UTC+03:30
Israel	UTC+03:00
Jamaica	UTC-05:00
Japan	UTC+09:00
Kwajalein	UTC+12:00
Libya	UTC+02:00
MET	UTC+02:00
MST	UTC-07:00
MST7MDT	UTC-06:00
Mexico/BajaNorte	UTC-07:00
Mexico/BajaSur	UTC-07:00
Mexico/General	UTC-06:00
NZ	UTC+13:00
NZ-CHAT	UTC+13:45
Navajo	UTC-06:00
PRC	UTC+08:00
PST8PDT	UTC-07:00
Pacific/Apia	UTC+13:00
Pacific/Auckland	UTC+13:00
Pacific/Bougainville	UTC+11:00
Pacific/Chatham	UTC+13:45
Pacific/Chuuk	UTC+10:00
Pacific/Easter	UTC-05:00
Pacific/Efate	UTC+11:00
Pacific/Enderbury	UTC+13:00
Pacific/Fakaofo	UTC+13:00
Pacific/Fiji	UTC+12:00
Pacific/Funafuti	UTC+12:00
Pacific/Galapagos	UTC-06:00
Pacific/Gambier	UTC-09:00
Pacific/Guadalcanal	UTC+11:00
Pacific/Guam	UTC+10:00
Pacific/Honolulu	UTC-10:00
Pacific/Johnston	UTC-10:00
Pacific/Kanton	UTC+13:00
Pacific/Kiritimati	UTC+14:00
Pacific/Kosrae	UTC+11:00
Pacific/Kwajalein	UTC+12:00
Pacific/Majuro	UTC+12:00
Pacific/Marquesas	UTC-09:30
Pacific/Midway	UTC-11:00
Pacific/Nauru	UTC+12:00
Pacific/Niue	UTC-11:00
Pacific/Norfolk	UTC+11:00
Pacific/Noumea	UTC+11:00
Pacific/Pago_Pago	UTC-11:00
Pacific/Palau	UTC+09:00
Pacific/Pitcairn	UTC-08:00
Pacific/Pohnpei	UTC+11:00
Pacific/Ponape	UTC+11:00
Pacific/Port_Moresby	UTC+10:00
Pacific/Rarotonga	UTC-10:00
Pacific/Saipan	UTC+10:00
Pacific/Samoa	UTC-11:00
Pacific/Tahiti	UTC-10:00
Pacific/Tarawa	UTC+12:00
Pacific/Tongatapu	UTC+13:00
Pacific/Truk	UTC+10:00
Pacific/Wake	UTC+12:00
Pacific/Wallis	UTC+12:00
Pacific/Yap	UTC+10:00
Poland	UTC+02:00
Portugal	UTC+01:00
ROC	UTC+08:00
ROK	UTC+09:00
Singapore	UTC+08:00
Turkey	UTC+03:00
UCT	UTC+00:00
US/Alaska	UTC-08:00
US/Aleutian	UTC-09:00
US/Arizona	UTC-07:00
US/Central	UTC-05:00
US/East-Indiana	UTC-04:00
US/Eastern	UTC-04:00
US/Hawaii	UTC-10:00
US/Indiana-Starke	UTC-05:00
US/Michigan	UTC-04:00
US/Mountain	UTC-06:00
US/Pacific	UTC-07:00
US/Samoa	UTC-11:00
UTC	UTC+00:00
Universal	UTC+00:00
W-SU	UTC+03:00
WET	UTC+01:00
Zulu	UTC+00:00
localtime	UTC+00:00

Code Used for Generating the Table¶

Run this code in a Python environment to generate the table above.

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo, available_timezones

# Prepare a list to store time zone information
timezones = []

for tz_name in sorted(available_timezones()):
    tz = ZoneInfo(tz_name)
    now = datetime.now(tz)
    offset = tz.utcoffset(now)

    if offset is None:
        offset_str = 'Unknown'
    else:
        total_seconds = offset.total_seconds()
        sign = '+' if total_seconds >= 0 else '-'
        total_seconds = abs(total_seconds)
        hours, remainder = divmod(total_seconds, 3600)
        minutes, _ = divmod(remainder, 60)
        offset_str = f"UTC{sign}{int(hours):02d}:{int(minutes):02d}"

    timezones.append((tz_name, offset_str))

# Generate Markdown table
print("| Timezone | UTC Offset |")
print("| --- | --- |")
for tz_name, offset_str in timezones:
    print(f"| {tz_name} | {offset_str} |")

Examples

Library Configuration Examples¶

Pyproject.toml is the preferred method, but there is an example for the bumpcalver.toml configuration included also.

PyProject.TOML¶

Add to your pyproject.toml

[project]
name = "example PyProject.toml"
version = "2025.2.2"
requires-python = ">=3.10"
description = "A powerful CLI tool for effortless calendar-based version management"
keywords = [ "cli", "tool", "calendar", "version", "management", "configuration", "example",]
readme = "README.md"

[project.license]
file = "LICENSE"

[tool.bumpcalver]
version_format = "{current_date}-{build_count:03}"
date_format = "%y.%m.%d"
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"

[[tool.bumpcalver.file]]
path = "sonar-project.properties"
file_type = "properties"
variable = "sonar.projectVersion"
version_standard = "default"

[[tool.bumpcalver.file]]
path = ".env"
file_type = "env"
variable = "VERSION"
version_standard = "default"

[[tool.bumpcalver.file]]
path = "setup.cfg"
file_type = "setup.cfg"
variable = "metadata.version"
version_standard = "python"

BumpCalver.TOML Configuration¶

File needs to be in the root and named bumpcalver.toml

version_format = "{current_date}-{build_count:03}"
date_format = "%y.%m.%d"
timezone = "America/New_York"
git_tag = true
auto_commit = true

[[file]]
path = "pyproject.toml"
file_type = "toml"
variable = "project.version"
version_standard = "python"

[[file]]
path = "examples/makefile"
file_type = "makefile"
variable = "APP_VERSION"
version_standard = "default"

[[file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "arg.VERSION"
version_standard = "default"

[[file]]
path = "examples/dockerfile"
file_type = "dockerfile"
variable = "env.APP_VERSION"
version_standard = "default"

[[file]]
path = "examples/p.py"
file_type = "python"
variable = "__version__"
version_standard = "python"

[[file]]
path = "sonar-project.properties"
file_type = "properties"
variable = "sonar.projectVersion"
version_standard = "default"

[[file]]
path = ".env"
file_type = "env"
variable = "VERSION"
version_standard = "default"

[[file]]
path = "setup.cfg"
file_type = "setup.cfg"
variable = "metadata.version"
version_standard = "python"

Example file layouts¶

Below are examples of various file types and how they could be setup using BumpCalver. As the intent of the library is to allow flexible use across different languages and use cases.

MakeFile¶

# Variables
REPONAME = bumpcalver
APP_VERSION = 2025.02.02
PYTHON = python3
PIP = $(PYTHON) -m pip
PYTEST = $(PYTHON) -m pytest

EXAMPLE_PATH = examples
SERVICE_PATH = src
TESTS_PATH = tests
SQLITE_PATH = _sqlite_db
LOG_PATH = log

PORT = 5000
WORKER = 8
LOG_LEVEL = debug

REQUIREMENTS_PATH = requirements.txt
# DEV_REQUIREMENTS_PATH = requirements/dev.txt

.PHONY: autoflake black cleanup create-docs flake8 help install isort run-example run-example-dev speedtest test

autoflake: ## Remove unused imports and unused variables from Python code
    autoflake --in-place --remove-all-unused-imports  --ignore-init-module-imports --remove-unused-variables -r $(SERVICE_PATH)
    autoflake --in-place --remove-all-unused-imports  --ignore-init-module-imports --remove-unused-variables -r $(TESTS_PATH)
    autoflake --in-place --remove-all-unused-imports  --ignore-init-module-imports --remove-unused-variables -r $(EXAMPLE_PATH)

YAML¶

application:
  description: This is an example application configuration file.
  name: ExampleApp
configuration:
  version: 2025.02.02
database:
  host: localhost
  password: password
  port: 5432
  username: user
features:
  feature_a: true
  feature_b: false
  feature_c: true

XML¶

<configuration>
    <version>2025.02.02</version>
    <application>
        <name>ExampleApp</name>
        <description>This is an example application configuration file.</description>
    </application>
    <database>
        <host>localhost</host>
        <port>5432</port>
        <username>user</username>
        <password>password</password>
    </database>
    <features>
        <feature_a>true</feature_a>
        <feature_b>false</feature_b>
        <feature_c>true</feature_c>
    </features>
</configuration>

TOML¶

[configuration]
version = "2025.02.02"

[configuration.application]
name = "ExampleApp"
description = "This is an example application configuration file."

[configuration.database]
host = "localhost"
port = 5432
username = "user"
password = "password"

[configuration.features]
feature_a = true
feature_b = false
feature_c = true

JSON¶

{
  "version": "2025.02.02",
  "application": {
    "name": "ExampleApp",
    "description": "This is an example application configuration file."
  },
  "database": {
    "host": "localhost",
    "port": 5432,
    "username": "user",
    "password": "password"
  },
  "features": {
    "feature_a": true,
    "feature_b": false,
    "feature_c": true
  }
}

Dockerfile¶

# Use an official Python runtime as a parent image
FROM python:3.14-slim

# Set the working directory in the container
WORKDIR /app

# Copy the current directory contents into the container at /app
COPY . /app

# Install any needed packages specified in requirements.txt
RUN pip install --no-cache-dir -r requirements.txt

# Make port 80 available to the world outside this container
EXPOSE 80

# Define environment variable
ENV APP_VERSION=2025.02.02
ARG VERSION=2025.02.02
# Run app.py when the container launches
CMD ["python", "app.py"]

Properties File (sonar-project.properties)¶

sonar.projectKey=devsetgo_bumpcalver
sonar.organization=devsetgo
sonar.projectName=bumpcalver
sonar.projectVersion=2025.02.02
sonar.language=python
sonar.sources=src
sonar.tests=tests
sonar.python.coverage.reportPaths=coverage.xml
sonar.python.xunit.reportPath=report.xml

Environment File (.env)¶

# Application Configuration
DEBUG=true
VERSION=2025.02.02
DATABASE_URL=postgresql://localhost/mydb
API_KEY=your-secret-api-key
LOG_LEVEL=info
PORT=5000

Setup Configuration (setup.cfg)¶

[metadata]
name = example-package
version = 2025.02.02
author = Your Name
author_email = your.email@example.com
description = A short description of the package
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/yourusername/example-package
classifiers =
    Development Status :: 4 - Beta
    Intended Audience :: Developers
    License :: OSI Approved :: MIT License
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3.9
    Programming Language :: Python :: 3.10
    Programming Language :: Python :: 3.11

[options]
packages = find:
python_requires = >=3.9
install_requires =
    click>=8.0.0
    toml>=0.10.0

[options.entry_points]
console_scripts =
    example-cli = example_package.cli:main

````

```

Documentation

Documentation Versioning with Mike¶

This project uses mike to manage multiple versions of the documentation. Mike integrates with MkDocs to provide a smooth versioning experience.

Overview¶

The documentation versioning system allows you to: - Deploy multiple versions of documentation simultaneously - Automatically manage version aliases (latest, stable, dev) - Provide a version selector in the documentation - Maintain clean URLs for different versions

Version Strategy¶

Version Formats¶

Release versions: Use calendar versioning format (e.g., 2025.08.01)
Development version: dev
Aliases: latest, stable

Version Hierarchy¶

latest - Always points to the most recent release
stable - Points to the current stable release
dev - Development/bleeding-edge documentation
Specific versions (e.g., 2025.08.01, 2025.07.15)

Commands¶

Deployment Commands¶

# Deploy current version (auto-detected from project files)
make create-docs

# Deploy locally without pushing to remote
make create-docs-local

# Deploy development version
make create-docs-dev

# Deploy specific version with custom aliases
python3 scripts/deploy_docs.py deploy --version 2025.08.01 --aliases latest stable --push

# Deploy development version
python3 scripts/deploy_docs.py deploy --dev --version dev --push

Management Commands¶

# List all deployed versions
make list-docs
# or
python3 scripts/deploy_docs.py list

# Serve all versions locally for testing
make serve-docs
# or
python3 scripts/deploy_docs.py serve

# Delete a specific version
make delete-version VERSION=2025.07.01
# or
python3 scripts/deploy_docs.py delete --version 2025.07.01 --push

# Set default version (what users see at the root URL)
make set-default-version VERSION=latest

Workflow Integration¶

Automated Deployment¶

The project includes GitHub Actions workflows that automatically deploy documentation:

Push to dev branch: Deploys to dev version
Push to main/master branch: Deploys as new release with latest alias
Tagged releases: Deploys with both latest and stable aliases

Manual Deployment¶

For manual deployment, follow these steps:

Update version: Use bumpcalver to update project version
```
bumpcalver --build
```
Deploy documentation:
```
make create-docs
```

Configuration¶

MkDocs Configuration¶

The mkdocs.yml file includes the mike plugin configuration:

plugins:
  - mike:
      alias_type: symlink
      version_selector: true
      css_dir: css
      javascript_dir: js

Mike Configuration¶

Project-specific mike settings are stored in .mike.yml:

remote_branch: gh-pages
remote_name: origin
version_selector: true
default_alias_type: symlink

Version Selector¶

The documentation includes an automatic version selector that: - Appears in the navigation bar - Shows all available versions - Allows users to switch between versions - Highlights the current version

Best Practices¶

Version Management¶

Always use aliases: Use latest and stable aliases for user-friendly URLs
Regular cleanup: Remove old versions that are no longer supported
Consistent naming: Follow the established version naming convention
Test locally: Use make serve-docs to test before deploying

Release Process¶

Development: Work on dev branch, deploy to dev version
Review: Test documentation thoroughly using local serving
Release: Merge to main, automatic deployment creates new versioned docs
Tag: Create Git tags for major releases to create permanent documentation snapshots

URL Structure¶

The documentation will be available at: - https://yoursite.com/ - Default version (usually latest) - https://yoursite.com/latest/ - Latest release - https://yoursite.com/stable/ - Stable release - https://yoursite.com/dev/ - Development version - https://yoursite.com/2025.08.01/ - Specific version

Troubleshooting¶

Common Issues¶

Version not found: Ensure the version exists with make list-docs
Git permissions: Configure Git user for automated deployments
Branch conflicts: Fetch latest changes before deploying

Recovery¶

If something goes wrong:

# List all versions to see current state
make list-docs

# Delete problematic version
make delete-version VERSION=problematic-version

# Redeploy from scratch
make create-docs-local

Integration with BumpCalver¶

The versioning system integrates seamlessly with BumpCalver:

Version detection: Automatically reads version from project files
Consistent versioning: Uses the same version format across project and docs
Automated workflow: Version bumps trigger documentation updates

This ensures that documentation versions always match the project versions.

Mike Documentation Versioning - Quick Reference¶

Quick Commands¶

Deploy Documentation¶

# Deploy current version (auto-detected)
make create-docs                 # Push to remote
make create-docs-local          # Local only

# Deploy development version
make create-docs-dev            # Push dev version

# Deploy specific version
python3 scripts/deploy_docs.py deploy --version 2025.08.01 --aliases latest stable --push

Manage Versions¶

# List all versions
make list-docs

# Serve locally (all versions)
make serve-docs

# Delete version
make delete-version VERSION=2025.07.01

# Set default version
make set-default-version VERSION=latest

Advanced Usage¶

# Deploy with custom title
python3 scripts/deploy_docs.py deploy --version 2025.08.01 --title "August 2025 Release" --push

# Deploy dev version with custom name
python3 scripts/deploy_docs.py deploy --dev --version staging --push

# Deploy without aliases
python3 scripts/deploy_docs.py deploy --version 2025.08.01 --push

Version Strategy¶

Version Type	Format	Example	When to Use
Release	YYYY.MM.DD	2025.08.01	Tagged releases
Development	dev	dev	Active development
Staging	staging	staging	Pre-release testing
Aliases	latest/stable	latest	User-friendly URLs

URL Structure¶

URL	Points To	Description
`/`	Default version	Usually `latest`
`/latest/`	Latest release	Most recent version
`/stable/`	Stable release	Production-ready
`/dev/`	Development	Bleeding edge
`/2025.08.01/`	Specific version	Permanent link

Integration Points¶

With BumpCalver¶

Auto-detects version from makefile, pyproject.toml, __init__.py
Consistent versioning across project and docs
Automated workflow on version bumps

With GitHub Actions¶

dev branch → dev documentation
main branch → latest documentation
Git tags → versioned + stable documentation

With MkDocs Material Theme¶

Automatic version selector in navigation
Responsive design across versions
Search within specific versions

About

About¶

BumpCalver Library is a library to help manage "calendar version" (CalVer) strings. You can update the version string in TOML, YAML, XML, JSON, Makefile, Dockerfile, and Python files. It follows PEP440 for Python packages, but is not intended to only be for Python pacakges. It supports git tags like beta, release, release-candidate, and custom tags of your own choosing. It has support for Timezones and build counts. It is a simple library that can be used in any project that needs to manage versioning.

The library is written in Python and is available on PyPi. It is open source and available on GitHub. Feel free to use it in your projects and contribute to the library.

About Me¶

I am a software engineering manager with an eclectic background in various industries (finance, manufacturing, and metrology). I am passionate about software development and love to learn new things.

Contributing¶

Please feel to contribute to this project. Adding common functions is the intent and if you have one to add or improve an existing it is greatly appreciated.

Ways to Contribute!¶

Add or improve a function
Add or improve documentation
Add or improve Tests
Report or fix a bug

Changelog¶

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog

Latest Changes¶

Fix of release (v2025.8.2.3)¶

What's Changed¶

Verion bump to 2025.8.2.3 (#66) @devsetgo
Test Cleanup (#65) @devsetgo
Fix of Publishing CICD (#64) @devsetgo

Published Date: 2025 August 02, 20:00

New File Handlers .ENV, setup.cfg, & sonar-project. Properties (v2025.8.2.1)¶

What's Changed¶

CICD fix and new Handlers (#63) @devsetgo
pip(deps): bump tox from 4.27.0 to 4.28.4 (#59) @dependabot[bot]
pip(deps): bump mkdocstrings[python,shell] from 0.29.1 to 0.30.0 (#60) @dependabot[bot]
pip(deps): bump mkdocs-material from 9.6.15 to 9.6.16 (#61) @dependabot[bot]
pip(deps): bump ruff from 0.12.2 to 0.12.7 (#62) @dependabot[bot]
update of requirements (#58) @devsetgo
pip(deps): bump ruff from 0.11.11 to 0.11.12 (#52) @dependabot[bot]
Updating Requirements (#51) @devsetgo

Published Date: 2025 August 02, 19:14

Improved documentation and update of dependencies (v2025.4.12.1)¶

What's Changed¶

Improving Documentation (#47) @devsetgo
pip(deps): bump pytest from 8.3.4 to 8.3.5 (#42) @dependabot[bot]
pip(deps): bump mkdocs-print-site-plugin from 2.6.0 to 2.7.2 (#44) @dependabot[bot]
pip(deps): bump pylint from 3.3.4 to 3.3.6 (#43) @dependabot[bot]
pip(deps): bump mkdocs-material from 9.6.6 to 9.6.11 (#45) @dependabot[bot]
pip(deps): bump genbadge[all] from 1.1.1 to 1.1.2 (#46) @dependabot[bot]
pip(deps): bump mkdocstrings[python,shell] from 0.27.0 to 0.28.2 (#37) @dependabot[bot]
pip(deps): bump twine from 6.0.1 to 6.1.0 (#38) @dependabot[bot]
pip(deps): bump pylint from 3.3.3 to 3.3.4 (#39) @dependabot[bot]
pip(deps): bump mkdocs-material from 9.5.49 to 9.6.6 (#40) @dependabot[bot]
pip(deps): bump ruff from 0.9.4 to 0.9.9 (#41) @dependabot[bot]
run of tests (#36) @devsetgo
pip(deps): bump black from 24.10.0 to 25.1.0 (#31) @dependabot[bot]
pip(deps): bump ruff from 0.8.4 to 0.9.4 (#32) @dependabot[bot]
pip(deps): bump tox from 4.23.2 to 4.24.1 (#33) @dependabot[bot]
pip(deps): bump pre-commit from 4.0.1 to 4.1.0 (#34) @dependabot[bot]
pip(deps): bump autopep8 from 2.3.1 to 2.3.2 (#35) @dependabot[bot]
pip(deps): bump ruff from 0.8.2 to 0.8.4 (#26) @dependabot[bot]
pip(deps): bump hatchling from 1.26.3 to 1.27.0 (#27) @dependabot[bot]
pip(deps): bump mkdocs-material from 9.5.47 to 9.5.49 (#28) @dependabot[bot]
pip(deps): bump pylint from 3.3.2 to 3.3.3 (#29) @dependabot[bot]
pip(deps): bump click from 8.1.7 to 8.1.8 (#30) @dependabot[bot]

Published Date: 2025 April 12, 16:34

Fix of Python Version (2024.12.14.1)¶

What's Changed¶

bump version (#25) @devsetgo
working on trusted publishing (#24) @devsetgo
Bump of Version 24.12.06-001 (#23) @devsetgo
Enhancing Date Formatting Capability (#22) @devsetgo
Adding BumpCalver.toml option (#16) @devsetgo
pip(deps): bump ruff from 0.7.1 to 0.7.2 (#15) @dependabot
pip(deps): bump mkdocs-material from 9.5.40 to 9.5.43 (#11) @dependabot
pip(deps): bump ruff from 0.6.9 to 0.7.1 (#12) @dependabot
pip(deps): bump tox from 4.21.2 to 4.23.2 (#13) @dependabot
pip(deps): bump pytest-cov from 5.0.0 to 6.0.0 (#14) @dependabot

Published Date: 2024 December 14, 20:10

Enhancing Date Formatting Capabilities (24.12.06-001-x)¶

What's Changed¶

working on trusted publishing (#24) @devsetgo

Published Date: 2024 December 14, 20:03

Enhancing Date Formatting Capabilites (24.12.06-001)¶

What's Changed¶

Changing version to xx.xx.xx-build.
Bump of Version 24.12.06-001 (#23) @devsetgo
Enhancing Date Formatting Capability (#22) @devsetgo

Published Date: 2024 December 06, 23:11

BumpCalver.toml Option (2024-11-08)¶

What's Changed¶

Adding BumpCalver.toml option (#16) @devsetgo
pip(deps): bump ruff from 0.7.1 to 0.7.2 (#15) @dependabot
pip(deps): bump mkdocs-material from 9.5.40 to 9.5.43 (#11) @dependabot
pip(deps): bump ruff from 0.6.9 to 0.7.1 (#12) @dependabot
pip(deps): bump tox from 4.21.2 to 4.23.2 (#13) @dependabot
pip(deps): bump pytest-cov from 5.0.0 to 6.0.0 (#14) @dependabot

Published Date: 2024 November 08, 21:41

Fix of OS classifiers (2024.10.20.4)¶

What's Changed¶

Fixing Classifier Gaps (#10) @devsetgo

Published Date: 2024 October 20, 16:14

Fix of classifiers (2024.10.20.3)¶

What's Changed¶

Updating classifiers (#9) @devsetgo

Published Date: 2024 October 20, 16:00

Adding Python 3.9 Support (2024.10.20)¶

What's Changed¶

Fix to support Python 3.9 and higher (#8) @devsetgo
Release Ready (#7) @devsetgo

Published Date: 2024 October 20, 15:35

Initial Release (2024.10.18)¶

What's Changed¶

Initial Work by @devsetgo in https://github.com/devsetgo/bumpcalver/pull/1
Pre-Release Work by @devsetgo in https://github.com/devsetgo/bumpcalver/pull/4

Full Changelog: https://github.com/devsetgo/bumpcalver/commits/2024.10.18

Published Date: 2024 October 18, 18:42

BumpCalver Library

BumpCalver CLI Documentation¶

Note¶

Overview¶

Table of Contents¶

Installation¶

Getting Started¶

Configuration¶

Configuration Options¶

Example Configuration¶

Date Format Examples¶

Supported File Types¶

Core File Types¶

Infrastructure Files¶

Configuration Files¶

Command-Line Usage¶

Options¶

Examples¶

Basic Version Bump¶

Beta Versioning¶

Specifying Timezone¶

Creating a Git Tag with Auto-Commit¶

Error Handling¶

Support¶

Quick Start¶

Install¶

Usage¶

Initialize Configuration¶

Basic Version Bump¶

Beta Versioning¶

Specify Timezone¶

Create a Git Tag with Auto-Commit¶

Additional Options¶

Create Custom Date Formats¶

See Documentation¶

Example version.py File¶

Integrate with Your Project¶

Summary¶

Timezones¶

Code Used for Generating the Table¶

Examples

Library Configuration Examples¶

PyProject.TOML¶

BumpCalver.TOML Configuration¶

Example file layouts¶

MakeFile¶

YAML¶

XML¶

TOML¶

JSON¶

Dockerfile¶

Properties File (sonar-project.properties)¶

Environment File (.env)¶

Setup Configuration (setup.cfg)¶

Documentation

Documentation Versioning with Mike¶

Overview¶

Version Strategy¶

Version Formats¶

Version Hierarchy¶

Commands¶

Deployment Commands¶

Management Commands¶

Workflow Integration¶

Automated Deployment¶

Manual Deployment¶

Configuration¶

MkDocs Configuration¶

Mike Configuration¶

Version Selector¶

Best Practices¶

Version Management¶

Release Process¶

URL Structure¶

Troubleshooting¶

Common Issues¶

Recovery¶

Integration with BumpCalver¶

Mike Documentation Versioning - Quick Reference¶

Quick Commands¶

Example `version.py` File¶