Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 17 additions & 4 deletions docs/docsite/rst/community/development_process.rst
Original file line number Diff line number Diff line change
Expand Up @@ -51,8 +51,8 @@ We do not merge every PR. Here are some tips for making your PR useful, attracti

.. _community_changelogs:

Creating changelog fragments
------------------------------
Changelog fragments
-------------------

Changelogs help users and developers keep up with changes to ansible-core and Ansible collections. Ansible and many collections build changelogs for each release from fragments. For ansible-core and collections using this model, you **must** add a changelog fragment to any PR that changes functionality or fixes a bug.

Expand All @@ -67,7 +67,7 @@ You do not need a changelog fragment for PRs that:

More precisely:

* Every bugfix PR must have a changelog fragment. The only exception are fixes to a change that has not yet been included in a release.
* Every bugfix PR must have a changelog fragment. The only exceptions are fixes to changes that have not yet been included in a release.
* Every feature PR must have a changelog fragment.
* New modules and plugins (including jinja2 filter and test plugins) must have ``version_added`` entries set correctly in their documentation, and do not need a changelog fragment. The tooling detects new modules and plugins by their ``version_added`` values and announces them in the next release's changelog automatically.

Expand All @@ -78,7 +78,7 @@ We build short summary changelogs for minor releases as well as for major releas
Creating a changelog fragment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A basic changelog fragment is a ``.yaml`` or ``.yml`` 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 you prefer). Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it.
A basic changelog fragment is a ``.yaml`` or ``.yml`` 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 written in the `RST <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`_ format and embedded in the YAML file. This means that certain constructs need to be escaped so that they can be interpreted by RST and not by YAML (or escaped for both YAML and RST if you prefer). Each PR **must** use a new fragment file rather than adding to an existing one, so we can trace the change back to the PR that introduced it.

PRs which add a new module or plugin do not necessarily need a changelog fragment. See the previous section :ref:`community_changelogs`. Also see the next section :ref:`changelogs_how_to_format` for the precise format changelog fragments should have.

Expand Down Expand Up @@ -225,6 +225,19 @@ While new modules, plugins, and roles are mentioned automatically in the generat
# not have a period at the end.
description: Wipes a server

.. _contribution_guide_testing_prs:

Testing PRs
-----------

Adding tests for your PR makes it a stronger candidate for being merged.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if tests are required per any official policy, or if there is any
nuance for things that shouldn't include tests.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think cases where tests aren't necessary are obvious to contributors (like sending in a typo fix). We probably shouldn't give them any idea along the lines of "by hey, you can actually ignore this requirement". They'll ask if unsure.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm okay, I've rephrased to be more ambiguous but I think a call out to "Hey tests are good" should be included for first time contributors especially.


For information on writing integration tests, see the docs page on :ref:`Integration tests <testing_integration>` and the existing integration tests at `test/integration <https://github.com/ansible/ansible/tree/devel/test/integration/targets>`_.

For information on writing unit tests see the docs page on :ref:`Unit tests <testing_units>` and the existing unit tests at `test/units <https://github.com/ansible/ansible/tree/devel/test/units>`_.

If you are not sure how to proceed with writing tests, ask for clarification in any of our :ref:`community channels. <communication>`

.. _backport_process:

Backporting merged PRs in ``ansible-core``
Expand Down