Package: proclamation
ProclamationA tool for building changelog files from fragments: ease to maintain, easy for
users to read.Inspired bytowncrier, but completely language-agnostic and markup-agnostic.
(The default template uses Markdown, but all formatting is controlled by Jinja2
templates so you can change that as desired.)Maintained athttps://gitlab.com/proclamation/proclamationDocumentation also available athttps://proclamation.readthedocs.io/en/latest/Table of ContentsBackgroundInstallUsageCLIMaintainersThanksCode of ConductContributingLicenseDefault license, including all Python code filesTemplates and this documentationBackgroundThe concept behindtowncrieris great: ease the maintenance burden of
creating human-readable changelogs (for projects where a git log/shortlog won't
suffice) and simultaneouslyhave each contributor/change author describe their own change for a
human-readable changelogavoid merge conflicts from everyone editing the same changelog fileTowncrier, as well as Proclamation, do this by having "changelog fragments"
accumulate between releases, and combining them (with a template and some
metadata) when running the tool before a release. While towncrier is focused on
Python and.rstformatting, Proclamation is explicitly language-neutral (a
motivating use case was a mixed-content repo with specifications as well as C++
code) and markup-neutral (all formatting is done by a Jinja2 template: the
default is Markdown but you can completely change the formatting if you supply a
custom template.)InstallNote:Contributors to your Proclamation-using project do not need to install
Proclamation -- all they have to do is create a text file, and only the person
doing releases strictly needs to install Proclamation. However, there are some
utilities that they might find useful if they do.Proclamation requires Python 3.7 or newer.Proclamation is available onpypi, so you can install it for your local user
in an isolated virtual environment withpipx:pipxinstallproclamationUpdating to a new release would be done withpipxupgradeproclamationAlternately, you can install from this repository. If you do this, it's
recommended to install this in a virtual environment. Something like this will
work on *nix-like systems, adjusted for your shell usage.# Create a virtualenv in `venv`python3-mvenvvenv# Activate it.venv/bin/activate# Install a link to this package in the venv.pipinstall--editable.If you follow those instructions, the virtualenv will refer to the source
instead of copying the source, so updating your local clone of this repo will
also update the virtualenv. Omit the--editableif you want other behavior.Note that thevenv/bin/proclamationscript can be run from outside the venv,
through the magic of virtual environments, so if you want to be able to use it
elsewhere on your system, you might symlink it into a directory that's in yourPATH. But, at that point, you may as well just usepipx.UsageFor detailed instructions that you might consider copying and modifying for your
own project, seeUSAGE.md.Proclamation itself is primarily used through the command line by the person
making releases.If theproclamationcommand line tool doesn't quite suit your complex needs,
you can access the bulk of the functionality through using this as a Python
module. See the command line interface driver,proclamation/main.py, to see
how it interacts with the underlying capabilities.CLIProclamation has command-line help available by passing--help. You can access
general help, listing overall options and subcommands, as follows:proclamation--helpAdditionally, each subcommand has its own help text, describing it and its available options, for example:proclamationbuild--helpA brief description of the two most common subcommands follows.To see a preview of the changelog additions that would be made if you
released a new version right now, runproclamationdraftThedraftsubcommand is the most useful one to non-maintaining contributors
who choose to install Proclamation, as it lets them verify their changelog
fragment(s) appear as desired.The main subcommand used by maintainers isbuild, for example like this:proclamationbuildYOUR_VERSION_NUMBER_HEREThis command updates your changelog file(s) (overwriting the original), and
removes your used changelog fragments for you. (You still need to remove them
from your version control system.)Maintainers@ryliepavlikhttps://ryliepavlik.comThanksThis tool was initially developed and maintained by Rylie Pavlik in the course
of her work at the open-source software consultancyCollabora. Thanks to Collabora and their "Open First"
mantra for supporting the development of this software.A debt of gratitude is owed to the developers of thetowncrierpackage,
which strongly inspired the usage pattern for this tool. (Before writing this
tool, Rylie initially attempted to modify towncrier to suit the use cases she
had.) It's definitely a project worth looking into if you maintain a Python
project. (The Proclamation project doesn't use it, despite being in Python,
because Proclamation uses itself...) Rylie first learned about towncrier atStephen Finucane's talk at FOSDEM 2020.Code of ConductPlease note that this project is released with a Contributor Code of Conduct. By
participating in this project you agree to abide by its terms.ContributingIf you have questions or found a bug, feel free to file an issue on the GitLab
project for Proclamation.Merge requests are gratefully accepted. To develop on Proclamation, you'll
probably want to follow the virtualenv installation instructions above to
locally install a link in a virtualenv.Additionally, consider the following suggestions/requirements:"flit" is the build system used, but pip/pipx should be able to handle it.Runpytest-3or similar to run the automated tests. If you add
functionality, consider adding tests.Runblack proclamationto
automatically format the source code withblack.Usetoxto runflake8as well as tests for multiple Python versions.e.g. on Debian Bookworm, you can runtox -e py39,flake8When submitting a change, be sure to create your changelog fragment in the
`changes`` directory! :)If editing the README, please conform to thestandard-readmespecification.No copyright assignment is required to contribute. However, you are required to
make your contributions available under the prevailing license for that content
type (see below) for it to be accepted into the main repo.LicenseThetl;dris: The bulk of the package isApache-2.0licensed. Files that
you might incorporate into your own project areCC0(roughly, public domain
dedication or nearest equivalent based on jurisdiction); this is so you can
freely use them into your project no matter what license you use.Every file has an SPDX license tag and copyright or author information in it
which is considered the authoritative licensing data.Note that dependencies and third-party documents may have their own licenses.
For instance, the code of conduct, based on the Contributor Covenant v2.0, is
licensed CC-BY-4.0.This project isREUSE-compliant(version 3.0 of the
REUSE specification). You can use that project's tools to work with the
copyright and license notices of files in this project.Default license, including all Python code filesCopyright 2019-2023 Collabora, Ltd. and the Proclamation contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.Templates and this documentationSPDX-License-Identifier: CC0-1.0
SPDX-FileCopyrightText: 2021-2023 Collabora, Ltd. and the Proclamation contributorsThisREADME.mdfileproclamation/templates/*CC0 1.0 Universal (CC0 1.0) Public Domain DedicationTo the extent possible under law, the person who associated CC0 with this work
has waived all copyright and related or neighboring rights to this work. This
work is published from: United States.