# Poetry Versions Plugin
License
## Overview
The Poetry Versions Plugin is a powerful extension for the Poetry dependency manager, designed to automate version
management and record Git information for Python projects.
This plugin simplifies the process of bumping version numbers
and integrates seamlessly with Git to ensure that all changes are tracked effectively.
## Features
- **Automated Version Management**: Easily bump major, minor, or patch versions using the `poetry version` command.
- **Git Integration**: Automatically records Git branch, commit, and status information within your project.
- **Customizable Workflow**: Configure commit message formats, allow/disallow dirty repository states, and specify which
files to update.
- **Release Process Automation**: Provides a script to handle releases using git flow, ensuring a streamlined and
consistent release process.
## Installation
To install the Poetry Versions Plugin, add it to your Poetry project:
```bash
poetry add poetry-versions-plugin
```
Poetry will automatically recognize the plugin without needing additional configuration in your `pyproject.toml`.
## Configuration
Configure the plugin in your `pyproject.toml` file under the `[tool.versions.settings]` section:
```toml
[tool.versions.settings]
allow_dirty = false
commit = true
commit_on = ["major", "minor", "patch"]
commit_message = "Bump version: {current_version} → {new_version}"
filename = [
"poetry_versions_plugin/versions.py",
]
```
### Main Configuration Options
allow_dirty: (default: false) If set to true, allows the version bumping even if the working directory has uncommitted
changes.
commit: (default: true) Automatically commit changes to the local git repository after a version bump.
commit_on: Specifies which version types (major, minor, patch) trigger an automatic commit.
commit_message: Format of the commit message for version bumps.
filename: List of additional files to update with the new version information.
## Usage
### Bumping Versions
To bump the version of your project, use the `poetry version` command with the desired version type:
```bash
poetry version [major|minor|patch]
```
This command updates the version in your `pyproject.toml`, updates additional specified files, and commits changes if
configured.
### Release Process
The `scripts.release:main` script automates the release process using git flow.
To execute a release:
```bash
poetry run release [major|minor|patch]
```
This script performs the following steps:
1. Checks if you're on the `develop` branch.
2. Verifies there are no uncommitted changes.
3. Bumps the version number.
4. Starts and finishes a git flow release.
5. Publishes the package.
#### Customizing the Release Process with a Makefile
You can also customize the release process using a Makefile. Here is an example:
```makefile
bump = patch
next-version = $(shell poetry version $(bump) -s --dry-run)
release:
@echo "Creating a new release..."
git flow release start $(next-version)
poetry version $(bump)
git flow release finish -m "publish"
git push --all
git push --tags
```
This Makefile example automates the version bumping and release process by leveraging `git flow` and Poetry commands.
#### Notes
The release script requires git flow to be installed and initialized in your repository.
Ensure your repository is clean and on the correct branch before starting a release.
## Testing
This project uses `pytest` for unit testing.
To run tests:
```bash
poetry run pytest
```
## License
This project is licensed under the Apache License 2.0. See the LICENSE file for details.
## Contribution
We welcome contributions to the Poetry Versions Plugin!
If you have suggestions, bug reports, or pull requests, please
visit our GitHub repository.
## Acknowledgments
Special thanks to the open-source community for their continuous support and contributions.
Your feedback and
contributions are what make projects like this possible!
Feel free to reach out via email for any additional questions or support.
Raw data
{
"_id": null,
"home_page": "https://github.com/xykong/poetry-versions-plugin",
"name": "poetry-versions-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "packaging, poetry, plugin, versioning, git",
"author": "xy.kong",
"author_email": "xy.kong@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2c/99/d9bb7c32f11f0533b82e97f7c0008f9d606792b1ec934247bc185a8007ec/poetry_versions_plugin-0.10.1.tar.gz",
"platform": null,
"description": "# Poetry Versions Plugin\n\nLicense\n\n## Overview\n\nThe Poetry Versions Plugin is a powerful extension for the Poetry dependency manager, designed to automate version\nmanagement and record Git information for Python projects.\nThis plugin simplifies the process of bumping version numbers\nand integrates seamlessly with Git to ensure that all changes are tracked effectively.\n\n## Features\n\n- **Automated Version Management**: Easily bump major, minor, or patch versions using the `poetry version` command.\n- **Git Integration**: Automatically records Git branch, commit, and status information within your project.\n- **Customizable Workflow**: Configure commit message formats, allow/disallow dirty repository states, and specify which\n files to update.\n- **Release Process Automation**: Provides a script to handle releases using git flow, ensuring a streamlined and\n consistent release process.\n\n## Installation\n\nTo install the Poetry Versions Plugin, add it to your Poetry project:\n\n```bash\npoetry add poetry-versions-plugin\n```\n\nPoetry will automatically recognize the plugin without needing additional configuration in your `pyproject.toml`.\n\n## Configuration\n\nConfigure the plugin in your `pyproject.toml` file under the `[tool.versions.settings]` section:\n\n```toml\n[tool.versions.settings]\nallow_dirty = false\ncommit = true\ncommit_on = [\"major\", \"minor\", \"patch\"]\ncommit_message = \"Bump version: {current_version} \u2192 {new_version}\"\nfilename = [\n \"poetry_versions_plugin/versions.py\",\n]\n```\n\n### Main Configuration Options\n\nallow_dirty: (default: false) If set to true, allows the version bumping even if the working directory has uncommitted\nchanges.\ncommit: (default: true) Automatically commit changes to the local git repository after a version bump.\ncommit_on: Specifies which version types (major, minor, patch) trigger an automatic commit.\ncommit_message: Format of the commit message for version bumps.\nfilename: List of additional files to update with the new version information.\n\n## Usage\n\n### Bumping Versions\n\nTo bump the version of your project, use the `poetry version` command with the desired version type:\n\n```bash\npoetry version [major|minor|patch]\n```\n\nThis command updates the version in your `pyproject.toml`, updates additional specified files, and commits changes if\nconfigured.\n\n### Release Process\n\nThe `scripts.release:main` script automates the release process using git flow.\nTo execute a release:\n\n```bash\npoetry run release [major|minor|patch]\n```\n\nThis script performs the following steps:\n\n1. Checks if you're on the `develop` branch.\n2. Verifies there are no uncommitted changes.\n3. Bumps the version number.\n4. Starts and finishes a git flow release.\n5. Publishes the package.\n\n#### Customizing the Release Process with a Makefile\n\nYou can also customize the release process using a Makefile. Here is an example:\n\n```makefile\nbump = patch\nnext-version = $(shell poetry version $(bump) -s --dry-run)\nrelease:\n\t@echo \"Creating a new release...\"\n\tgit flow release start $(next-version)\n\tpoetry version $(bump)\n\tgit flow release finish -m \"publish\"\n\tgit push --all\n\tgit push --tags\n```\n\nThis Makefile example automates the version bumping and release process by leveraging `git flow` and Poetry commands.\n\n#### Notes\n\nThe release script requires git flow to be installed and initialized in your repository.\nEnsure your repository is clean and on the correct branch before starting a release.\n\n## Testing\n\nThis project uses `pytest` for unit testing.\nTo run tests:\n\n```bash\npoetry run pytest\n```\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the LICENSE file for details.\n\n## Contribution\n\nWe welcome contributions to the Poetry Versions Plugin!\nIf you have suggestions, bug reports, or pull requests, please\nvisit our GitHub repository.\n\n## Acknowledgments\n\nSpecial thanks to the open-source community for their continuous support and contributions.\nYour feedback and\ncontributions are what make projects like this possible!\n\nFeel free to reach out via email for any additional questions or support.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Poetry plugin that automates version management and records Git information for Python projects.",
"version": "0.10.1",
"project_urls": {
"Documentation": "https://github.com/xykong/poetry-versions-plugin/blob/master/README.md",
"Homepage": "https://github.com/xykong/poetry-versions-plugin",
"Repository": "https://github.com/xykong/poetry-versions-plugin"
},
"split_keywords": [
"packaging",
" poetry",
" plugin",
" versioning",
" git"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f20ef9767def12dc62a7e343786e41e848560592b374ffa4a7beca2fcb16511",
"md5": "b94a881d41caaaefb3a926c781827a80",
"sha256": "1847c1e108da8c578594dae0ad5810f3a0f38512253ba81702d797167c73da13"
},
"downloads": -1,
"filename": "poetry_versions_plugin-0.10.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b94a881d41caaaefb3a926c781827a80",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 8935,
"upload_time": "2025-02-10T11:44:25",
"upload_time_iso_8601": "2025-02-10T11:44:25.190861Z",
"url": "https://files.pythonhosted.org/packages/3f/20/ef9767def12dc62a7e343786e41e848560592b374ffa4a7beca2fcb16511/poetry_versions_plugin-0.10.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2c99d9bb7c32f11f0533b82e97f7c0008f9d606792b1ec934247bc185a8007ec",
"md5": "867c226079ba9faf1f1f206e5b1fd096",
"sha256": "37255bbcb9bdbc650f3a72b6a12023103a4573b9de352ffe15f2a8cd635b44ee"
},
"downloads": -1,
"filename": "poetry_versions_plugin-0.10.1.tar.gz",
"has_sig": false,
"md5_digest": "867c226079ba9faf1f1f206e5b1fd096",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 8364,
"upload_time": "2025-02-10T11:44:26",
"upload_time_iso_8601": "2025-02-10T11:44:26.950831Z",
"url": "https://files.pythonhosted.org/packages/2c/99/d9bb7c32f11f0533b82e97f7c0008f9d606792b1ec934247bc185a8007ec/poetry_versions_plugin-0.10.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-10 11:44:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xykong",
"github_project": "poetry-versions-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "poetry-versions-plugin"
}
JSON
