<!--
SPDX-FileCopyrightText: 2023 Carmen Bianca BAKKER <carmen@carmenbianca.eu>
SPDX-License-Identifier: CC-BY-SA-4.0 OR GPL-3.0-or-later
-->
# Protokolo
[](https://pypi.python.org/pypi/protokolo)
[](https://pypi.python.org/pypi/protokolo)
[](https://api.reuse.software/info/codeberg.org/carmenbianca/protokolo)
[](https://github.com/RichardLitt/standard-readme)
[](https://hosted.weblate.org/engage/protokolo/)
Protokolo is a change log generator.
Protokolo allows you to maintain your change log fragments in separate files,
and then finally aggregate them into a new section in CHANGELOG just before
release.
## Table of contents
- [Background](#background)
- [Install](#install)
- [Usage](#usage)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
- [Licensing](#licensing)
## Background
Change logs are [a really good idea](https://keepachangelog.com/).
Unfortunately, they are also a bit of a pain when combined with version control:
- Different merge requests all edit the same area in CHANGELOG, inevitably
resulting in merge conflicts.
- If a section for an unreleased version does not yet exist in the main branch's
CHANGELOG (typically shortly after release), feature branches must create this
section. If multiple feature branches do this, you get more merge conflicts.
- Old merge requests, when merged, sometimes add their change log entry to the
section of a release that is already published.
Life would be a lot easier if you didn't have to deal with these problems.
Enter Protokolo
([Esperanto for 'report' or 'minutes'](https://vortaro.net/#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.
### See also
[Towncrier](https://github.com/twisted/towncrier) is an older and more widely
used implementation of the same idea. Protokolo is distinct in that it uses a
directory hierarchy instead of putting all metadata in the file name of each
change log fragment. Furthermore, Protokolo does no fancy formatting of
fragments---what you write is what you get.
There are three main problems I encountered in Towncrier that Protokolo attempts
to address:
- When using Towncrier, I would always forget which fragment types are available
to me and had to look them up. These fragment types can also differ per
repository. In Protokolo, the types are always visible because they are
directories.
- Towncrier fragments are sorted by their ID, which is typically an issue or PR
number. This isn't always what I want.
- Because (some) Towncrier workflows put the PR number in the file name as
metadata, I would have to open the PR before I could create the change log
fragment.
A much younger version of me also tried her hand at writing a program like this
in [changelogdir](https://pypi.org/project/changelogdir/).
## Install
Protokolo is a regular Python package
[hosted on PyPI](https://pypi.python.org/pypi/protokolo). You can install it
using `pipx install protokolo`. Make sure that `~/.local/share/bin` is in your
`$PATH` with `pipx ensurepath`.
## Usage
For full documentation and options, read the documentation at
<https://protokolo.readthedocs.io>.
### Initial set-up
To set up your project for use with Protokolo, run `protokolo init`. This will
create a `CHANGELOG.md` file (if one did not already exist) and a directory
structure under `changelog.d`. The directory structure uses the
[Keep a Changelog](https://keepachangelog.com/) sections, 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.md
└── .protokolo.toml
```
The `.protokolo.toml` files in `changelog.d` contain metadata for their
respective sections: the section title, heading level, and order. Their
inclusion is mandatory.
The `.protokolo.toml` file in the root of the project contains configurations
for Protokolo that reduce the amount of typing you need to do when running
commands.
If a `CHANGELOG.md` file already existed, make sure to add a line containing
`<!-- protokolo-section-tag -->` just before the heading of the latest release.
### Adding fragments
To add a change log fragment, create the file `changelog.d/added/my_feature.md`,
and write something like:
```markdown
- Added `--my-new-feature` option.
```
Note the bullet 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 fragments in the same section (read:
directory) are sorted alphabetically by their file name. If you want to make
certain that some change log fragments go first or last, prefix the file with
`000_` or `zzz_`. For example, you can create
`changelog.d/added/000_important_feature.md` to make it appear first.
### Compiling your change log
You compile your change log with `protokolo compile`. This will take all change
log fragments from `changelog.d` and put them in your `CHANGELOG.md`. If we run
it now, the following section is added after the
`<!-- protokolo-section-tag -->` comment:
```markdown
## ${version} - 2023-11-08
### Added
- Added important feature.
- Added `--my-new-feature` option.
```
The Markdown files in `changelog.d/added/` are deleted. You can manually replace
`${version}` with a release version, or you can pass the option
`--format version 1.0.0` to `protokolo compile` to format the heading at compile
time.
## Maintainers
- Carmen Bianca BAKKER <carmen@carmenbianca.eu>
## Contributing
The code and issue tracker is hosted at
<https://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.
Translations are done at
<https://hosted.weblate.org/projects/protokolo/protokolo/> using Weblate. If
there are issues with translation, feel free to open an issue at Codeberg.
## Licensing
All 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 is [REUSE](https://reuse.software)-compliant. Check the
individual files for their exact licensing.
Raw data
{
"_id": null,
"home_page": "https://codeberg.org/carmenbianca/protokolo",
"name": "protokolo",
"maintainer": "Carmen Bianca BAKKER",
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": "carmen@carmenbianca.eu",
"keywords": "changelog, history, news",
"author": "Carmen Bianca BAKKER",
"author_email": "carmen@carmenbianca.eu",
"download_url": "https://files.pythonhosted.org/packages/74/67/e5d635ddf4553ac783709c95f01f0625c993615f98d5c6ac017257d9c780/protokolo-2.1.4.tar.gz",
"platform": null,
"description": "<!--\nSPDX-FileCopyrightText: 2023 Carmen Bianca BAKKER <carmen@carmenbianca.eu>\n\nSPDX-License-Identifier: CC-BY-SA-4.0 OR GPL-3.0-or-later\n-->\n\n# Protokolo\n\n[](https://pypi.python.org/pypi/protokolo)\n[](https://pypi.python.org/pypi/protokolo)\n[](https://api.reuse.software/info/codeberg.org/carmenbianca/protokolo)\n[](https://github.com/RichardLitt/standard-readme)\n[](https://hosted.weblate.org/engage/protokolo/)\n\nProtokolo is a change log generator.\n\nProtokolo allows you to maintain your change log fragments in separate files,\nand then finally aggregate them into a new section in CHANGELOG just before\nrelease.\n\n## Table of contents\n\n- [Background](#background)\n- [Install](#install)\n- [Usage](#usage)\n- [Maintainers](#maintainers)\n- [Contributing](#contributing)\n- [Licensing](#licensing)\n\n## Background\n\nChange logs are [a really good idea](https://keepachangelog.com/).\nUnfortunately, they are also a bit of a pain when combined with version control:\n\n- Different merge requests all edit the same area in CHANGELOG, inevitably\n resulting in merge conflicts.\n- If a section for an unreleased version does not yet exist in the main branch's\n CHANGELOG (typically shortly after release), feature branches must create this\n section. If multiple feature branches do this, you get more merge conflicts.\n- Old merge requests, when merged, sometimes add their change log entry to the\n section of a release that is already published.\n\nLife would be a lot easier if you didn't have to deal with these problems.\n\nEnter Protokolo\n([Esperanto for 'report' or 'minutes'](https://vortaro.net/#protokolo)). The\nidea is very simple: for every change log entry, create a new file. Finally,\njust before release, compile the contents of those files into a new section in\nCHANGELOG, and delete the files.\n\n### See also\n\n[Towncrier](https://github.com/twisted/towncrier) is an older and more widely\nused implementation of the same idea. Protokolo is distinct in that it uses a\ndirectory hierarchy instead of putting all metadata in the file name of each\nchange log fragment. Furthermore, Protokolo does no fancy formatting of\nfragments---what you write is what you get.\n\nThere are three main problems I encountered in Towncrier that Protokolo attempts\nto address:\n\n- When using Towncrier, I would always forget which fragment types are available\n to me and had to look them up. These fragment types can also differ per\n repository. In Protokolo, the types are always visible because they are\n directories.\n- Towncrier fragments are sorted by their ID, which is typically an issue or PR\n number. This isn't always what I want.\n- Because (some) Towncrier workflows put the PR number in the file name as\n metadata, I would have to open the PR before I could create the change log\n fragment.\n\nA much younger version of me also tried her hand at writing a program like this\nin [changelogdir](https://pypi.org/project/changelogdir/).\n\n## Install\n\nProtokolo is a regular Python package\n[hosted on PyPI](https://pypi.python.org/pypi/protokolo). You can install it\nusing `pipx install protokolo`. Make sure that `~/.local/share/bin` is in your\n`$PATH` with `pipx ensurepath`.\n\n## Usage\n\nFor full documentation and options, read the documentation at\n<https://protokolo.readthedocs.io>.\n\n### Initial set-up\n\nTo set up your project for use with Protokolo, run `protokolo init`. This will\ncreate a `CHANGELOG.md` file (if one did not already exist) and a directory\nstructure under `changelog.d`. The directory structure uses the\n[Keep a Changelog](https://keepachangelog.com/) sections, and ends up looking\nlike this:\n\n```\n.\n\u251c\u2500\u2500 changelog.d\n\u2502 \u251c\u2500\u2500 added\n\u2502 \u2502 \u2514\u2500\u2500 .protokolo.toml\n\u2502 \u251c\u2500\u2500 changed\n\u2502 \u2502 \u2514\u2500\u2500 .protokolo.toml\n\u2502 \u251c\u2500\u2500 deprecated\n\u2502 \u2502 \u2514\u2500\u2500 .protokolo.toml\n\u2502 \u251c\u2500\u2500 fixed\n\u2502 \u2502 \u2514\u2500\u2500 .protokolo.toml\n\u2502 \u251c\u2500\u2500 removed\n\u2502 \u2502 \u2514\u2500\u2500 .protokolo.toml\n\u2502 \u251c\u2500\u2500 security\n\u2502 \u2502 \u2514\u2500\u2500 .protokolo.toml\n\u2502 \u2514\u2500\u2500 .protokolo.toml\n\u251c\u2500\u2500 CHANGELOG.md\n\u2514\u2500\u2500 .protokolo.toml\n```\n\nThe `.protokolo.toml` files in `changelog.d` contain metadata for their\nrespective sections: the section title, heading level, and order. Their\ninclusion is mandatory.\n\nThe `.protokolo.toml` file in the root of the project contains configurations\nfor Protokolo that reduce the amount of typing you need to do when running\ncommands.\n\nIf a `CHANGELOG.md` file already existed, make sure to add a line containing\n`<!-- protokolo-section-tag -->` just before the heading of the latest release.\n\n### Adding fragments\n\nTo add a change log fragment, create the file `changelog.d/added/my_feature.md`,\nand write something like:\n\n```markdown\n- Added `--my-new-feature` option.\n```\n\nNote the bullet at the start---Protokolo does not add them for you. What you\nwrite is exactly what you get.\n\nYou can add more files. Change log fragments in the same section (read:\ndirectory) are sorted alphabetically by their file name. If you want to make\ncertain that some change log fragments go first or last, prefix the file with\n`000_` or `zzz_`. For example, you can create\n`changelog.d/added/000_important_feature.md` to make it appear first.\n\n### Compiling your change log\n\nYou compile your change log with `protokolo compile`. This will take all change\nlog fragments from `changelog.d` and put them in your `CHANGELOG.md`. If we run\nit now, the following section is added after the\n`<!-- protokolo-section-tag -->` comment:\n\n```markdown\n## ${version} - 2023-11-08\n\n### Added\n\n- Added important feature.\n- Added `--my-new-feature` option.\n```\n\nThe Markdown files in `changelog.d/added/` are deleted. You can manually replace\n`${version}` with a release version, or you can pass the option\n`--format version 1.0.0` to `protokolo compile` to format the heading at compile\ntime.\n\n## Maintainers\n\n- Carmen Bianca BAKKER <carmen@carmenbianca.eu>\n\n## Contributing\n\nThe code and issue tracker is hosted at\n<https://codeberg.org/carmenbianca/protokolo>. You are welcome to open any\nissues. For pull requests, bug fixes are always welcome, but new features should\nprobably be discussed in any issue first.\n\nTranslations are done at\n<https://hosted.weblate.org/projects/protokolo/protokolo/> using Weblate. If\nthere are issues with translation, feel free to open an issue at Codeberg.\n\n## Licensing\n\nAll code is licensed under GPL-3.0-or-later.\n\nAll documentation is licensed under CC-BY-SA-4.0 OR GPL-3.0-or-later.\n\nSome configuration files are licensed under CC0-1.0 OR GPL-3.0-or-later.\n\nThe repository is [REUSE](https://reuse.software)-compliant. Check the\nindividual files for their exact licensing.\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Protokolo is a change log generator.",
"version": "2.1.4",
"project_urls": {
"Documentation": "https://protokolo.readthedocs.io",
"Homepage": "https://codeberg.org/carmenbianca/protokolo",
"Repository": "https://codeberg.org/carmenbianca/protokolo"
},
"split_keywords": [
"changelog",
" history",
" news"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "809858f8c91710949ae612505445787a07ff80b0abe7bd6b448c0c452f7647c2",
"md5": "c10367eb3712df486a3cef1adca8c2ba",
"sha256": "b10ff72199e5ced3fd662a5b870b673bf37a5c990dd4eacf054bdf3ea5f2e359"
},
"downloads": -1,
"filename": "protokolo-2.1.4-cp311-cp311-manylinux_2_36_x86_64.whl",
"has_sig": false,
"md5_digest": "c10367eb3712df486a3cef1adca8c2ba",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": "<4.0,>=3.11",
"size": 48671,
"upload_time": "2024-04-30T17:52:19",
"upload_time_iso_8601": "2024-04-30T17:52:19.524893Z",
"url": "https://files.pythonhosted.org/packages/80/98/58f8c91710949ae612505445787a07ff80b0abe7bd6b448c0c452f7647c2/protokolo-2.1.4-cp311-cp311-manylinux_2_36_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7467e5d635ddf4553ac783709c95f01f0625c993615f98d5c6ac017257d9c780",
"md5": "dcb6e2353ea7c819a759b2ccca0ba54b",
"sha256": "451addc697e43a2aac4db612acf747ffe839686e5ea71018a5bc1ea5adeddc08"
},
"downloads": -1,
"filename": "protokolo-2.1.4.tar.gz",
"has_sig": false,
"md5_digest": "dcb6e2353ea7c819a759b2ccca0ba54b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 55776,
"upload_time": "2024-04-30T17:52:22",
"upload_time_iso_8601": "2024-04-30T17:52:22.028784Z",
"url": "https://files.pythonhosted.org/packages/74/67/e5d635ddf4553ac783709c95f01f0625c993615f98d5c6ac017257d9c780/protokolo-2.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 17:52:22",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "carmenbianca",
"codeberg_project": "protokolo",
"lcname": "protokolo"
}
JSON