Package: changelogged
ChangeloggerAutomated management of your CHANGELOG.md and other versioned files, following
the principles ofKeep a ChangelogandSemantic Versioning.This project usesJinjafor simple yet
powerful templating and regular expressions for pattern matching. To learn more
about this, checkout the.changelogger.ymlSyntaxsection. The next section will go over how this works, and you can use
changelogger to help manage your versioned files.MotivationWith 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.Installationpip install changeloggedUsageRunchangelog [SUBCOMMANDS] --helpto 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.                             │
╰───────────────────────────────────────────────────────────────────────────────────────────────╯IntroductionThe.changelogger.ymlconfiguration file allows you to customize what files
are versioned and maintained by Changelogger. Let's say you have apyproject.tomlfile which is versioned in addition to yourCHANGELOG.mdfile. You would add the.changelogger.ymlfile to the root of your project, with the following configuration.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 theCHANGELOG.mdfile.- rel_path: "pyproject.toml"The-is the start of a new versioned file section; it's unimportant that this
is on therel_pathfield, but is important that this section is separated from
other versioned files, and that all other related fields are below the-'d field.Therel_pathlets Changelogger know that there is a file in the path, relative
to the.changelogger.ymlfile, that you would like Changelogger to maintain the
version in said file. In this case, thepyproject.tomlfile is at the root of
this project, so all we need is that name.Notethat 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 }}"'Thepatternfield lets Changelogger know how to find the versioned segment in
this file. Thepatternfield supports Python's flavor of regular expressions,
as well as the use of Jinja with pre-determined variables. More on these can be
foundbelow. The combination of these two allow for a strong
yet simple pattern matching interface.jinja: 'version = "{{ new_version }}"'Thejinjafield is used as a jinja template to replace the matched pattern.
The same rendered variables which are available for thepatternfield 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.ymlfile to manage the required
changes.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, thetemplatefield can be used. This allows us to move
our code to a jinja file and reference said file relative to the.changelogger.ymlfile..changelogger.ymlversioned_files:
  - rel_path: "pyproject.toml"
    pattern: 'version = "{{ old_version }}"\nrelease_date = "\d+-\d+-\d+"'
    jinja: |
      version = "{{ new_version }}"
      release_date = "{{ today }}".pyproject.toml.jinja2version = "{{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 thetemplatesdirectory.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 themanage upgrade. Make sure to explore what commands are
available by using thechangelogger --helpcommand!.changelogger.ymlSyntaxThis section reviews all available configuration sections of the Changelogger
configuration file. For a more streamlined introduction, review theintroductionsection. TheJSON Schema Corecompliant schema can be found in theconfig.schema.jsonfile.Thechangelogfield is used for managing and updating theCHANGELOG.md.
If your project doesn't follow the standard changelog file format prescribed
by Changelogger, you will need to upate this section.Notethat 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 theversioned_filessection.Example File with All Required Fieldschangelog:
  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 VariablesThe following is an overview of the jinja variables available in thepatternfield and thejinjatemplating for managed replacement.new_version: stringThe new version after the requested semantic version bump type has been applied.Example.some.jinja2New Version:{{new_version}}old_version: stringThe current version of the project, which the requested semantic version bump type
will be applied on.Example.some.jinja2Old Version:{{old_version}}today: datetime.dateAdatetime.dateobject with today's date.Example.some.jinja2Todays 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{%forname,notesinsections.items()-%}{%ifnotes-%}####{{name.title()}}{%fornoteinnotes-%}-{{note}}{%endfor%}{%endif%}{%-endfor-%}context: dict[str, Any]User specified context in the.changelogger.ymlconfiguration file, available in
both the pattern and jinja through dot notation.Example.changelogger.ymlversioned_files:
  - rel_path: "pyproject.toml"
    pattern: 'version = "{{ old_version }}"'
    template: '.pyproject.toml.jinja2'
    context:
      git:
        org: award28
        repo: changelogger.pyproject.toml.jinja2org:{{context.git.org}}repo:{{context.git.repo}}