<a href="https://www.espressif.com">
<img src="https://www.espressif.com/sites/all/themes/espressif/logo-black.svg" alt="Espressif logo" title="Espressif" align="right" height="20" />
</a>
# Commitizen plugin czEspressif
This is a plugin for Commitizen that makes it easy to create and maintain a well-organized and good-looking `CHANGELOG.md`. It also takes care of version bumping and helps you write commit messages that follow Espressif standards.
All of this with minimal config and setup, so your `pyproject.toml` file stays clean and simple.
<!-- GitHub Badges -->
<div align="center">
<p>
<hr>
<img alt="GitHub Release" src="https://img.shields.io/github/v/release/espressif/cz-plugin-espressif? display_name=release&logo=github&logoColor=white&label=Release">
<img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/czespressif?logo=pypi&logoColor=white&label=Pythons&link=https%3A%2F%2Fpypi.org%2Fproject%2Fczespressif%2F">
<img alt="Static Badge" src="https://img.shields.io/badge/pip%20install-czespressif-black?logo=python&logoColor=white">
<a href="/LICENSE"><img alt="Project License" src="https://img.shields.io/pypi/l/czespressif"/></a>
<br>
<img alt="GitHub contributors" src="https://img.shields.io/github/contributors/espressif/cz-plugin-espressif?logo=github&label=Contributors&color=purple">
<img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/y/espressif/cz-plugin-espressif?logo=git&logoColor=white&label=Commits&color=purple">
<img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/espressif/cz-plugin-espressif?logo=git&logoColor=white&label=Last%20commit">
<img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/czespressif?logo=pypi&logoColor=white&label=PyPI%20downloads&color=blue&cacheSeconds=3600&link=https%3A%2F%2Fpypi.org%2Fproject%2Fczespressif%2F">
<br>
<img alt="GitHub workflow Tests Pytest" src="https://img.shields.io/github/actions/workflow/status/espressif/cz-plugin-espressif/.github%2Fworkflows%2Fplugin-tests.yml?branch=master&logo=pytest&logoColor=white&label=Tests&link=https%3A%2F%2Fgithub.com%2Fespressif%2Fcz-plugin-espressif%2Factions%2Fworkflows%2Fplugin-tests.yml">
<img alt="GitHub workflow SyncJira" src="https://img.shields.io/github/actions/workflow/status/espressif/cz-plugin-espressif/.github%2Fworkflows%2Fsync-jira.yml?branch=master&logo=jirasoftware&label=Sync with Jira&link=https%3A%2F%2Fgithub.com%2Fespressif%2Fcz-plugin-espressif%2Factions%2Fworkflows%2Fsync-jira.yml">
<img alt="GitHub workflow CodeQL" src="https://img.shields.io/github/actions/workflow/status/espressif/cz-plugin-espressif/.github%2Fworkflows%2Fcode-ql.yml?branch=master&label=CodeQL">
</p>
<small>
<b>
<a href="https://github.com/espressif/cz-plugin-espressif/issues/new?assignees=&labels=Type%3A+Bug&projects=&template=01-BUG-REPORT.yml">Report bug</a>
·
<a href="https://github.com/espressif/cz-plugin-espressif/issues/new?assignees=&labels=Type%3A+Feature\+Request&projects=&template=02-FEATURE-REQUEST.yml">Request Feature</a>
</b>
</small>
<hr>
</div>
- [Commitizen plugin czEspressif](#commitizen-plugin-czespressif)
- [Features](#features)
- [Compatibility](#compatibility)
- [Install](#install)
- [Usage](#usage)
- [Create Changelog file](#create-changelog-file)
- [Bump Release version](#bump-release-version)
- [GitHub Action for Automated Release Creation](#github-action-for-automated-release-creation)
- [Create commit messages](#create-commit-messages)
- [Examples of good commit messages](#examples-of-good-commit-messages)
- [Configuration](#configuration)
- [Minimal setup](#minimal-setup)
- [Optimal setup](#optimal-setup)
- [Additional configurable parameters](#additional-configurable-parameters)
- [Solving Troubles](#solving-troubles)
- [Pre-commit hook (beta)](#pre-commit-hook-beta)
- [Contributing](#contributing)
- [License](#license)
- [Credits](#credits)
---
## Features
- Can be almost zero-config but offers many customization options if your project needs it.
- Predefined **CHANGELOG template** with default categories _Breaking changes / New features / Bug fixes / Documentation / Code refactoring / Removals_.
- The CHANGELOG automatically displays commits and the authors of those commits.
- The default order in the changelog categories lists commits with a scope first, followed by the rest, both groups sorted alphabetically.
- Predefined **Release Notes template** that can be used in an automated release workflow.
- `cz commit` command with default Espressif commit types, aligned with the Espressif pre-commit linter.
- You can use pre-commit hook that triggers a local changelog update (Unreleased section) when version files change.
---
## Compatibility
[This plugin](https://pypi.org/project/czespressif/) requires Python 3.9 or higher. It should run on pretty much any anything (Linux, Mac, Windows, amd64, aarch64).
If you encounter issues with a specific architecture or OS, please [report it here](https://github.com/espressif/cz-plugin-espressif/issues/new?assignees=&labels=Type%3A+Bug&projects=&template=01-BUG-REPORT.yml), and we will try to address it as soon as possible.
---
## Install
Install with `pip` or your favorite package manager:
```sh
pip install czespressif
```
Then add this snippet to \`pyproject.toml:
```ini
[tool.commitizen]
name = "czespressif"
bump_message = 'change(bump): release $current_version → $new_version [skip-ci]'
```
And verify that installation and setup was successful by showing the example.
```sh
cz example
```
> \[!TIP\]
> You can also add it to your project `dev` dependencies (suggested) and run the sync command (`pipenv sync`, `pip-sync`, `poetry install`, ...).
>
> commitizen itself is in the plugin's dependencies, so pip will take care of everything.
> \[!WARNING\]
> Don't try to install it system-wide with `pipx`; it likely won't work as expected.
> (This option will be explored in the future, and once a solution is found, we will update this recommendation.)
---
## Usage
> \[!TIP\]
> You can check the implementation of this command in the GitHub workflow [.github/workflows/create-release.yml](.github/workflows/create-release.yml) if you're interested.
> In this project's [tests/**snapshots**/test_changelog/](tests/__snapshots__/test_changelog/) directory, we store snapshots used for automated testing. These snapshots **also serve as examples of the plugin's output**.
> You can explore them and compare the plugin output (`test_changelog_czespressif_*.md`) with the default Commitizen output (`test_changelog_cz_default_*.md`), which is generated when our plugin is not used.
### Create Changelog file
If a changelog already exists in your project, make sure you have staged or committed its latest version.
This command turns your old changelog into a nicely organized template based on the [Keep a Changelog standard](https://keepachangelog.com/en/1.1.0/).
```sh
cz changelog
```
### Bump Release version
Is better to first run:
```sh
cz bump --dry-run
```
This only shows the future version and the part of the changelog that will be updated. When all ok, do the same without `--dry-run` flag.
### GitHub Action for Automated Release Creation
In automated scenarios, such as GitHub Actions workflows, you may want to create project releases automatically. This can be easily achieved by parsing the changelog to extract the "Release notes" relevant to the current release.
In this repository, there is a GitHub workflow (`.github/workflows/create-release.yml`) that follows this strategy. To trigger a release, the repository admin simply needs to push a release tag to the origin (GitHub).
This triggers the workflow, which builds all Python binaries for all combinations of Python versions, operating systems, and architectures. It then parses the changelog to extract the release notes (only the section related to the current release, without any headers, footers, etc.), creates a GitHub release, and uploads the binaries both to the GitHub release and the PyPI registry.
The following command generates the changelog for the release version v4.8.0, using the internal template for release notes and writing the partial changelog to a file:
```sh
cz changelog v4.8.0 --template="RELEASE_NOTES.md.j2" --file-name="Release_notes.md"
```
**Release notes custom footer**: You can append a custom footer to the end of the release notes snippet. For example, if you want to include a link to something important for your project, or maybe some GitHub badges, and so on, you can do that.
You can check [example without a footer (default)](docs/Release_notes_example.md) and [example with a custom footer](docs/Release_notes_example_with_footer.md).
> \[!IMPORTANT\]
> Note that the custom template for release notes is part of the czespressif plugin, not the target (your project) repository.
> Any custom settings you define for the changelog locally in the project configuration will also apply to the release notes. For example, if you change the order of sections in the changelog, the release notes will reflect that change as well.
>
> This approach ensures consistent visual styling and allows repository admins to configure everything in one place.
> \[!TIP\]
> You can check the implementation of this command in the GitHub workflow [.github/workflows/create-release.yml](.github/workflows/create-release.yml) if you're interested.
### Create commit messages
In case anyone actually prefers this way of creating commit messages, the command in this plugin is aligned with the Espressif commit linter and DangerJS linters.:
```sh
cz commit
```
```
? Select the type of change you are committing (Use arrow keys)
» feat ✨ A new feature
fix 🐛 A bug fix
change 🏗️ A change made to the codebase.
docs 📖 Documentation only change
test 🚦 Adding missing or correcting existing tests
ci ⚙️ Changes to CI configuration files and scripts
refactor 🔧 A changeset neither fixing a bug nor adding a feature
revert 🔙 Revert one or more commits
remove 🗑️ Removing code or files
```
### Examples of good commit messages
If you are unsure about the commit message standard, run:
```sh
cz example
```
This will bring up a complete example of good commit messages and commit schema in the terminal.
---
## Configuration
Config is accepted in `pyproject.toml` (priority, following example), `.cz.toml`, `.cz.json`, `cz.json`, `.cz.yaml`, `cz.yaml`, and `cz.toml`.
### Minimal setup
> \[!TIP\]
> Try to be minimalistic with custom configs. The best approach is to keep the defaults, so all Espressif projects maintain the same look and feel.
> Also, you will save yourself troubles with non-standard setups.
```ini
[tool.commitizen]
name = "czespressif"
bump_message = 'change(bump): release $current_version → $new_version [skip-ci]'
```
### Optimal setup
```ini
[tool.commitizen]
name = "czespressif"
bump_message = 'change(bump): release $current_version → $new_version [skip-ci]'
# see commitizen docs, following are standard configs
annotated_tag = true
changelog_merge_prerelease = true
tag_format = "v$version"
update_changelog_on_bump = true
version = "1.2.3"
version_files = ["<src>/__init__.py:__version__"]
version_provider = "commitizen"
```
### Additional configurable parameters
```ini
[tool.commitizen]
...
# - Section emojis in the changelog, emojis in CLI command `cz commit` -
# Default: true; false = do not display emojis
# Note: Emojis are never added in the commit messages.
use_emoji = false
# - Custom text of changelog title -
# Note: "" (empty string) disables title
changelog_title = "Our changelog"
# - Custom text of changelog header -
# Note: "" (empty string) disables header
changelog_header = "This is our changelog.\nAll cool things we do are here.\n\nPlease read it."
# - Custom text of changelog footer -
# Note: "" (empty string) disables footer
changelog_footer = "This is the end of our changelog.\n\nMore cool things are coming."
# - Horizontal lines between release sections in the changelog -
# Default: true; false = removes lines
changelog_section_line = false # default (true); false = removes horizontal lines between releases
# - Section "Unreleased" in the changelog -
# Default: true; false = removes section Unreleased, keeps only releases
changelog_unreleased = false
# - Authors of the changes (commits) in the changelog -
# Default: true; false = do not display authors
changelog_show_authors = false
# - Commit numbers (short SHA) in the changelog -
# Default: true; false = do not display commit numbers
changelog_show_commits = false
# - Change orders in which sections displays in the changelog -
# Default: this example is default
change_type_order = [ # with enabled emojis
'🚨 Breaking changes',
'✨ New features',
'🐛 Bug fixes',
'📖 Documentation',
'🔧 Code refactoring',
'🗑️ Removals',
'🏗️ Changes', # in default not in the changelog
'⚙️ CI and project settings', # in default not in the changelog
'🚦 Testing', # in default not in the changelog
'🔙 Reverted', # in default not in the changelog
]
change_type_order = [ # same thing, with disabled emojis
'Breaking changes',
'New features',
'Bug fixes',
'Documentation',
'Code refactoring',
'Removals',
'Changes', # in default not in the changelog
'CI and project settings', # in default not in the changelog
'Testing', # in default not in the changelog
'Reverted', # in default not in the changelog
]
# - Redefine which types are shown in the changelog -
# Note: You need to list here ALL types that you want to have in the changelog - included default ones
# Note: The order in this list doesn't matter — if you want to change the sections' order too, use with "change_type_order."
types_in_changelog = ["feat", "fix", "refactor", "style", "ci"]
# - Custom text that you can append to release notes output -
# Default: Null (in default there is no custom footer )
release_notes_footer = """Thanks to <FILL OUT CONTRIBUTORS>, and others for contributing to this release!"""
# - Add extra commit types for 'cz commit' and to the changelog (sections) -
# Note: If you are working with custom commit types, ensure your commit linter and PR/MR linter is set same way
[[tool.commitizen.extra_types]]
type = "style"
heading = "Code Style"
emoji = "🎨"
description = "Changes that do not affect the meaning of the code (white-space, formatting, etc.)"
bump = "PATCH"
changelog = true
```
---
## Solving Troubles
The plugin `czespressif` has `commitizen` as its dependency, so users only need to install `czespressif`, and that will automatically install the proper version of `commitizen`. This plugin requires at least version 3.29 of `commitizen` to work properly. Older versions either cause errors like this:
```log
The committer has not been found in the system.
Try running 'pip install czespressif'
```
... or `czespressif` plugin partially works but behaves in weird and unexpected ways.
If you encounter this error, it probably means that you have a conflicting version of commitizen installed on your system, and this old version is prioritized in your system path.
You can copy and paste this snippet into your terminal to check if this is the case:
```sh
clear;if command -v cz &> /dev/null; then
cz_version=$(cz version | awk '{print $NF}')
if [ "$(printf '%s\n' "3.29" "$cz_version" | sort -V | head -n1)" = "3.29" ]; then
echo "Commitizen version $cz_version is OK."
else
echo "Commitizen version $cz_version is too old. Found at $(which cz)."
echo "Please uninstall it with 'pip uninstall commitizen' or 'pipx uninstall commitizen'."
fi
else
echo "No Commitizen found, but you are not in a virtual environment."
echo "Consider creating/activating a virtual environment first and installing by 'pip install czespressif'."
fi
```
> \[!TIP\]
> For each Python project, use a virtual environment. If you install everything with pip to the system Python, you risk running into unsolvable dependency issues and possibly breaking some system tools.
>
> If your project isn’t a Python project and you don’t care about python virtual envs, at least ensure you don’t have multiple outdated versions of some Python packages, such as commitizen in this case.
---
## Pre-commit hook (beta)
To automatically keep your changelog's "Unreleased" section up to date, add the following to your `.pre-commit-config.yaml` file:
```yaml
- repo: https://github.com/espressif/cz-plugin-espressif
rev: ''
hooks:
- id: update-changelog
```
Next, run the following command to fetch the latest version (`rev:`):
```sh
pre-commit autoupdate --repo https://github.com/espressif/cz-plugin-espressif
```
If you have already set `default_install_hook_types`, then include `pre-push` in the list. Otherwise, add the following to your `.pre-commit-config.yaml` file:
```yaml
default_install_hook_types: [pre-commit, pre-push]
```
After installing the hook, it runs automatically before you pushing commits to the repository. It updates the changelog with the latest commits. If the push failed because of the hook, don't forget to add the updated changelog to the commit and push again.
---
## Contributing
We welcome contributions from the community! Please read the [Contributing Guide](CONTRIBUTING.md) to learn how to get involved.
---
## License
This PROJECT is licensed under the [Apache 2.0 License](LICENSE).
---
## Credits
This was inspired by the project [Emotional](https://github.com/noirbizarre/emotional), created by [Axel H. / @noirbizarre](https://github.com/noirbizarre).
- If you are looking for **similar and customizable plugin for projects outside Espressif** organization, you should definitely try [Emotional](https://github.com/noirbizarre/emotional).
- If you are learning Python and want to write clean and well-organized, pro-level code, you should definitely check out [Emotional](https://github.com/noirbizarre/emotional).
---
Raw data
{
"_id": null,
"home_page": null,
"name": "czespressif",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Espressif Systems",
"author_email": "Tomas Sebestik <tomas.sebestik@espressif.com>",
"download_url": "https://files.pythonhosted.org/packages/2f/e3/1e09a2438c8721c556854c18365c7f299b30b3256ef1369819a2312a5f50/czespressif-1.3.0.tar.gz",
"platform": null,
"description": "<a href=\"https://www.espressif.com\">\n <img src=\"https://www.espressif.com/sites/all/themes/espressif/logo-black.svg\" alt=\"Espressif logo\" title=\"Espressif\" align=\"right\" height=\"20\" />\n</a>\n\n# Commitizen plugin czEspressif\n\nThis is a plugin for Commitizen that makes it easy to create and maintain a well-organized and good-looking `CHANGELOG.md`. It also takes care of version bumping and helps you write commit messages that follow Espressif standards.\n\nAll of this with minimal config and setup, so your `pyproject.toml` file stays clean and simple.\n\n<!-- GitHub Badges -->\n\n<div align=\"center\">\n <p>\n <hr>\n <img alt=\"GitHub Release\" src=\"https://img.shields.io/github/v/release/espressif/cz-plugin-espressif? display_name=release&logo=github&logoColor=white&label=Release\">\n <img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/czespressif?logo=pypi&logoColor=white&label=Pythons&link=https%3A%2F%2Fpypi.org%2Fproject%2Fczespressif%2F\">\n <img alt=\"Static Badge\" src=\"https://img.shields.io/badge/pip%20install-czespressif-black?logo=python&logoColor=white\">\n <a href=\"/LICENSE\"><img alt=\"Project License\" src=\"https://img.shields.io/pypi/l/czespressif\"/></a>\n <br>\n <img alt=\"GitHub contributors\" src=\"https://img.shields.io/github/contributors/espressif/cz-plugin-espressif?logo=github&label=Contributors&color=purple\">\n <img alt=\"GitHub commit activity\" src=\"https://img.shields.io/github/commit-activity/y/espressif/cz-plugin-espressif?logo=git&logoColor=white&label=Commits&color=purple\">\n <img alt=\"GitHub last commit\" src=\"https://img.shields.io/github/last-commit/espressif/cz-plugin-espressif?logo=git&logoColor=white&label=Last%20commit\">\n <img alt=\"PyPI - Downloads\" src=\"https://img.shields.io/pypi/dm/czespressif?logo=pypi&logoColor=white&label=PyPI%20downloads&color=blue&cacheSeconds=3600&link=https%3A%2F%2Fpypi.org%2Fproject%2Fczespressif%2F\">\n <br>\n <img alt=\"GitHub workflow Tests Pytest\" src=\"https://img.shields.io/github/actions/workflow/status/espressif/cz-plugin-espressif/.github%2Fworkflows%2Fplugin-tests.yml?branch=master&logo=pytest&logoColor=white&label=Tests&link=https%3A%2F%2Fgithub.com%2Fespressif%2Fcz-plugin-espressif%2Factions%2Fworkflows%2Fplugin-tests.yml\">\n <img alt=\"GitHub workflow SyncJira\" src=\"https://img.shields.io/github/actions/workflow/status/espressif/cz-plugin-espressif/.github%2Fworkflows%2Fsync-jira.yml?branch=master&logo=jirasoftware&label=Sync with Jira&link=https%3A%2F%2Fgithub.com%2Fespressif%2Fcz-plugin-espressif%2Factions%2Fworkflows%2Fsync-jira.yml\">\n <img alt=\"GitHub workflow CodeQL\" src=\"https://img.shields.io/github/actions/workflow/status/espressif/cz-plugin-espressif/.github%2Fworkflows%2Fcode-ql.yml?branch=master&label=CodeQL\">\n </p>\n <small>\n <b>\n <a href=\"https://github.com/espressif/cz-plugin-espressif/issues/new?assignees=&labels=Type%3A+Bug&projects=&template=01-BUG-REPORT.yml\">Report bug</a>\n \u00b7\n <a href=\"https://github.com/espressif/cz-plugin-espressif/issues/new?assignees=&labels=Type%3A+Feature\\+Request&projects=&template=02-FEATURE-REQUEST.yml\">Request Feature</a>\n </b>\n </small>\n <hr>\n</div>\n\n- [Commitizen plugin czEspressif](#commitizen-plugin-czespressif)\n - [Features](#features)\n - [Compatibility](#compatibility)\n - [Install](#install)\n - [Usage](#usage)\n - [Create Changelog file](#create-changelog-file)\n - [Bump Release version](#bump-release-version)\n - [GitHub Action for Automated Release Creation](#github-action-for-automated-release-creation)\n - [Create commit messages](#create-commit-messages)\n - [Examples of good commit messages](#examples-of-good-commit-messages)\n - [Configuration](#configuration)\n - [Minimal setup](#minimal-setup)\n - [Optimal setup](#optimal-setup)\n - [Additional configurable parameters](#additional-configurable-parameters)\n - [Solving Troubles](#solving-troubles)\n - [Pre-commit hook (beta)](#pre-commit-hook-beta)\n - [Contributing](#contributing)\n - [License](#license)\n - [Credits](#credits)\n\n---\n\n## Features\n\n- Can be almost zero-config but offers many customization options if your project needs it.\n- Predefined **CHANGELOG template** with default categories _Breaking changes / New features / Bug fixes / Documentation / Code refactoring / Removals_.\n- The CHANGELOG automatically displays commits and the authors of those commits.\n- The default order in the changelog categories lists commits with a scope first, followed by the rest, both groups sorted alphabetically.\n- Predefined **Release Notes template** that can be used in an automated release workflow.\n- `cz commit` command with default Espressif commit types, aligned with the Espressif pre-commit linter.\n- You can use pre-commit hook that triggers a local changelog update (Unreleased section) when version files change.\n\n---\n\n## Compatibility\n\n[This plugin](https://pypi.org/project/czespressif/) requires Python 3.9 or higher. It should run on pretty much any anything (Linux, Mac, Windows, amd64, aarch64).\n\nIf you encounter issues with a specific architecture or OS, please [report it here](https://github.com/espressif/cz-plugin-espressif/issues/new?assignees=&labels=Type%3A+Bug&projects=&template=01-BUG-REPORT.yml), and we will try to address it as soon as possible.\n\n---\n\n## Install\n\nInstall with `pip` or your favorite package manager:\n\n```sh\npip install czespressif\n```\n\nThen add this snippet to \\`pyproject.toml:\n\n```ini\n[tool.commitizen]\n name = \"czespressif\"\n bump_message = 'change(bump): release $current_version \u2192 $new_version [skip-ci]'\n```\n\nAnd verify that installation and setup was successful by showing the example.\n\n```sh\ncz example\n```\n\n> \\[!TIP\\]\n> You can also add it to your project `dev` dependencies (suggested) and run the sync command (`pipenv sync`, `pip-sync`, `poetry install`, ...).\n>\n> commitizen itself is in the plugin's dependencies, so pip will take care of everything.\n\n> \\[!WARNING\\]\n> Don't try to install it system-wide with `pipx`; it likely won't work as expected.\n> (This option will be explored in the future, and once a solution is found, we will update this recommendation.)\n\n---\n\n## Usage\n\n> \\[!TIP\\]\n> You can check the implementation of this command in the GitHub workflow [.github/workflows/create-release.yml](.github/workflows/create-release.yml) if you're interested.\n> In this project's [tests/**snapshots**/test_changelog/](tests/__snapshots__/test_changelog/) directory, we store snapshots used for automated testing. These snapshots **also serve as examples of the plugin's output**.\n> You can explore them and compare the plugin output (`test_changelog_czespressif_*.md`) with the default Commitizen output (`test_changelog_cz_default_*.md`), which is generated when our plugin is not used.\n\n### Create Changelog file\n\nIf a changelog already exists in your project, make sure you have staged or committed its latest version.\n\nThis command turns your old changelog into a nicely organized template based on the [Keep a Changelog standard](https://keepachangelog.com/en/1.1.0/).\n\n```sh\ncz changelog\n```\n\n### Bump Release version\n\nIs better to first run:\n\n```sh\ncz bump --dry-run\n```\n\nThis only shows the future version and the part of the changelog that will be updated. When all ok, do the same without `--dry-run` flag.\n\n### GitHub Action for Automated Release Creation\n\nIn automated scenarios, such as GitHub Actions workflows, you may want to create project releases automatically. This can be easily achieved by parsing the changelog to extract the \"Release notes\" relevant to the current release.\n\nIn this repository, there is a GitHub workflow (`.github/workflows/create-release.yml`) that follows this strategy. To trigger a release, the repository admin simply needs to push a release tag to the origin (GitHub).\nThis triggers the workflow, which builds all Python binaries for all combinations of Python versions, operating systems, and architectures. It then parses the changelog to extract the release notes (only the section related to the current release, without any headers, footers, etc.), creates a GitHub release, and uploads the binaries both to the GitHub release and the PyPI registry.\n\nThe following command generates the changelog for the release version v4.8.0, using the internal template for release notes and writing the partial changelog to a file:\n\n```sh\ncz changelog v4.8.0 --template=\"RELEASE_NOTES.md.j2\" --file-name=\"Release_notes.md\"\n\n```\n\n**Release notes custom footer**: You can append a custom footer to the end of the release notes snippet. For example, if you want to include a link to something important for your project, or maybe some GitHub badges, and so on, you can do that.\n\nYou can check [example without a footer (default)](docs/Release_notes_example.md) and [example with a custom footer](docs/Release_notes_example_with_footer.md).\n\n> \\[!IMPORTANT\\]\n> Note that the custom template for release notes is part of the czespressif plugin, not the target (your project) repository.\n> Any custom settings you define for the changelog locally in the project configuration will also apply to the release notes. For example, if you change the order of sections in the changelog, the release notes will reflect that change as well.\n>\n> This approach ensures consistent visual styling and allows repository admins to configure everything in one place.\n\n> \\[!TIP\\]\n> You can check the implementation of this command in the GitHub workflow [.github/workflows/create-release.yml](.github/workflows/create-release.yml) if you're interested.\n\n### Create commit messages\n\nIn case anyone actually prefers this way of creating commit messages, the command in this plugin is aligned with the Espressif commit linter and DangerJS linters.:\n\n```sh\ncz commit\n```\n\n```\n? Select the type of change you are committing (Use arrow keys)\n \u00bb feat \u2728 A new feature\n fix \ud83d\udc1b A bug fix\n change \ud83c\udfd7\ufe0f A change made to the codebase.\n docs \ud83d\udcd6 Documentation only change\n test \ud83d\udea6 Adding missing or correcting existing tests\n ci \u2699\ufe0f Changes to CI configuration files and scripts\n refactor \ud83d\udd27 A changeset neither fixing a bug nor adding a feature\n revert \ud83d\udd19 Revert one or more commits\n remove \ud83d\uddd1\ufe0f Removing code or files\n```\n\n### Examples of good commit messages\n\nIf you are unsure about the commit message standard, run:\n\n```sh\ncz example\n```\n\nThis will bring up a complete example of good commit messages and commit schema in the terminal.\n\n---\n\n## Configuration\n\nConfig is accepted in `pyproject.toml` (priority, following example), `.cz.toml`, `.cz.json`, `cz.json`, `.cz.yaml`, `cz.yaml`, and `cz.toml`.\n\n### Minimal setup\n\n> \\[!TIP\\]\n> Try to be minimalistic with custom configs. The best approach is to keep the defaults, so all Espressif projects maintain the same look and feel.\n> Also, you will save yourself troubles with non-standard setups.\n\n```ini\n[tool.commitizen]\n name = \"czespressif\"\n bump_message = 'change(bump): release $current_version \u2192 $new_version [skip-ci]'\n```\n\n### Optimal setup\n\n```ini\n[tool.commitizen]\n name = \"czespressif\"\n bump_message = 'change(bump): release $current_version \u2192 $new_version [skip-ci]'\n\n # see commitizen docs, following are standard configs\n annotated_tag = true\n changelog_merge_prerelease = true\n tag_format = \"v$version\"\n update_changelog_on_bump = true\n version = \"1.2.3\"\n version_files = [\"<src>/__init__.py:__version__\"]\n version_provider = \"commitizen\"\n\n```\n\n### Additional configurable parameters\n\n```ini\n[tool.commitizen]\n ...\n\n # - Section emojis in the changelog, emojis in CLI command `cz commit` -\n # Default: true; false = do not display emojis\n # Note: Emojis are never added in the commit messages.\n use_emoji = false\n\n # - Custom text of changelog title -\n # Note: \"\" (empty string) disables title\n changelog_title = \"Our changelog\"\n\n # - Custom text of changelog header -\n # Note: \"\" (empty string) disables header\n changelog_header = \"This is our changelog.\\nAll cool things we do are here.\\n\\nPlease read it.\"\n\n # - Custom text of changelog footer -\n # Note: \"\" (empty string) disables footer\n changelog_footer = \"This is the end of our changelog.\\n\\nMore cool things are coming.\"\n\n # - Horizontal lines between release sections in the changelog -\n # Default: true; false = removes lines\n changelog_section_line = false # default (true); false = removes horizontal lines between releases\n\n # - Section \"Unreleased\" in the changelog -\n # Default: true; false = removes section Unreleased, keeps only releases\n changelog_unreleased = false\n\n # - Authors of the changes (commits) in the changelog -\n # Default: true; false = do not display authors\n changelog_show_authors = false\n\n # - Commit numbers (short SHA) in the changelog -\n # Default: true; false = do not display commit numbers\n changelog_show_commits = false\n\n # - Change orders in which sections displays in the changelog -\n # Default: this example is default\n change_type_order = [ # with enabled emojis\n '\ud83d\udea8 Breaking changes',\n '\u2728 New features',\n '\ud83d\udc1b Bug fixes',\n '\ud83d\udcd6 Documentation',\n '\ud83d\udd27 Code refactoring',\n '\ud83d\uddd1\ufe0f Removals',\n '\ud83c\udfd7\ufe0f Changes', # in default not in the changelog\n '\u2699\ufe0f CI and project settings', # in default not in the changelog\n '\ud83d\udea6 Testing', # in default not in the changelog\n '\ud83d\udd19 Reverted', # in default not in the changelog\n ]\n\n change_type_order = [ # same thing, with disabled emojis\n 'Breaking changes',\n 'New features',\n 'Bug fixes',\n 'Documentation',\n 'Code refactoring',\n 'Removals',\n 'Changes', # in default not in the changelog\n 'CI and project settings', # in default not in the changelog\n 'Testing', # in default not in the changelog\n 'Reverted', # in default not in the changelog\n ]\n\n # - Redefine which types are shown in the changelog -\n # Note: You need to list here ALL types that you want to have in the changelog - included default ones\n # Note: The order in this list doesn't matter \u2014 if you want to change the sections' order too, use with \"change_type_order.\"\n types_in_changelog = [\"feat\", \"fix\", \"refactor\", \"style\", \"ci\"]\n\n\n # - Custom text that you can append to release notes output -\n # Default: Null (in default there is no custom footer )\n release_notes_footer = \"\"\"Thanks to <FILL OUT CONTRIBUTORS>, and others for contributing to this release!\"\"\"\n\n # - Add extra commit types for 'cz commit' and to the changelog (sections) -\n # Note: If you are working with custom commit types, ensure your commit linter and PR/MR linter is set same way\n [[tool.commitizen.extra_types]]\n type = \"style\"\n heading = \"Code Style\"\n emoji = \"\ud83c\udfa8\"\n description = \"Changes that do not affect the meaning of the code (white-space, formatting, etc.)\"\n bump = \"PATCH\"\n changelog = true\n```\n\n---\n\n## Solving Troubles\n\nThe plugin `czespressif` has `commitizen` as its dependency, so users only need to install `czespressif`, and that will automatically install the proper version of `commitizen`. This plugin requires at least version 3.29 of `commitizen` to work properly. Older versions either cause errors like this:\n\n```log\nThe committer has not been found in the system.\n\nTry running 'pip install czespressif'\n```\n\n... or `czespressif` plugin partially works but behaves in weird and unexpected ways.\n\nIf you encounter this error, it probably means that you have a conflicting version of commitizen installed on your system, and this old version is prioritized in your system path.\n\nYou can copy and paste this snippet into your terminal to check if this is the case:\n\n```sh\nclear;if command -v cz &> /dev/null; then\n cz_version=$(cz version | awk '{print $NF}')\n if [ \"$(printf '%s\\n' \"3.29\" \"$cz_version\" | sort -V | head -n1)\" = \"3.29\" ]; then\n echo \"Commitizen version $cz_version is OK.\"\n else\n echo \"Commitizen version $cz_version is too old. Found at $(which cz).\"\n echo \"Please uninstall it with 'pip uninstall commitizen' or 'pipx uninstall commitizen'.\"\n fi\nelse\n echo \"No Commitizen found, but you are not in a virtual environment.\"\n echo \"Consider creating/activating a virtual environment first and installing by 'pip install czespressif'.\"\nfi\n```\n\n> \\[!TIP\\]\n> For each Python project, use a virtual environment. If you install everything with pip to the system Python, you risk running into unsolvable dependency issues and possibly breaking some system tools.\n>\n> If your project isn\u2019t a Python project and you don\u2019t care about python virtual envs, at least ensure you don\u2019t have multiple outdated versions of some Python packages, such as commitizen in this case.\n\n---\n\n## Pre-commit hook (beta)\n\nTo automatically keep your changelog's \"Unreleased\" section up to date, add the following to your `.pre-commit-config.yaml` file:\n\n```yaml\n- repo: https://github.com/espressif/cz-plugin-espressif\n rev: ''\n hooks:\n - id: update-changelog\n```\n\nNext, run the following command to fetch the latest version (`rev:`):\n\n```sh\npre-commit autoupdate --repo https://github.com/espressif/cz-plugin-espressif\n```\n\nIf you have already set `default_install_hook_types`, then include `pre-push` in the list. Otherwise, add the following to your `.pre-commit-config.yaml` file:\n\n```yaml\ndefault_install_hook_types: [pre-commit, pre-push]\n```\n\nAfter installing the hook, it runs automatically before you pushing commits to the repository. It updates the changelog with the latest commits. If the push failed because of the hook, don't forget to add the updated changelog to the commit and push again.\n\n---\n\n## Contributing\n\nWe welcome contributions from the community! Please read the [Contributing Guide](CONTRIBUTING.md) to learn how to get involved.\n\n---\n\n## License\n\nThis PROJECT is licensed under the [Apache 2.0 License](LICENSE).\n\n---\n\n## Credits\n\nThis was inspired by the project [Emotional](https://github.com/noirbizarre/emotional), created by [Axel H. / @noirbizarre](https://github.com/noirbizarre).\n\n- If you are looking for **similar and customizable plugin for projects outside Espressif** organization, you should definitely try [Emotional](https://github.com/noirbizarre/emotional).\n\n- If you are learning Python and want to write clean and well-organized, pro-level code, you should definitely check out [Emotional](https://github.com/noirbizarre/emotional).\n\n---\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Commitizen plugin with Espressif code style",
"version": "1.3.0",
"project_urls": {
"Changelog": "https://github.com/espressif/cz-plugin-espressif/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/espressif/cz-plugin-espressif/",
"Source": "https://github.com/espressif/cz-plugin-espressif/",
"Tracker": "https://github.com/espressif/cz-plugin-espressif/issues/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f633762d7d53d16189b6ca684e8fcc45c65ee7b88d1b3b38fa8ba6cd4c6ca1e9",
"md5": "13d7d08dce8f51982f6b02befe6d0a2c",
"sha256": "a3ce08c2476d73e4a5ed205bc16647df50d2e2eb505ccd0bdb11a81dece507fe"
},
"downloads": -1,
"filename": "czespressif-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "13d7d08dce8f51982f6b02befe6d0a2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 28915,
"upload_time": "2024-10-07T12:55:05",
"upload_time_iso_8601": "2024-10-07T12:55:05.890718Z",
"url": "https://files.pythonhosted.org/packages/f6/33/762d7d53d16189b6ca684e8fcc45c65ee7b88d1b3b38fa8ba6cd4c6ca1e9/czespressif-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2fe31e09a2438c8721c556854c18365c7f299b30b3256ef1369819a2312a5f50",
"md5": "c2a657609b645958d8b5d0d4519086f5",
"sha256": "cd910f5c37f47275d014a14120d9e4be1279aee731040a50c8f05e52f9275cab"
},
"downloads": -1,
"filename": "czespressif-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "c2a657609b645958d8b5d0d4519086f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 32622,
"upload_time": "2024-10-07T12:55:07",
"upload_time_iso_8601": "2024-10-07T12:55:07.773982Z",
"url": "https://files.pythonhosted.org/packages/2f/e3/1e09a2438c8721c556854c18365c7f299b30b3256ef1369819a2312a5f50/czespressif-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 12:55:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "espressif",
"github_project": "cz-plugin-espressif",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "argcomplete",
"specs": [
[
"==",
"3.5.0"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.3.2"
]
]
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.6"
]
]
},
{
"name": "commitizen",
"specs": [
[
"==",
"3.29.0"
]
]
},
{
"name": "decli",
"specs": [
[
"==",
"0.6.2"
]
]
},
{
"name": "importlib-metadata",
"specs": [
[
"==",
"8.4.0"
]
]
},
{
"name": "jinja2",
"specs": [
[
"==",
"3.1.4"
]
]
},
{
"name": "markupsafe",
"specs": [
[
"==",
"2.1.5"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.1"
]
]
},
{
"name": "prompt-toolkit",
"specs": [
[
"==",
"3.0.36"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "questionary",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "termcolor",
"specs": [
[
"==",
"2.4.0"
]
]
},
{
"name": "tomlkit",
"specs": [
[
"==",
"0.13.2"
]
]
},
{
"name": "wcwidth",
"specs": [
[
"==",
"0.2.13"
]
]
},
{
"name": "zipp",
"specs": [
[
"==",
"3.20.1"
]
]
}
],
"lcname": "czespressif"
}
JSON
