Skip to main content

Tool for managing changelogs

Project description

JMESLog - Changelog Management

PyPI PyPI - Python Version PyPI - License


Source Code: https://github.com/jamesls/jmeslog PyPI: https://pypi-hypernode.com/project/jmeslog/


JMESLog is a script for managing changelogs. It helps you associate changelog entries for new features and bug fixes and also helps you generate a CHANGELOG file or any other type of release notes page. It enforces semver by automatically determining the next version number based on the pending changes for your next release.

Installation

pip install jmeslog

Quickstart

Initialize a repo to use JMESLog:

$ jmeslog init

Before you send a PR, create a changelog entry for your change:

$ jmeslog new-change

A change file was created at .changes/next-release/foo-bar.json

Commit that file:

$ git add .changes/next-release/foo-bar.json
$ git commit -m "Add changelog entry"

That's it. When it comes time to release, you run these commands:

$ jmeslog new-release
$ jmeslog render > CHANGELOG.rst

The new-release command consolidates all the files in .changes/next-release into a single JSON file representing the new release. The render command regenerates your CHANGELOG file.

The rest of this doc explains this workflow in more detail.

Concepts

All changes for a repo are stored as structured data in a .changes/ directory.

The changes for the next release are stored in .changes/next-release/. All of the changes from previous releases are stored in .changes/X.Y.Z.json where X.Y.Z represent the version associated a given release. These files are generated by running the jmeslog new-change command.

When you're ready to release a new version, all of the change files from .changes/next-release/ are gathered and a new .changes/X.Y.Z.json file is created that contain those changes. The content from .changes/next-release/ is then removed. This is done with the jmeslog new-release command.

You can then generate a CHANGELOG (or any other file) using the data from .changes/. To do this you run the jmeslog generate command.

Usage

The typical workflow when using jmeslog:

  • Use the jmeslog new-change command to generate a new changelog file when you're working on a new feature. This file is included as part of the PR you send.
  • When you're ready to release, you can run the jmespath generate command to generate the CHANGELOG file based on all your change files. You also run the jmeslog new-release command to consolidate files from the next .changes/next-release/ directory into a new single .changes/X.Y.Z.json file.

Rendering Changelogs

By default, the jmeslog render command renders a CHANGELOG file in RST format with this structure:

=========
CHANGELOG
=========

X.Y.Z
=====

* type:category:description

You can control how your changes are rendered by specifying your own template. To specify your own templates, first create a .changes/templates directory:

mkdir .changes/templates

Next create any number of templates you want. For example:

touch .changes/templates/MYTEMPLATE

This name can be anything you want. Next, you write your template. Templates are written using jinja2.

The template is provided the following context dictionary when rendering the changelog:

{
  "changes": [
    ("x.y.z": [{"type": "", "category": "", "description": ""}, ...]),
    ("x.y.z - 1": [{"type": "", "category": "", "description": ""}, ...]),
    ("x.y.z - 2": [{"type": "", "category": "", "description": ""}, ...]),
  ]
}

The changes list is in descender order with the most recent release being first, and the oldest release being the last item in the changes list.

To use this template, specify the filename (the basename, not the entire filename) as the --template parameter. For example, if your template file is .changes/templates/MYTEMPLATE, you'd specify jmeslog render --template MYTEMPLATE.

Here's the default template that's used if no --template parameter is provided:

=========
CHANGELOG
=========

{% for release, changes in releases %}
{{ release }}
{{ '=' * release|length }}
{% if changes.summary %}
{{ changes.summary -}}
{% endif %}
{% for change in changes.changes %}
* {{ change.type }}:{{ change.category }}:{{ change.description }}
{% endfor %}
{% endfor %}

Backwards Compatibility

The following things may change in a backwards incompatible manner until the 1.0.0 GA release:

  • The CLI commands and parameters
  • The files generates under .changes/
  • The functionality provided by JMESLog
  • The context dictionary provided to custom templates

FAQ

What problem is this trying to solve?

JMESLog helps you automate releases. It's the result of iterating on an automated release process that started from a completely manual process to eventually releasing every single day. When you think about what's involved in releasing a new version of your library/tool, you have to:

  • Figure out the next version number you want for your release. If you're following semver, this will depend on what types of changes will be in the next release. New features should require a minor version bump, and bug fixes should result in a new patch version.
  • Update your CHANGELOG with all the new changes that will be part of this next release under a new section corresponding to the next version number.

This tool helps with manage both of these problems so you can completely automate your release process. It also solves several other problems that come up:

  • You can have changelog entries tracked with each pull request, and you don't have to worry about merge conflicts to your CHANGELOG file.
  • You can generate more than just a CHANGELOG file if needed. For example, you can create a "History" page in your docs that's rendered differently than your CHANGELOG.
  • You can programatically query for a projects changes.

Development

This project requires at Python 3.9+ and uses Poetry to manage dependencies.

Once you've created and activated your virtual environment, run:

poetry install

This will install all necessary dependencies and install this project in editable mode.

Testing

Poe the Poet is the task runner used for this project, it's automatically installed as part of the poetry install step. To see a list of available tasks, run the poe command with no args.

To run the tests for this project run:

poe test

Pre-commit

Pre-commit hooks runs misc. auto-formatters and quality checks to ensure all changes look good before committing. The same changes are also run on Pull Requests so this helps provides a quicker feedback loop before submitting a PR.

You can install the hooks with (runs for each commit):

pre-commit install

Or if you want e.g. want to run all checks manually for all files:

poe pre-commit

Or if you run to the pre-commit executable directly:

pre-commit run --all-files

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jmeslog-0.2.0.tar.gz (16.5 kB view details)

Uploaded Source

Built Distribution

jmeslog-0.2.0-py3-none-any.whl (15.9 kB view details)

Uploaded Python 3

File details

Details for the file jmeslog-0.2.0.tar.gz.

File metadata

  • Download URL: jmeslog-0.2.0.tar.gz
  • Upload date:
  • Size: 16.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for jmeslog-0.2.0.tar.gz
Algorithm Hash digest
SHA256 4cab43a8ce3469ac878ba58cb8493d5317200c85b92a85189a2554b859d5533f
MD5 84f459df9a0d64abd426adb39997ed97
BLAKE2b-256 272b38adf3f4a2193ba38d02d25e42fddfc70864203c9ca047eddd03d61120e0

See more details on using hashes here.

File details

Details for the file jmeslog-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: jmeslog-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 15.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for jmeslog-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 373569fc0ae86396466ab9b443e6558bf1bc9b6207dff307e79c214ef4727b96
MD5 5b937482551a174cee6dbad4cef649a8
BLAKE2b-256 1423e8da029c40c6288ff06d6404be467286bed9e5b4cd8e93e54d08a5240d93

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page