| Name | foxy-changelog JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | None |
| Summary | A tool which generates a changelog and manage version for any git repository using conventional commits specification |
| upload_time | 2024-01-27 21:03:51 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
changelog
git
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🦊 Foxy changelog
> [!IMPORTANT]
> This repository is a fork of [auto-changelog](https://github.com/KeNaCo/auto-changelog).
> I decided to do it because auto-changelog is not maintained anymore and I need some changes for my personal usage.
> I will publish these changes for everyone to use but I do not promise to answer to feature request and bug fixes.
>
> **Sadly I do not have time to provide steps to contribute and not everything will be tested.**
A tool which generates a changelog and manage version for any git repository using [`conventional commits`](https://www.conventionalcommits.org/en/v1.0.0/) specification.
- [Installation](#installation)
- [Changelog generation](#changelog-generation)
- [Add to an existing changelog](#add-to-an-existing-changelog)
- [Version management](#version-management)
- [semver-conventional-commit-foxy](#semver-conventional-commit-foxy)
- [calendar-conventional-commit-foxy](#calendar-conventional-commit-foxy)
- [Hatch](#hatch)
- [Configuration](#configuration)
- [Python project](#python-project)
- [Other projects](#other-projects)
- [Command line interface](#command-line-interface)
## Installation
It is recommanded to install this tool with [`pipx`](https://github.com/pypa/pipx) to install it in a isolated environments:
```console
pipx install foxy-changelog
```
## Changelog generation
### Add to an existing changelog
If you’d like to keep an existing changelog below your generated one, just add `<!-- foxy-changelog-above -->` to your current changelog.
The generated changelog will be added above this token, and anything below will remain.
> [!TIP]
> This is quite useful when changing the tag pattern (e.g. from semver to calendar) used to version a project or to help keeping an old manually generated changelog when integrated conventional commit to a project to integrate foxy-changelog.
## Version management
`foxy-changelog` is providing support to automatically generate the version of your python project according to its commit history.
The management is based on [setuptools_scm](https://github.com/pypa/setuptools_scm) and [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/).
As defined in the conventional commit specification:
>- The type `feat` MUST be used when a commit adds a new feature to your application or library.
>- The type `fix` MUST be used when a commit represents a bug fix for your application.
`foxy-changelog` is providing two entry points for `setuptools_scm.version_scheme` configuration.
### semver-conventional-commit-foxy
Based on [semver](https://semver.org/lang/fr/).
Rules:
- A commit with type `feat` activates an increment of the minor.
- All other types will activate an increment of the patch.
> [!NOTE]
> Breaking changes is not supported yet.
### calendar-conventional-commit-foxy
To manage version based on the calendar. The supported convention is YYYY.MM.Patch with Patch a number not 0-padded starting to 1. (example: 2024.01.1).
Rules:
- A commit with type `feat` activates an increment of the month.
- All other types will activate an increment of the patch version.
- The year is automatically incremented at the end a year.
### Hatch
[Hatch](https://github.com/pypa/hatch) is supporting out of the box thanks to [hatch-vcs](https://github.com/ofek/hatch-vcs).
Python projet using other project management tool can use `setuptools_scm` directly.
Ensure `hatch-vcs` and `foxy-changelog` is defined within the `build-system.requires` field in your `pyproject.toml` file.
All other options supported by `hatch-vcs` and `setuptools_scm` can be used. More information can be found in their documentation.
```toml
[build-system]
requires = ["hatchling", "hatch-vcs", "foxy-changelog"]
build-backend = "hatchling.build"
[tool.hatch.version]
source = "vcs"
[tool.hatch.version.raw-options]
version_scheme = "semver-conventional-commit-foxy"
```
## Configuration
`foxy-changelog` can be configured thanks to its command line or configuration files (`foxy-changelog.toml` or `pyproject.toml`).
All the configurations of the command line to be also put in the configuration files for easier usage.
Configurations files are automatically looked up in the project's folder but custom path can always to passed to the command line.
Configurations from different sources are considered with an defined order.
Commande line options overrides configurations from `foxy-changelog.toml` which overrides configurations from `pyproject.toml`.
### Python project
`pyproject.toml` is supported and is the recommanded way to configure python projects.
The following configuration block can be added to the `pyproject.toml` file.
```toml
[tool.foxy-changelog.changelog]
tag_pattern = "semver"
```
If no title and description are provided the one from `project` configuration are taken.
### Other projects
`foxy-changelog.toml` is recommanded way.
The following configuration block can be added to the `foxy-changelog.toml` file.
```toml
[changelog]
tag_pattern = "semver"
```
## Command line interface
You can list the command line options by running `foxy-changelog --help`:
```console
Usage: foxy-changelog [OPTIONS]
Options:
-c, --config PATH path to 'pyproject.toml' with foxy-changelog
config or 'foxy-changelog.toml' , default: looked
up in the current or parent directories
--gitlab Set Gitlab Pattern Generation.
--github Set GitHub Pattern Generation.
-p, --path-repo PATH Path to the repository's root directory
[Default: .]
-t, --title TEXT The changelog's title [Default: Changelog]
-d, --description TEXT Your project's description
-o, --output FILENAME The place to save the generated changelog
[Default: CHANGELOG.md]
-r, --remote TEXT Specify git remote to use for links
-v, --latest-version TEXT use specified version as latest release
-u, --unreleased Include section for unreleased changes
--template TEXT specify template to use [compact, lastrelease] or a path
to a custom template, default: compact
--diff-url TEXT override url for compares, use {current} and
{previous} for tags
--issue-url TEXT Override url for issues, use {id} for issue id
--issue-pattern TEXT Override regex pattern for issues in commit
messages. Should contain two groups, original
match and ID used by issue-url.
--tag-pattern TEXT Specify regex pattern for version tags [semver,
calendar, custom-regex]. A custom regex containing
one group named 'version' can be specified.
[default: semver]
--tag-prefix TEXT prefix used in version tags, default: ""
--stdout
--tag-pattern TEXT Override regex pattern for release tags
--starting-commit TEXT Starting commit to use for changelog generation
--stopping-commit TEXT Stopping commit to use for changelog generation
--debug set logging level to DEBUG
--help Show this message and exit.
```
Raw data
{
"_id": null,
"home_page": null,
"name": "foxy-changelog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "changelog,git",
"author": null,
"author_email": "Michael F Bryan <michaelfbryan@gmail.com>, Ken Mijime <kenaco666@gmail.com>, Fabien Hermitte <email@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/5a/45a061c458ef872daff6eeee18beb198672460e059548d51b8691fa2254d/foxy_changelog-1.2.0.tar.gz",
"platform": null,
"description": "# \ud83e\udd8a Foxy changelog\n\n> [!IMPORTANT]\n> This repository is a fork of [auto-changelog](https://github.com/KeNaCo/auto-changelog).\n> I decided to do it because auto-changelog is not maintained anymore and I need some changes for my personal usage.\n> I will publish these changes for everyone to use but I do not promise to answer to feature request and bug fixes.\n>\n> **Sadly I do not have time to provide steps to contribute and not everything will be tested.**\n\nA tool which generates a changelog and manage version for any git repository using [`conventional commits`](https://www.conventionalcommits.org/en/v1.0.0/) specification.\n\n- [Installation](#installation)\n- [Changelog generation](#changelog-generation)\n - [Add to an existing changelog](#add-to-an-existing-changelog)\n- [Version management](#version-management)\n - [semver-conventional-commit-foxy](#semver-conventional-commit-foxy)\n - [calendar-conventional-commit-foxy](#calendar-conventional-commit-foxy)\n - [Hatch](#hatch)\n- [Configuration](#configuration)\n - [Python project](#python-project)\n - [Other projects](#other-projects)\n- [Command line interface](#command-line-interface)\n\n## Installation\n\nIt is recommanded to install this tool with [`pipx`](https://github.com/pypa/pipx) to install it in a isolated environments:\n\n```console\npipx install foxy-changelog\n```\n\n## Changelog generation\n\n### Add to an existing changelog\n\nIf you\u2019d like to keep an existing changelog below your generated one, just add `<!-- foxy-changelog-above -->` to your current changelog.\nThe generated changelog will be added above this token, and anything below will remain.\n\n> [!TIP]\n> This is quite useful when changing the tag pattern (e.g. from semver to calendar) used to version a project or to help keeping an old manually generated changelog when integrated conventional commit to a project to integrate foxy-changelog.\n\n## Version management\n\n`foxy-changelog` is providing support to automatically generate the version of your python project according to its commit history.\n\nThe management is based on [setuptools_scm](https://github.com/pypa/setuptools_scm) and [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/).\n\nAs defined in the conventional commit specification:\n\n>- The type `feat` MUST be used when a commit adds a new feature to your application or library.\n>- The type `fix` MUST be used when a commit represents a bug fix for your application.\n\n`foxy-changelog` is providing two entry points for `setuptools_scm.version_scheme` configuration.\n\n### semver-conventional-commit-foxy\n\nBased on [semver](https://semver.org/lang/fr/).\n\nRules:\n\n- A commit with type `feat` activates an increment of the minor.\n- All other types will activate an increment of the patch.\n\n> [!NOTE]\n> Breaking changes is not supported yet.\n\n### calendar-conventional-commit-foxy\n\nTo manage version based on the calendar. The supported convention is YYYY.MM.Patch with Patch a number not 0-padded starting to 1. (example: 2024.01.1).\n\nRules:\n\n- A commit with type `feat` activates an increment of the month.\n- All other types will activate an increment of the patch version.\n- The year is automatically incremented at the end a year.\n\n### Hatch\n\n[Hatch](https://github.com/pypa/hatch) is supporting out of the box thanks to [hatch-vcs](https://github.com/ofek/hatch-vcs).\nPython projet using other project management tool can use `setuptools_scm` directly.\n\nEnsure `hatch-vcs` and `foxy-changelog` is defined within the `build-system.requires` field in your `pyproject.toml` file.\n\nAll other options supported by `hatch-vcs` and `setuptools_scm` can be used. More information can be found in their documentation.\n\n```toml\n[build-system]\nrequires = [\"hatchling\", \"hatch-vcs\", \"foxy-changelog\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.version]\nsource = \"vcs\"\n\n[tool.hatch.version.raw-options]\nversion_scheme = \"semver-conventional-commit-foxy\"\n```\n\n## Configuration\n\n`foxy-changelog` can be configured thanks to its command line or configuration files (`foxy-changelog.toml` or `pyproject.toml`).\nAll the configurations of the command line to be also put in the configuration files for easier usage.\n\nConfigurations files are automatically looked up in the project's folder but custom path can always to passed to the command line.\nConfigurations from different sources are considered with an defined order.\nCommande line options overrides configurations from `foxy-changelog.toml` which overrides configurations from `pyproject.toml`.\n\n### Python project\n\n`pyproject.toml` is supported and is the recommanded way to configure python projects.\n\nThe following configuration block can be added to the `pyproject.toml` file.\n\n```toml\n[tool.foxy-changelog.changelog]\ntag_pattern = \"semver\"\n```\n\nIf no title and description are provided the one from `project` configuration are taken.\n\n### Other projects\n\n`foxy-changelog.toml` is recommanded way.\n\nThe following configuration block can be added to the `foxy-changelog.toml` file.\n\n```toml\n[changelog]\ntag_pattern = \"semver\"\n```\n\n## Command line interface\n\nYou can list the command line options by running `foxy-changelog --help`:\n\n```console\nUsage: foxy-changelog [OPTIONS]\n\nOptions:\n-c, --config PATH path to 'pyproject.toml' with foxy-changelog\n config or 'foxy-changelog.toml' , default: looked\n up in the current or parent directories\n--gitlab Set Gitlab Pattern Generation.\n--github Set GitHub Pattern Generation.\n-p, --path-repo PATH Path to the repository's root directory\n [Default: .]\n\n-t, --title TEXT The changelog's title [Default: Changelog]\n-d, --description TEXT Your project's description\n-o, --output FILENAME The place to save the generated changelog\n [Default: CHANGELOG.md]\n\n-r, --remote TEXT Specify git remote to use for links\n-v, --latest-version TEXT use specified version as latest release\n-u, --unreleased Include section for unreleased changes\n--template TEXT specify template to use [compact, lastrelease] or a path\n to a custom template, default: compact\n\n--diff-url TEXT override url for compares, use {current} and\n {previous} for tags\n\n--issue-url TEXT Override url for issues, use {id} for issue id\n--issue-pattern TEXT Override regex pattern for issues in commit\n messages. Should contain two groups, original\n match and ID used by issue-url.\n\n--tag-pattern TEXT Specify regex pattern for version tags [semver,\n calendar, custom-regex]. A custom regex containing\n one group named 'version' can be specified.\n [default: semver]\n\n--tag-prefix TEXT prefix used in version tags, default: \"\"\n--stdout\n--tag-pattern TEXT Override regex pattern for release tags\n--starting-commit TEXT Starting commit to use for changelog generation\n--stopping-commit TEXT Stopping commit to use for changelog generation\n--debug set logging level to DEBUG\n--help Show this message and exit.\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool which generates a changelog and manage version for any git repository using conventional commits specification",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://github.com/LeMimit/foxy-changelog#readme",
"Issues": "https://github.com/LeMimit/foxy-changelog/issues",
"Source": "https://github.com/LeMimit/foxy-changelog"
},
"split_keywords": [
"changelog",
"git"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "54eaa090f58ab9a2bd6b9c4d43ec8523c037f2d02f67f32091c5216985e10c59",
"md5": "6823fab846f9483aa4e13fc1bd66dd6b",
"sha256": "4a5bc17d473eba0133d5a04efe2bf91d49fab68f929bcc75f14afaf5d46bacec"
},
"downloads": -1,
"filename": "foxy_changelog-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6823fab846f9483aa4e13fc1bd66dd6b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22874,
"upload_time": "2024-01-27T21:03:50",
"upload_time_iso_8601": "2024-01-27T21:03:50.161343Z",
"url": "https://files.pythonhosted.org/packages/54/ea/a090f58ab9a2bd6b9c4d43ec8523c037f2d02f67f32091c5216985e10c59/foxy_changelog-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c35a45a061c458ef872daff6eeee18beb198672460e059548d51b8691fa2254d",
"md5": "7658ee226681fbc7d5a889f0727f6e49",
"sha256": "3cc71b2191cbef0e7f863da8186bd7c28127b70905e5658707485deee9b472cf"
},
"downloads": -1,
"filename": "foxy_changelog-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7658ee226681fbc7d5a889f0727f6e49",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32359,
"upload_time": "2024-01-27T21:03:51",
"upload_time_iso_8601": "2024-01-27T21:03:51.898804Z",
"url": "https://files.pythonhosted.org/packages/c3/5a/45a061c458ef872daff6eeee18beb198672460e059548d51b8691fa2254d/foxy_changelog-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-27 21:03:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LeMimit",
"github_project": "foxy-changelog#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "foxy-changelog"
}
