# Changlogs for PRs

**URL:** <https://forum.ansible.com/t/changlogs-for-prs/27713>\
**Category:** Ansible Developer\
**Created:** [June 5, 2018, 9:22pm UTC](https://forum.ansible.com/t/changlogs-for-prs/27713 "2018-06-05T21:22:26Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![tkuratom](https://avatars.discourse-cdn.com/v4/letter/t/b19c9b/32.png) [@tkuratom](https://forum.ansible.com/u/tkuratom)\
**Post date:** [June 5, 2018, 9:22pm UTC](https://forum.ansible.com/t/changlogs-for-prs/27713/1 "2018-06-05T21:22:26Z")

</div>

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: