Package: chlog
chlogTL;DRMaintains changelog files in Markdown format.Does not overwrite your manual edits.Helps you comply withSemantic Versioning.Adheres toKeep a Changelogby default.Can be configured to support other changelog templates.UsageWhen you commit a (set of) software modification(s) that users of the project should know about, add a corresponding change note, phrased to be meaningful to the users of the project, to your CHANGELOG.md file. Examples:%chlogadded"Export to PDF."%chlogfixed"File -> Save As no longer overwrites files without a warning."%chlogchanged"Improved the error handling during imports."%chlogchanged--breaking"Configuration files now use the TOML format."%chlogdeprecated"The foobar feature will be removed in v2.0.0."%chlogremoved"INI files are no longer supported."%chlogsecurity"In certain conditions an attacker might discover user data."chlog freezereplaces "## [Unreleased]" with a version number and the current date. It suggests the new version number based on the content of the Unreleased section and the rules ofSemantic Versioning. You can accept or reject that number.chlog freeze 2.0.0applies the version number provided.chlog printrenders the Markdown in the changelog file to the terminal. It's beautiful.Instead of "added", "fixed", "removed", and "freeze", you can say "new", "fix", "rm", and "tag".Using chlog versus maintaining the changelog in an editorThere is no conflict here. Round trips between command line use and manual modifications in a text editor are safe.chlogonly ever changes the Unreleased section of the changelog. It does not even look at what comes before and after it. It is also safe to add, remove, reorder, or rephrase change notes which were added to the Unreleased section via the command line. In rare cases,chlogmight change white space but it will not otherwise overwrite or reformat your work.chlog and changelogs not created by itselfIf your existing changelog already conforms to theKeep a Changelogtemplate,chlogwill simply load it and add change notes to it. If your existing changelog uses a different template,chlogwill be unable to recognize the types of changes that are recorded in it. If, for instance, the changelog says "### New Features" instead of "### Added", change notes created withchlog addedwill appear under "### Added". The imported "### New Features" section will be appended to the end of the Unreleased section. However, you can customize chlog to support your project's changelog template.Customizationchlogcan be adapted to support a variety of projects. This is done via[tool.chlog]tables in TOML files. For example:[tool.chlog]chlog-filename="CHANGELOG.md"determines the file name to use for the changelog. The table array[[tool.chlog.commands]]can be used to redefine existing commands and change note types. For example, projects which use "### New Features" instead of "### Added" include the statement[[tool.chlog.commands]]command="added"heading="New Features"To define an entirely new command and change note type, include something like[[tool.chlog.commands]]command="breaking"heading="Breaking Changes"insert-before=3help="record a breaking change in the changelog"description='''Records breaking changes in the Unreleased section of the changelog.'''in the TOML configuration file. That will allow to issuechlog breaking "A change note."commands and insert a "### Breaking Changes" section into the changelog.To customizechlogin this way, a Python project would add the tool.chlog tables to itspyproject.toml. Other projects usechlog.tomlor.chlog.TODO: Document this in more detail.Planned for the next versionExpand issue numbers in new change notes. For examplechlog fixed "Fixed the line-too-long bug issue#1234."adds- Fixed the line-too-long bug [#1234](<issues-url>/1234).to the changelog. For this to work, the TOML config must specify the issues URL e.g.[project.urls]Issues="https://github.com/myaccount/myproject/issues/"or[tool.chlog.urls]issues="https://github.com/myaccount/myproject/issues/"