Expand description
Building changelogs from fragments.
§Example
Please see the readme for an overview of this project and an example of using it.
§Inspiration
Keep a Changelog is the inspiration of this project.
The changelog of changelogging
is built using itself, which gives the “bootstrapping” vibe.
§Terminology
§Changelogs
Changelogs are files which document all notable changes between project versions. Each version of the project has its own entry in the changelog.
§Fragments
Fragments are small pieces of information, which, combined together, form changelog entries.
Fragments contain three things:
- id, usually bound to something like pull requests;
- type, for instance change or feature;
- content, which gets written to the changelog.
In changelogging
, fragments are files which have names starting with {id}.{name}
and contain fragment contents.
§Entries
Entries describe changes between project versions. They are composed of sections.
§Sections
Sections group and describe specific changes, e.g. features, fixes, deprecations, etc.
§Configuration
changelogging
uses TOML for its configuration.
By default the application will look for the changelogging.toml
file in the current directory.
It also understands pyproject.toml
if it contains the [tool.changelogging]
section.
In case both files are present, the former takes precedence.
See config
for configuration, context
for contexts and workspace
that combines configuration and context into one structure.
§Usage
This section assumes we have this configuration and the following template.
§Globals
--help (-h)
displays help information.--version (-V)
shows this application’s version.--directory (-D)
changes the directory before doing anything.--config (-C)
specifies the configuration file to use.
§create
The create
command is used to create changelog fragments.
The fragment content can be passed through the argument:
$ changelogging create --content "Added cool features!" 13.feature.md
If the content is not provided, the placeholder gets written instead:
$ changelogging create 64.change.md
$ cat changes/64.change.md
Add the fragment content here.
Let us add some content to this fragment:
$ echo "Changed some things!" > changes/64.change.md
Alternatively, the default editor can be used to write the fragment content:
$ changelogging create --edit ~bug.fix.md
And, inside the editor:
Fixed annoying bugs!
Here are the options (except for globals) that create
supports:
--content (-c)
passes the content of the fragment through the argument.--edit (-e)
opens the default editor to enter the fragment’s contents.--add (-a)
adds the fragment file viagit
.
§preview
The preview
command is used to preview changelog entries:
$ changelogging preview
## [0.7.0](https://github.com/nekitdev/changelogging/tree/v0.7.0) (YYYY-MM-DD)
### Features
- Added cool features! ([#13](https://github.com/nekitdev/changelogging/pull/13))
### Changes
- Changed some things! ([#64](https://github.com/nekitdev/changelogging/pull/64))
### Fixes
- Fixed annoying bugs!
Here are the options (except for globals) that preview
supports:
--date (-d)
specifies the date to use instead of today.
§build
The build
command is used to build changelog entries from fragments.
After one ensures that the changelog entry is correct, building the changelog is as simple as:
$ changelogging build
You can also see the rendered version.
Here are the options (except for globals) that build
supports:
--date (-d)
specifies the date to use instead of today.--stage (-s)
stages the updated changelog viagit
.--remove (-r)
removes all fragment files withgit
.
Modules§
- app
- The application.
- builder
- Building changelogs from fragments.
- commands
changelogging
subcommands.- config
- Configuration.
- context
- Context.
- date
- Parsing dates and fetching the current date.
- discover
- Discovering workspaces.
- fragment
- Changelog fragments.
- git
git
functionality.- init
- Application initialization.
- load
- Loading values from paths.
- workspace
- Discovering and loading workspaces.