From 9a4a65cd99bc49bffff04bfd0df2ee2a77d9c3f2 Mon Sep 17 00:00:00 2001 From: pkingsto Date: Fri, 5 Sep 2025 14:17:40 -0400 Subject: [PATCH 1/9] 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 --- docs/docsite/rst/community/development_process.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index b3f74453d14..c1e9bbad5e0 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -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. @@ -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 in the `rst `_ format 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. From 4949c244efe0d917518f7b09f7da7c27fac0e0d3 Mon Sep 17 00:00:00 2001 From: pkingsto Date: Fri, 5 Sep 2025 15:05:27 -0400 Subject: [PATCH 2/9] Add small section on testing --- docs/docsite/rst/community/development_process.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index c1e9bbad5e0..27e1611122b 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -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_write_tests: + +Writing tests for PRs +--------------------- + +Adding tests for your PR makes it a stronger candidate for being merged. + +PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. Bugfix PRs should include tests that ensure the bug is no longer present. + +As a rule of thumb, integration tests located at `test/integration `_ should be prefered over unit tests located at `test/units `_). + +For more information on writing integration tests, see the docs page on :ref:`Integration tests `. And for information on writing unit tests see the docs page on :ref:`Unit tests `. Reading the existing integration and unit tests can also help when writing tests. + .. _backport_process: Backporting merged PRs in ``ansible-core`` From 14eb9bed45782bf63a4bc3fbb8780d85ec5dd06e Mon Sep 17 00:00:00 2001 From: pkingsto Date: Fri, 5 Sep 2025 15:07:07 -0400 Subject: [PATCH 3/9] Edit title for Changelog section I find the title "Creating changelog fragments" too similar to "Creating a changelog fragment". --- docs/docsite/rst/community/development_process.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 27e1611122b..d1f4a00d374 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -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. From 1e1343555399e8b0210567ffef4cb0398745e2d1 Mon Sep 17 00:00:00 2001 From: pkingsto Date: Fri, 5 Sep 2025 15:13:07 -0400 Subject: [PATCH 4/9] Update title of test section and reorganize sentences --- docs/docsite/rst/community/development_process.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index d1f4a00d374..ce76d5ac198 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -225,18 +225,18 @@ 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_write_tests: +.. _contribution_guide_testing_prs: -Writing tests for PRs ---------------------- +Testing PRs +----------- Adding tests for your PR makes it a stronger candidate for being merged. -PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. Bugfix PRs should include tests that ensure the bug is no longer present. +PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. Bugfix PRs should include tests that ensure the bug is no longer present. As a rule of thumb, integration tests should be prefered over unit tests. -As a rule of thumb, integration tests located at `test/integration `_ should be prefered over unit tests located at `test/units `_). +For information on writing integration tests, see the docs page on :ref:`Integration tests ` and the existing integration tests at `test/integration `_. -For more information on writing integration tests, see the docs page on :ref:`Integration tests `. And for information on writing unit tests see the docs page on :ref:`Unit tests `. Reading the existing integration and unit tests can also help when writing tests. +For information on writing unit tests see the docs page on :ref:`Unit tests ` and the existing unit tests at `test/units `_. .. _backport_process: From 25e68a1caf1f79507f5641659f0025e06807996b Mon Sep 17 00:00:00 2001 From: pkingsto Date: Fri, 5 Sep 2025 15:30:15 -0400 Subject: [PATCH 5/9] Fix spelling of preferred --- docs/docsite/rst/community/development_process.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index ce76d5ac198..463f0fc9bc8 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -232,7 +232,7 @@ Testing PRs Adding tests for your PR makes it a stronger candidate for being merged. -PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. Bugfix PRs should include tests that ensure the bug is no longer present. As a rule of thumb, integration tests should be prefered over unit tests. +PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. Bugfix PRs should include tests that ensure the bug is no longer present. As a rule of thumb, integration tests should be preferred over unit tests. For information on writing integration tests, see the docs page on :ref:`Integration tests ` and the existing integration tests at `test/integration `_. From 14b315d2f87b5eda279ee9178015a21c1a572e27 Mon Sep 17 00:00:00 2001 From: pkingsto Date: Fri, 5 Sep 2025 15:35:24 -0400 Subject: [PATCH 6/9] Add words for clarity --- docs/docsite/rst/community/development_process.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 463f0fc9bc8..0d91e418501 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -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 in the `rst `_ format 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. +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 `_ 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. From 3a2fcd4e2347f39584f928d56b0d139a13c985c6 Mon Sep 17 00:00:00 2001 From: pkingsto Date: Fri, 5 Sep 2025 15:40:22 -0400 Subject: [PATCH 7/9] Capitalize YAML and RST Capitalizing these helps to distinguish between the yaml/rst format and file extension. --- docs/docsite/rst/community/development_process.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 0d91e418501..8b0cfc261f4 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -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 written in the `rst `_ 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. +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 `_ 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. From d799294131fdc8388dcee5251ed6c33c54bd7644 Mon Sep 17 00:00:00 2001 From: Patrick Kingston <66141901+pkingstonxyz@users.noreply.github.com> Date: Tue, 9 Sep 2025 11:02:40 -0400 Subject: [PATCH 8/9] Fix line breaks in test section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) --- docs/docsite/rst/community/development_process.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 8b0cfc261f4..c0aadb6af1d 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -232,7 +232,9 @@ Testing PRs Adding tests for your PR makes it a stronger candidate for being merged. -PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. Bugfix PRs should include tests that ensure the bug is no longer present. As a rule of thumb, integration tests should be preferred over unit tests. +PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. +Bugfix PRs should include tests that ensure the bug is no longer present. +As a rule of thumb, integration tests should be preferred over unit tests. For information on writing integration tests, see the docs page on :ref:`Integration tests ` and the existing integration tests at `test/integration `_. From 3bd94fc5c991fccaba1a501324cfe633ff777218 Mon Sep 17 00:00:00 2001 From: Patrick Kingston <66141901+pkingstonxyz@users.noreply.github.com> Date: Fri, 12 Sep 2025 16:32:02 -0400 Subject: [PATCH 9/9] Rephrase testing section --- docs/docsite/rst/community/development_process.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index c0aadb6af1d..33072578ce5 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -232,14 +232,12 @@ Testing PRs Adding tests for your PR makes it a stronger candidate for being merged. -PRs that add new functionality should include tests to fully exercise the new functionality and the failure paths of that functionality. -Bugfix PRs should include tests that ensure the bug is no longer present. -As a rule of thumb, integration tests should be preferred over unit tests. - For information on writing integration tests, see the docs page on :ref:`Integration tests ` and the existing integration tests at `test/integration `_. For information on writing unit tests see the docs page on :ref:`Unit tests ` and the existing unit tests at `test/units `_. +If you are not sure how to proceed with writing tests, ask for clarification in any of our :ref:`community channels. ` + .. _backport_process: Backporting merged PRs in ``ansible-core``