cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add docs on how to write changelog fragments (#42428)

Browse source 
* Add docs on how to write changelog fragments

* Make recommended changes

* Restore lines and make recommended changes

* Add link to new style changelog

Remove redundant mention of old style changelog
This commit is contained in:
Sam Doran 2018-09-11 12:23:22 -04:00 committed by ansibot
parent 9d2c989337
commit 5d6f844eba
2 changed files with 45 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docsite/rst/community/development_process.rst
View file

@ -63,7 +63,7 @@ pull request to backport the change to a previous stable branch.
git cherry-pick -x [SHA_FROM_DEVEL]
#. Add a changelog entry for the change, and commit it.
#. Add a :ref:`changelog fragment <changelogs_how_to>` for the change, and commit it.
#. Push your feature branch to your fork on GitHub:

48
docs/docsite/rst/reference_appendices/release_and_maintenance.rst
View file

@ -97,14 +97,54 @@ releases of Ansible, there can sometimes be exceptions for critical issues.
.. _GitHub: https://github.com/ansible/ansible
.. _changelogs_how_to:
Changelogs
~~~~~~~~~~~~~~~~~~
Since 2.5, we've logged changes to ``stable-<version>`` git branches at ``stable-<version>/changelogs/CHANGELOG-v<version>.rst``.
For example, here's the changelog for 2.5_ on GitHub.
Older versions logged changes in ``stable-<version>`` branches at ``stable-<version>/CHANGELOG.md``. For example, here is the changelog for 2.4_ on GitHub.
We now generate changelogs based on fragments. Here is the generated changelog for 2.6_ as an example. When creating new features or fixing bugs, create a changelog fragment describing the change. A changelog entry is not needed for new modules or plugins. Details for those items will be generated from the module documentation.
Creating New Fragments
----------------------
Create a new file with a unique and descriptive name in ``changelogs/fragments/`` that ends in ``.yaml`` such as ``user-40696-backup-shadow-file.yaml``
A single changelog fragment may contain multiple sections but most will only contain one section. Here are the valid sections and a description of each:
**major_changes**
Major changes to Ansible itself. Generally does not include module or plugin changes.
**minor_changes**
Minor changes to Ansible, modules, or plugins. This includes new features, new parameters added to modules, or behavior changes to existing parameters.
**deprecated_features**
Features that have been deprecated and are scheduled for removal in a future release.
**removed_features**
Features that were previously deprecated and are now removed.
**bugfixes**
Fixes that resolve issues. If there is a specific issue related to this bugfix, add a link in the changelog entry.
**known_issues**
Known issues that are currently not fixed or will not be fixed.
Most changelog entries will be ``bugfixes`` or ``minor_changes``. When writing a changelog entry that pertains to a particular module, start the entry with ``- [module name] -`` and include a link to the related issue if one exists. Here are some examples:
.. code-block:: yaml
bugfixes:
- win_updates - fixed issue where running win_updates on async fails without any error
.. code-block:: yaml
minor_changes:
- lineinfile - add warning when using an empty regexp (https://github.com/ansible/ansible/issues/29443)
Commit the changelog fragment and include it with the pull request.
Older versions logged changes to ``stable-<version>/CHANGELOG.md``. For example,
here's the CHANGELOG for 2.4_.
Release candidates