tldr; Please add a changelog fragment with any PR that is
changelog-worthy (features, major bugfixes, backwards
incompatiblities, etc) except for new modules and plugins (Our tooling
will automatically add any new module or plugin)
== Background ==
For the past two releases, Ansible has been working on adding
changelogs via a tool which assembles the changelog from short
snippets of yaml. Originally we tried to use the reno tool from the
openstack project but that didn't fit well wit the workflow that we
have for making releases. Recently we've switched to our own tool
which uses reno's changelog fragment format but doesn't walk the git
history to decide what should be included in the changelog. This
should let those familiar with reno create changelogs using their
existing knowledge while the ansible release engineers can use the
tool in a manner more closely aligned with our needs.
== Expectations ==
We're going to start requiring that any PRs that are merged and should
appear in the changelog have a changelog fragment. This includes new
features, major bugfixes, backward incompatibilities, deprecations,
and other things that users should know on update.
Minor bugfixes that are going to be backported we would want changelog
entries in the backport PR (if they didn't already appear in the devel
PR) as our changlog policy is for minor releases to list a short
summary of all changes.
== How to ==
A basic changelog fragment is a .yaml file placed in the
changelogs/fragments/ directory. Each file contains a yaml dict with
keys like "bugfixes" or "major_changes" followed by a list of
changelog entries of bugfixes or features. Each changelog entry is
rst embedded inside of the yaml file which means that certain
constructs would need to be escaped so they can be interpreted by rst
and not by yaml (or escaped for both yaml and rst if that's your
desire). Each PR should use a new fragment file rather than adding to
an existing one.
Here's an example of a changelog fragment for a bugfix: