change log
Fragments¶
The change log
utility manages change fragments
and compiles entire changelogs if required.
Each fragment represents an individual change made
for some version of your project;
versions tie together all changes that are released together.
Changelogs are based on keep a changelog and semantic versioning.
Fragments¶
Fragments are YAML files that contain meta-data
and human-readable descriptions of individual changes.
Each fragment file contains a mapping that must contain
the fields category
, summary
, and description
and optionally the fields
pull requests
and issues
; a unique naming convention of files such as
<first PR>.<topic>.yaml
is recommended.
Both summary
and description
fields are interpreted as reStructured Text.
The category
should be one of
added
, changed
, fixed
, deprecated
, removed
, or security
.
# file `4.documentation.yaml`
# any of 'added', 'changed', 'fixed', 'deprecated', 'removed', 'security'
category: added
# short description of changes
summary: "Added basic documentation on readthedocs.io"
# pull requests of this change
pull requests:
- 4
# issues solved by this change
issues:
- 5
# long description of changes
description: |
A ``sphinx`` documentation for tool usage and code maintenance is available at
`change-log.readthedocs.io <https://change-log.readthedocs.io/en/feature-docs/>`_.
The version
is optional and in most cases does not need manual definition.
Unversioned fragments belong to the next release, and
specific release information is added automatically when a release is prepared.