Skip to content

Commit 9f769b6

Browse files
patchback[bot]pkingstonxyzwebknjaz
authored
Enhance "Making your PR Merge Worthy" section (#3028) (#3243)
* Fix grammar and add documentation link - Fix the number-verb agreement in a bullet point - Add a link to the RST spec and re-word the embedding * Add small section on testing * Edit title for Changelog section I find the title "Creating changelog fragments" too similar to "Creating a changelog fragment". * Update title of test section and reorganize sentences * Fix spelling of preferred * Add words for clarity * Capitalize YAML and RST Capitalizing these helps to distinguish between the yaml/rst format and file extension. * Fix line breaks in test section * Rephrase testing section * Fix period clickability --------- (cherry picked from commit b2a6c41) Co-authored-by: Patrick Kingston <[email protected]> Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>
1 parent 9147a38 commit 9f769b6

File tree

1 file changed

+17
-4
lines changed

1 file changed

+17
-4
lines changed

docs/docsite/rst/community/development_process.rst

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,8 @@ We do not merge every PR. Here are some tips for making your PR useful, attracti
5151

5252
.. _community_changelogs:
5353

54-
Creating changelog fragments
55-
------------------------------
54+
Changelog fragments
55+
-------------------
5656

5757
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.
5858

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

6868
More precisely:
6969

70-
* 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.
70+
* Every bugfix PR must have a changelog fragment. The only exceptions are fixes to changes that have not yet been included in a release.
7171
* Every feature PR must have a changelog fragment.
7272
* 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.
7373

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

81-
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.
81+
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.
8282

8383
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.
8484

@@ -225,6 +225,19 @@ While new modules, plugins, and roles are mentioned automatically in the generat
225225
# not have a period at the end.
226226
description: Wipes a server
227227
228+
.. _contribution_guide_testing_prs:
229+
230+
Testing PRs
231+
-----------
232+
233+
Adding tests for your PR makes it a stronger candidate for being merged.
234+
235+
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>`_.
236+
237+
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>`_.
238+
239+
If you are not sure how to proceed with writing tests, ask for clarification in any of our :ref:`community channels <communication>`.
240+
228241
.. _backport_process:
229242

230243
Backporting merged PRs in ``ansible-core``

0 commit comments

Comments
 (0)