# Changelogger
[](https://github.com/award28/changelogger/actions/workflows/continuous_deployment.yml)
[](https://github.com/award28/changelogger/actions/workflows/continuous_integration.yml)
[](https://codecov.io/gh/award28/changelogger)
[](https://github.com/pre-commit/pre-commit)
[](https://pypi.org/project/changelogged/)
[](https://pepy.tech/project/changelogged)
[](https://pypi.org/project/changelogged/)
[](https://github.com/users/award28/projects/2)
Automated management of your CHANGELOG.md and other versioned files, following
the principles of [Keep a Changelog](https://keepachangelog.com) and
[Semantic Versioning](https://semver.org).
This project uses [Jinja](https://jinja.palletsprojects.com/) for simple yet
powerful templating and regular expressions for pattern matching. To learn more
about this, checkout the [`.changelogger.yml` Syntax](#changelogger-syntax)
section. The next section will go over how this works, and you can use
changelogger to help manage your versioned files.
## Motivation
With any software that is versioned, it is typically necessary to include the
version number in more than one file. In addition to the version changes, there
is also a need for certain projects to include their changelog contents in
multiple locations. **Maintaining these files by hand is tedious and error prone.**
By automating the upgrade of each of these files, we can reduce the risk of
out-of-sync files, validate these changes in our CI/CD pipelines, and save
ourselves some time.
## Installation
```
pip install changelogged
```
## Usage
Run `changelog [SUBCOMMANDS] --help` to understand the usage for any command.
```
❯ changelogger --help
Usage: changelogger [OPTIONS] COMMAND [ARGS]...
Automated management of your CHANGELOG.md and other versioned files, following the principles
of Keep a Changelog and Semantic Versioning.
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy it or customize │
│ the installation. │
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ────────────────────────────────────────────────────────────────────────────────────╮
│ manage Management commands for changelog and other versioned files, as specified in the │
│ changelogger config file. │
│ unreleased Commands for the unreleased section of the changelog. │
╰───────────────────────────────────────────────────────────────────────────────────────────────╯
```
## Introduction
The `.changelogger.yml` configuration file allows you to customize what files
are versioned and maintained by Changelogger. Let's say you have a `pyproject.toml`
file which is versioned in addition to your `CHANGELOG.md` file. You would add the
`.changelogger.yml` file to the root of your project, with the following configuration.
```yml
versioned_files:
- rel_path: "pyproject.toml"
pattern: 'version = "{{ old_version }}"'
jinja: 'version = "{{ new_version }}"'
```
In fact, that's the exact configuration used by this project! Let's breakdown
what each line means.
##### `versioned_files:`
This line lets Changelogger know that you have a list of files you would like
Changelogger to maintain. This list can be one or more, but if it doesn't exist,
Changelogger will only manage the `CHANGELOG.md` file.
##### `- rel_path: "pyproject.toml"`
The `-` is the start of a new versioned file section; it's unimportant that this
is on the `rel_path` field, but is important that this section is separated from
other versioned files, and that all other related fields are below the `-`'d field.
The `rel_path` lets Changelogger know that there is a file in the path, relative
to the `.changelogger.yml` file, that you would like Changelogger to maintain the
version in said file. In this case, the `pyproject.toml` file is at the root of
this project, so all we need is that name.
**Note** that you can list a file multiple times within the configuration file;
this can reduce the complexity of pattern matching while keeping all versioned
sections of a file in-sync.
##### `pattern: 'version = "{{ old_version }}"'`
The `pattern` field lets Changelogger know how to find the versioned segment in
this file. The `pattern` field supports Python's flavor of regular expressions,
as well as the use of Jinja with pre-determined variables. More on these can be
found [below](#jinja-variables). The combination of these two allow for a strong
yet simple pattern matching interface.
##### `jinja: 'version = "{{ new_version }}"'`
The `jinja` field is used as a jinja template to replace the matched pattern.
The same rendered variables which are available for the `pattern` field can
be utilized by this field.
Further, using standard yaml, you can create a multiline jinja to replace the
matched pattern. For instance, if our release also came with a release date,
we could use the following `.changelogger.yml` file to manage the required
changes.
```yml
versioned_files:
- rel_path: "pyproject.toml"
pattern: 'version = "{{ old_version }}"\nrelease_date = "\d+-\d+-\d+"'
jinja: |
version = "{{ new_version }}"
release_date = "{{ today }}"
```
While this approach is great for a simple use case like the one above, it
falls short for more complex jinja templates. To help deal with this
limitation, the `template` field can be used. This allows us to move
our code to a jinja file and reference said file relative to the
`.changelogger.yml` file.
*.changelogger.yml*
```yml
versioned_files:
- rel_path: "pyproject.toml"
pattern: 'version = "{{ old_version }}"\nrelease_date = "\d+-\d+-\d+"'
jinja: |
version = "{{ new_version }}"
release_date = "{{ today }}"
```
*.pyproject.toml.jinja2*
```jinja
version = "{{ new_version }}"
release_date = "{{ today }}"
```
Now we have our multiline Jinja outside of our configuration file and, with
the right IDE support, we can get Jinja syntax highlighting. Examples of Jinja
templates used by this project can be found in the [`templates`](../changelogger/templates)
directory.
---
With that, we now understand how the Changelogger configuration file works.
Now all you need to do is let Changelogger do the heavy lifting for any
upgrade with the `manage upgrade`. Make sure to explore what commands are
available by using the `changelogger --help` command!
## `.changelogger.yml` Syntax
This section reviews all available configuration sections of the Changelogger
configuration file. For a more streamlined introduction, review the
[introduction](#introduction) section. The
[JSON Schema Core](https://json-schema.org/latest/json-schema-core.html)
compliant schema can be found in the
[config.schema.json](../config.schema.json) file.
The `changelog` field is used for managing and updating the `CHANGELOG.md`.
If your project doesn't follow the standard changelog file format prescribed
by Changelogger, you will need to upate this section. **Note** that the changelog
section requires both the overview and links sub sections be provided. However,
if there are other versioned changes you would like to require Changelogger manage
on your behalf, you can add those to the `versioned_files` section.
*Example File with All Required Fields*
```yml
changelog:
rel_path: "CHANGELOG.md"
overview:
pattern: '### \[Unreleased\]([\s\S]*)### \[{{ old_version }}]'
template: ./templates/.cl.overview.jinja2
links:
pattern: '\[Unreleased\]:.*\n'
template: ./templates/.cl.links.jinja2
versioned_files:
- rel_path: "pyproject.toml"
pattern: 'version = "{{ old_version }}"'
jinja: 'version = "{{ new_version }}"'
```
# Jinja Variables
The following is an overview of the jinja variables available in the `pattern`
field and the `jinja` templating for managed replacement.
## `new_version`: string
The new version after the requested semantic version bump type has been applied.
### Example
*.some.jinja2*
```jinja
New Version: {{ new_version }}
```
## `old_version`: string
The current version of the project, which the requested semantic version bump type
will be applied on.
### Example
*.some.jinja2*
```jinja
Old Version: {{ old_version }}
```
## `today`: datetime.date
A [datetime.date](https://docs.python.org/3/library/datetime.html#date-objects)
object with today's date.
### Example
*.some.jinja2*
```jinja
Todays Date: {{ today }}
```
## `sections`: dict[str, list[str]]
A map from each section of the Keep a Changelog standard to the notes included for
that section.
### Example
*.some.jinja2*
```jinja
{% for name, notes in sections.items() -%}
{% if notes -%}
#### {{ name.title() }}
{% for note in notes -%}
- {{ note }}
{% endfor %}
{% endif %}
{%- endfor -%}
```
## `context`: dict[str, Any]
User specified context in the `.changelogger.yml` configuration file, available in
both the pattern and jinja through dot notation.
### Example
*.changelogger.yml*
```yml
versioned_files:
- rel_path: "pyproject.toml"
pattern: 'version = "{{ old_version }}"'
template: '.pyproject.toml.jinja2'
context:
git:
org: award28
repo: changelogger
```
*.pyproject.toml.jinja2*
```jinja
org: {{ context.git.org }}
repo: {{ context.git.repo }}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/award28/changelogger",
"name": "changelogged",
"maintainer": "award28",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "austin.ward@klaviyo.com",
"keywords": "changelog,version,semver,changelogger,changelogged",
"author": "award28",
"author_email": "austin.ward@klaviyo.com",
"download_url": "https://files.pythonhosted.org/packages/1b/20/f9f90f756c9c21eab466eade46164443e6d725c3c05b5b1165e5b676feb2/changelogged-0.13.0.tar.gz",
"platform": null,
"description": "# Changelogger\n\n[](https://github.com/award28/changelogger/actions/workflows/continuous_deployment.yml)\n[](https://github.com/award28/changelogger/actions/workflows/continuous_integration.yml)\n[](https://codecov.io/gh/award28/changelogger)\n[](https://github.com/pre-commit/pre-commit)\n[](https://pypi.org/project/changelogged/)\n[](https://pepy.tech/project/changelogged)\n[](https://pypi.org/project/changelogged/)\n[](https://github.com/users/award28/projects/2)\n\nAutomated management of your CHANGELOG.md and other versioned files, following\nthe principles of [Keep a Changelog](https://keepachangelog.com) and\n[Semantic Versioning](https://semver.org).\n\n\nThis project uses [Jinja](https://jinja.palletsprojects.com/) for simple yet\npowerful templating and regular expressions for pattern matching. To learn more\nabout this, checkout the [`.changelogger.yml` Syntax](#changelogger-syntax)\nsection. The next section will go over how this works, and you can use\nchangelogger to help manage your versioned files.\n\n## Motivation\n\nWith any software that is versioned, it is typically necessary to include the\nversion number in more than one file. In addition to the version changes, there\nis also a need for certain projects to include their changelog contents in\nmultiple locations. **Maintaining these files by hand is tedious and error prone.**\n\nBy automating the upgrade of each of these files, we can reduce the risk of\nout-of-sync files, validate these changes in our CI/CD pipelines, and save\nourselves some time.\n\n## Installation\n\n```\npip install changelogged\n```\n\n## Usage\n\nRun `changelog [SUBCOMMANDS] --help` to understand the usage for any command.\n\n```\n\u276f changelogger --help\n\n Usage: changelogger [OPTIONS] COMMAND [ARGS]...\n\n Automated management of your CHANGELOG.md and other versioned files, following the principles\n of Keep a Changelog and Semantic Versioning.\n\n\u256d\u2500 Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 --install-completion Install completion for the current shell. \u2502\n\u2502 --show-completion Show completion for the current shell, to copy it or customize \u2502\n\u2502 the installation. \u2502\n\u2502 --help Show this message and exit. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\u256d\u2500 Commands \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 manage Management commands for changelog and other versioned files, as specified in the \u2502\n\u2502 changelogger config file. \u2502\n\u2502 unreleased Commands for the unreleased section of the changelog. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\n## Introduction\n\nThe `.changelogger.yml` configuration file allows you to customize what files\nare versioned and maintained by Changelogger. Let's say you have a `pyproject.toml`\nfile which is versioned in addition to your `CHANGELOG.md` file. You would add the\n`.changelogger.yml` file to the root of your project, with the following configuration.\n\n```yml\nversioned_files:\n - rel_path: \"pyproject.toml\"\n pattern: 'version = \"{{ old_version }}\"'\n jinja: 'version = \"{{ new_version }}\"'\n```\n\nIn fact, that's the exact configuration used by this project! Let's breakdown\nwhat each line means.\n\n##### `versioned_files:`\nThis line lets Changelogger know that you have a list of files you would like\nChangelogger to maintain. This list can be one or more, but if it doesn't exist,\nChangelogger will only manage the `CHANGELOG.md` file.\n\n##### `- rel_path: \"pyproject.toml\"`\nThe `-` is the start of a new versioned file section; it's unimportant that this\nis on the `rel_path` field, but is important that this section is separated from\nother versioned files, and that all other related fields are below the `-`'d field.\n\nThe `rel_path` lets Changelogger know that there is a file in the path, relative\nto the `.changelogger.yml` file, that you would like Changelogger to maintain the\nversion in said file. In this case, the `pyproject.toml` file is at the root of\nthis project, so all we need is that name.\n\n**Note** that you can list a file multiple times within the configuration file;\nthis can reduce the complexity of pattern matching while keeping all versioned\nsections of a file in-sync.\n\n##### `pattern: 'version = \"{{ old_version }}\"'`\nThe `pattern` field lets Changelogger know how to find the versioned segment in\nthis file. The `pattern` field supports Python's flavor of regular expressions,\nas well as the use of Jinja with pre-determined variables. More on these can be\nfound [below](#jinja-variables). The combination of these two allow for a strong\nyet simple pattern matching interface.\n\n##### `jinja: 'version = \"{{ new_version }}\"'`\nThe `jinja` field is used as a jinja template to replace the matched pattern.\nThe same rendered variables which are available for the `pattern` field can\nbe utilized by this field.\n\nFurther, using standard yaml, you can create a multiline jinja to replace the\nmatched pattern. For instance, if our release also came with a release date,\nwe could use the following `.changelogger.yml` file to manage the required\nchanges.\n\n```yml\nversioned_files:\n - rel_path: \"pyproject.toml\"\n pattern: 'version = \"{{ old_version }}\"\\nrelease_date = \"\\d+-\\d+-\\d+\"'\n jinja: |\n version = \"{{ new_version }}\"\n release_date = \"{{ today }}\"\n```\n\nWhile this approach is great for a simple use case like the one above, it\nfalls short for more complex jinja templates. To help deal with this\nlimitation, the `template` field can be used. This allows us to move\nour code to a jinja file and reference said file relative to the\n`.changelogger.yml` file.\n\n*.changelogger.yml*\n```yml\nversioned_files:\n - rel_path: \"pyproject.toml\"\n pattern: 'version = \"{{ old_version }}\"\\nrelease_date = \"\\d+-\\d+-\\d+\"'\n jinja: |\n version = \"{{ new_version }}\"\n release_date = \"{{ today }}\"\n```\n\n*.pyproject.toml.jinja2*\n```jinja\nversion = \"{{ new_version }}\"\nrelease_date = \"{{ today }}\"\n```\n\nNow we have our multiline Jinja outside of our configuration file and, with\nthe right IDE support, we can get Jinja syntax highlighting. Examples of Jinja\ntemplates used by this project can be found in the [`templates`](../changelogger/templates)\ndirectory.\n\n---\n\nWith that, we now understand how the Changelogger configuration file works.\nNow all you need to do is let Changelogger do the heavy lifting for any\nupgrade with the `manage upgrade`. Make sure to explore what commands are\navailable by using the `changelogger --help` command!\n\n## `.changelogger.yml` Syntax\n\nThis section reviews all available configuration sections of the Changelogger\nconfiguration file. For a more streamlined introduction, review the\n[introduction](#introduction) section. The\n[JSON Schema Core](https://json-schema.org/latest/json-schema-core.html)\ncompliant schema can be found in the\n[config.schema.json](../config.schema.json) file.\n\n\nThe `changelog` field is used for managing and updating the `CHANGELOG.md`.\nIf your project doesn't follow the standard changelog file format prescribed\nby Changelogger, you will need to upate this section. **Note** that the changelog\nsection requires both the overview and links sub sections be provided. However,\nif there are other versioned changes you would like to require Changelogger manage\non your behalf, you can add those to the `versioned_files` section.\n\n*Example File with All Required Fields*\n```yml\nchangelog:\n rel_path: \"CHANGELOG.md\"\n overview:\n pattern: '### \\[Unreleased\\]([\\s\\S]*)### \\[{{ old_version }}]'\n template: ./templates/.cl.overview.jinja2\n links:\n pattern: '\\[Unreleased\\]:.*\\n'\n template: ./templates/.cl.links.jinja2\n\nversioned_files:\n - rel_path: \"pyproject.toml\"\n pattern: 'version = \"{{ old_version }}\"'\n jinja: 'version = \"{{ new_version }}\"'\n```\n\n\n# Jinja Variables\nThe following is an overview of the jinja variables available in the `pattern`\nfield and the `jinja` templating for managed replacement.\n\n## `new_version`: string\n\nThe new version after the requested semantic version bump type has been applied.\n\n### Example\n\n*.some.jinja2*\n```jinja\nNew Version: {{ new_version }}\n```\n\n## `old_version`: string\n\nThe current version of the project, which the requested semantic version bump type\nwill be applied on.\n\n### Example\n\n*.some.jinja2*\n```jinja\nOld Version: {{ old_version }}\n```\n\n## `today`: datetime.date\n\nA [datetime.date](https://docs.python.org/3/library/datetime.html#date-objects)\nobject with today's date.\n\n### Example\n\n*.some.jinja2*\n```jinja\nTodays Date: {{ today }}\n```\n\n## `sections`: dict[str, list[str]]\n\nA map from each section of the Keep a Changelog standard to the notes included for\nthat section.\n\n### Example\n\n*.some.jinja2*\n```jinja\n{% for name, notes in sections.items() -%}\n{% if notes -%}\n#### {{ name.title() }}\n{% for note in notes -%}\n- {{ note }}\n{% endfor %}\n{% endif %}\n\n{%- endfor -%}\n```\n## `context`: dict[str, Any]\n\nUser specified context in the `.changelogger.yml` configuration file, available in\nboth the pattern and jinja through dot notation.\n\n### Example\n\n*.changelogger.yml*\n```yml\nversioned_files:\n - rel_path: \"pyproject.toml\"\n pattern: 'version = \"{{ old_version }}\"'\n template: '.pyproject.toml.jinja2'\n context:\n git:\n org: award28\n repo: changelogger\n```\n\n*.pyproject.toml.jinja2*\n```jinja\norg: {{ context.git.org }}\nrepo: {{ context.git.repo }}\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automated management of your changelog and other versioned files, following the principles of Keep a Changelog and Semantic Versioning.",
"version": "0.13.0",
"project_urls": {
"Bug Tracker": "https://github.com/award28/changelogger/issues",
"Changelog": "https://github.com/award28/changelogger/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/award28/changelogger",
"Repository": "https://github.com/award28/changelogger",
"Road Map": "https://github.com/users/award28/projects/2"
},
"split_keywords": [
"changelog",
"version",
"semver",
"changelogger",
"changelogged"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6d11688e76e4bf4dcc3bac57df92869440ea79c1770e28b7cd33ffca805a69dc",
"md5": "792e2c477dd2464e1eb01ec24030e3d4",
"sha256": "a3472b2bd976c1a8255d13a5b9464b860f93e1fdc4579a4907402b5f5ceae87e"
},
"downloads": -1,
"filename": "changelogged-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "792e2c477dd2464e1eb01ec24030e3d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 24650,
"upload_time": "2023-07-05T19:04:00",
"upload_time_iso_8601": "2023-07-05T19:04:00.975801Z",
"url": "https://files.pythonhosted.org/packages/6d/11/688e76e4bf4dcc3bac57df92869440ea79c1770e28b7cd33ffca805a69dc/changelogged-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1b20f9f90f756c9c21eab466eade46164443e6d725c3c05b5b1165e5b676feb2",
"md5": "743adf1b939728fe90b31d788200da09",
"sha256": "95163d1fdd232a907354a9115effec97525e9a8adf32fd2c020b1f1aa7a50467"
},
"downloads": -1,
"filename": "changelogged-0.13.0.tar.gz",
"has_sig": false,
"md5_digest": "743adf1b939728fe90b31d788200da09",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 16338,
"upload_time": "2023-07-05T19:04:02",
"upload_time_iso_8601": "2023-07-05T19:04:02.695466Z",
"url": "https://files.pythonhosted.org/packages/1b/20/f9f90f756c9c21eab466eade46164443e6d725c3c05b5b1165e5b676feb2/changelogged-0.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-05 19:04:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "award28",
"github_project": "changelogger",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "changelogged"
}
JSON
