# Crafting better changelog fragments ###### tags: `Documentation` **Discusison moved to https://github.com/ansible-community/community-topics/issues/64** This is a summary of some conversations we had recently on what users need, what developers need, etc when it comes to what's new and different in a given Ansible release. ## What Ansible has today Today, Ansible provides: * **Porting guide** (target audience, end users of Ansible)- The Ansible package generates this based on changelog entries that have been tagged as XXX. ansible-core manually creates porting guide entries. * **Changelogs** (Target audience, end users AND developers) - Both Ansible package and ansible-core provide changelogs, but we don't have a lot of guidance on what should be included in a 'good' changelog entry. * **git commits** (target audience - other developers)- I don't think we show these anywhere outside of git itself? ## What makes for a good changelog fragment? We should provide guidance on this so that developers aren't basing changelog fragments on what they would normally put in a git commit. Changelogs should aim at informing the end-users about the high-level influence on their workflows UX-wise that has happened since the previous release. These fragments should be written in a common style so the autogenerated results flow well together. Perhaps choosing past tense. ## Do we need release notes? Currently we have nothing that is a release note other than what goes out in the release announcement emails. Do we need something in this space besides the porting guide? Does the porting guide really tell the end user how to 'port' their playbooks etc to a new ansible version? Or is the porting guide really a partial combination of upgrade/porting information and what would normally be release note information? (more questions than answers here!) ## related links/discussions Discussion moved to https://github.com/ansible-community/community-topics/issues/64 * osp fragment guidelines - https://paste.openstack.org/show/812197/ * * https://towncrier.rtfd.io/en/actual-freaking-docs/#philosophy * https://scriv.readthedocs.io/en/latest/philosophy.html#philosophy * https://setuptools.pypa.io/en/latest/development/developer-guide.html#making-a-pull-request