You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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]>
Copy file name to clipboardExpand all lines: docs/docsite/rst/community/development_process.rst
+17-4Lines changed: 17 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -51,8 +51,8 @@ We do not merge every PR. Here are some tips for making your PR useful, attracti
51
51
52
52
.. _community_changelogs:
53
53
54
-
Creating changelog fragments
55
-
------------------------------
54
+
Changelog fragments
55
+
-------------------
56
56
57
57
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.
58
58
@@ -67,7 +67,7 @@ You do not need a changelog fragment for PRs that:
67
67
68
68
More precisely:
69
69
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.
71
71
* Every feature PR must have a changelog fragment.
72
72
* 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.
73
73
@@ -78,7 +78,7 @@ We build short summary changelogs for minor releases as well as for major releas
78
78
Creating a changelog fragment
79
79
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
80
80
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.
82
82
83
83
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.
84
84
@@ -225,6 +225,19 @@ While new modules, plugins, and roles are mentioned automatically in the generat
225
225
# not have a period at the end.
226
226
description: Wipes a server
227
227
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>`.
0 commit comments