Package: protokolo
ProtokoloProtokolo is a change log generator.Protokolo allows you to maintain your change log entries in separate files, and
then finally aggregate them into a new section in CHANGELOG just before release.Table of ContentsBackgroundInstallUsageMaintainersContributingLicenseBackgroundChange logs area really good idea.
Unfortunately, they are also a bit of a pain when combined with version control:If two pull requests edit CHANGELOG, there is a non-zero chance that you'll
need to resolve a conflict when trying to merge them both.Just after you make a release, you need to create a new section in CHANGELOG
for your next release. If you forget this busywork, new feature branches will
need to create this section, which increases the chance of merge conflicts.If a feature branch adds a change log entry to the section for the next v1.2.3
release, and v1.2.3 subsequently releases without merging that feature branch,
then merging that feature branch afterwards would still add the change log
entry to the v1.2.3 section, even though it should now go to the v1.3.0
section.Life would be a lot easier if you didn't have to deal with these problems.Enter Protokolo. The idea is very simple: For every change log entry, create a
new file. Finally, just before release, compile the contents of those files into
a new section in CHANGELOG, and delete the files.InstallProtokolo is a regular Python package. You can install it usingpipx install protokolo. Make sure that~/.local/share/binis in your$PATHwithpipx ensurepath.UsageTo set up your project for use with Protokolo, runprotokolo init. This will
create aCHANGELOG.mdfile (if one did not already exist) and a directory
structure underchangelog.d. The directory structure uses theKeep a Changelogsections, and ends up looking
like this:.
├── changelog.d
│   ├── added
│   │   └── .protokolo.toml
│   ├── changed
│   │   └── .protokolo.toml
│   ├── deprecated
│   │   └── .protokolo.toml
│   ├── fixed
│   │   └── .protokolo.toml
│   ├── removed
│   │   └── .protokolo.toml
│   ├── security
│   │   └── .protokolo.toml
│   └── .protokolo.toml
└── CHANGELOG.mdThe.protokolo.tomlfiles contain metadata for their respective sections; the
section title, header level, and order. Their inclusion is mandatory.To add a change log entry, create the filechangelog.d/added/my_feature.md,
and write something like:-Added`--my-new-feature`option.Note the item dash at the start; Protokolo does not add them for you. What you
write is exactly what you get.You can add more files. Change log entries in the same section (read: directory)
are sorted alphabetically by their file name. If you want to make certain that
some change log entries go first or last, prefix the file with000_orzzz_.
For example, you can createchangelog.d/added/000_important_feature.mdto make
it appear first.Finally, compile your change log withprotokolo compile --changelog CHANGELOG.md changelog.d. This will take all
change log entries fromchangelog.dand put them in yourCHANGELOG.md. If we
run it now, the following section is added after the<!-- protokolo-section-tag -->comment:## ${version} - 2023-11-08### Added-Added important feature.-Added`--my-new-feature`option.The Markdown files inchangelog.d/added/are deleted. You can manually replace${version}with a release version, or you can pass the option--format version=1.0.0toprotokolo compileto format the header at compile
time (TODO: not implemented yet).For more documentation and options, read the documentation at TODO.MaintainersCarmen Bianca BAKKERcarmen@carmenbianca.euContributingThe code and issue tracker is hosted athttps://codeberg.org/carmenbianca/protokolo. You are welcome to open any
issues. For pull requests, bug fixes are always welcome, but new features should
probably be discussed in any issue first.LicenseAll code is licensed under GPL-3.0-or-later.All documentation is licensed under CC-BY-SA-4.0 OR GPL-3.0-or-later.Some configuration files are licensed under CC0-1.0 OR GPL-3.0-or-later.The repository isREUSE-compliant. Check the
individual files for their exact licensing.