mirror of https://github.com/ansible/ansible.git
[docs][backport] 5 06 docs backportapalooza (#77749)
* Docsite: move a stepped down steering committee member to past members (#77715) (cherry picked from commitpull/77787/head^2a1ddb83fc1) * add collection pr review checklist (#77661) Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com> Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru> (cherry picked from commitef2fe6823c) * clarify latest release (#77577) * clarify latest release * fix tables (cherry picked from commitf633b62cbc) * typo in doc (#77672) (cherry picked from commitc71faec595) * Docs: `ansible-test sanity` example with a folder ##### SUMMARY The docs mentions explicitly that you can run the tests against certain files which might not relay that it works on folders too! Let's make this clear :) ##### ISSUE TYPE - Docs Pull Request +label: docsite_pr (cherry picked from commit52bd59c481) * docs: update porting guide for ansible 6.0.0a2 (#77736) (cherry picked from commit0cfc291573) * simplify developing modules (#77647) (cherry picked from commit255745b3e6) * Mention admin requirement for runas become (#77722) (cherry picked from commitdd094a4413) * core branch descriptions (#76152) (cherry picked from commitd352f2ec21) * Fix ansible-test import analysis warning. Fix overlooked in https://github.com/ansible/ansible/pull/68372/ (cherry picked from commit77732ed50d) * Revert "Fix ansible-test import analysis warning." This reverts commit676f1056cb. Co-authored-by: Andrew Klychkov <aklychko@redhat.com> Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Kristian Heljas <11139388+kristianheljas@users.noreply.github.com> Co-authored-by: David Moreau Simard <moi@dmsimard.com> Co-authored-by: Brian Coca <bcoca@users.noreply.github.com> Co-authored-by: Jordan Borean <jborean93@gmail.com> Co-authored-by: Matt Davis <6775756+nitzmahone@users.noreply.github.com> Co-authored-by: Matt Clay <matt@mystile.com>
Sandra McCann
3 years ago
committed by
GitHub
parent
a07e3eb45b
commit
a6d7eb8710
@ -0,0 +1,74 @@
|
||||
.. _review_checklist:
|
||||
|
||||
Review checklist for collection PRs
|
||||
====================================
|
||||
|
||||
Use this section as a checklist reminder of items to review when you review a collection PR.
|
||||
|
||||
Reviewing bug reports
|
||||
----------------------
|
||||
|
||||
When users report bugs, verify the behavior reported. Remember always to be kind with your feedback.
|
||||
|
||||
* Did the user made a mistake in the code they put in the Steps to reproduce issue's section? We often see user errors reported as bugs.
|
||||
* Did the user assume an unexpected behavior? Ensure that the related documentation is clear. If not, the issue is useful to help us improve documentation.
|
||||
* Is there a minimal reproducer? If not, ask the reporter to reduce the complexity to help pinpoint the issue.
|
||||
* Is the issue a consequence of wrong-configured environment?
|
||||
* If it seems to be real bug, does the behaviour still exist in the most recent release or the development branch?
|
||||
* Reproduce the bug, or if you do not have a suitable infrastructure, ask other contributors to reproduce the bug.
|
||||
|
||||
|
||||
Reviewing suggested changes
|
||||
---------------------------
|
||||
|
||||
When reviewing PRs, verify the suggested changes first. Do not:
|
||||
|
||||
* Unnecessarily break backwards compatibility.
|
||||
* Bring more harm than value.
|
||||
* Introduce non-idempotent solutions.
|
||||
* Duplicate already existing features (inside or outside the collection).
|
||||
* Violate the :ref:`Ansible development conventions <module_conventions>`.
|
||||
|
||||
|
||||
Other standards to check for in a PR include:
|
||||
|
||||
* A pull request MUST NOT contain a mix of bugfixes and new features that are not tightly related. If yes, ask the author to split the pull request into separate PRs.
|
||||
* If the pull request is not a documentation fix, it must include a :ref:`changelog fragment <collection_changelog_fragments>`. Check the format carefully as follows:
|
||||
|
||||
* New modules and plugins (that are not jinja2 filter and test plugins) do not need changelog fragments.
|
||||
* For jinja2 filter and test plugins, check out the `special syntax for changelog fragments <https://github.com/ansible-community/antsibull-changelog/blob/main/docs/changelogs.rst#adding-new-roles-playbooks-test-and-filter-plugins>`_.
|
||||
* The changelog content contains useful information for end users of the collection.
|
||||
|
||||
* If new files are added with the pull request, they follow the `licensing rules <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#licensing>`_.
|
||||
* The changes follow the :ref:`Ansible documentation standards <developing_modules_documenting>` and the :ref:`style_guide`.
|
||||
* The changes follow the :ref:`Development conventions <developing_modules_best_practices>`.
|
||||
* If a new plugin is added, it is one of the `allowed plugin types <https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#modules-plugins>`_.
|
||||
* Documentation, examples, and return sections use FQCNs for the ``M(..)`` :ref:`format macros <module_documents_linking>` when referring to modules.
|
||||
* Modules and plugins from ansible-core use ``ansible.builtin.`` as an FQCN prefix when mentioned.
|
||||
* When a new option, module, plugin, or return value is added, the corresponding documentation or return sections use ``version_added:`` containing the *collection* version which they will be first released in.
|
||||
|
||||
* This is typically the next minor release, sometimes the next major release. For example: if 2.7.5 is the current release, the next minor release will be 2.8.0, and the next major release will be 3.0.0).
|
||||
|
||||
* FQCNs are used for ``extends_documentation_fragment:``, unless the author is referring to doc_fragments from ansible-core.
|
||||
* New features have corresponding examples in the :ref:`examples_block`.
|
||||
* Return values are documented in the :ref:`return_block`.
|
||||
|
||||
|
||||
Review tests in the PR
|
||||
----------------------
|
||||
Review the following if tests are applicable and possible to implement for the changes included in the PR:
|
||||
|
||||
|
||||
* Where applicable, the pull request has :ref:`testing_integration` and :ref:`testing_units`.
|
||||
* All changes are covered. For example, a bug case or a new option separately and in sensible combinations with other options.
|
||||
* Integration tests cover ``check_mode`` if supported.
|
||||
* Integration tests check the actual state of the system, not only what the module reports. For example, if the module actually changes a file, check that the file was changed by using the ``ansible.builtin.stat`` module..
|
||||
* Integration tests check return values, if applicable.
|
||||
|
||||
|
||||
Review for merge commits and breaking changes
|
||||
---------------------------------------------
|
||||
|
||||
* The pull request does not contain merge commits. See the GitHub warnings at the bottom of the pull request. If merge commits are present, ask the author to rebase the pull request branch.
|
||||
* If the pull request contains breaking changes, ask the author and the collection maintainers if it really is needed, and there is a way not to introduce breaking changes. If breaking changes are present, they MUST only appear in the next major release and MUST NOT appear in a minor or patch release. The only exception is breaking changes caused by security fixes that are absolutely necessary to fix the security issue.
|
||||
|
||||
@ -0,0 +1,58 @@
|
||||
.. _core_branches_and_tags:
|
||||
|
||||
******************************************
|
||||
``ansible-core`` project branches and tags
|
||||
******************************************
|
||||
|
||||
``devel`` branch
|
||||
================
|
||||
|
||||
All new development on the next version of ``ansible-core`` occurs exclusively in the ``devel`` branch,
|
||||
and all bugfixes to prior releases must first be merged to devel before being backported to one or more stable branches
|
||||
for inclusion in servicing releases. Around the Beta 1 milestone, a new ``stable-X.Y`` branch is cut from ``devel``,
|
||||
which is then updated to host development of the ``X.Y+1`` release. External automated testing of Ansible content from
|
||||
``devel`` is not generally recommended.
|
||||
|
||||
``stable-X.Y`` branches
|
||||
=======================
|
||||
|
||||
All ``ansible-core`` ``X.Y.Z`` releases are created from a corresponding ``stable-X.Y`` branch. A
|
||||
release's stable branch is typically cut from ``devel`` around ``X.Y.0 beta 1`` (when the release is feature complete).
|
||||
All further bugfixes (no enhancements!) must be made against ``devel`` and backported to applicable stable branches.
|
||||
|
||||
``vX.Y.Z`` tags
|
||||
===============
|
||||
|
||||
Each ``ansible-core vX.Y.Z`` release is tagged from the release commit in the corresponding ``stable-X.Y`` branch,
|
||||
allowing access to the exact source used to create the release. As of ``ansible-core`` 2.13, the auto-generated GitHub
|
||||
tarball of the tag contents is considered the official canonical release artifact.
|
||||
|
||||
|
||||
.. _milestone_branch:
|
||||
|
||||
``milestone`` branch
|
||||
====================
|
||||
|
||||
A ``milestone`` branch is a slow-moving stream of the ``devel`` branch, intended for external testing of ``ansible-core``
|
||||
features under active development. As described in the :ref:`ansible_core_roadmaps` for a given release, development is
|
||||
typically split into three phases of decreasing duration, with larger and more invasive changes targeted to be merged to
|
||||
``devel`` in earlier phases. The ``milestone`` branch is updated to the contents of ``devel`` at the end of each
|
||||
development phase. This allows testing of semi-stable unreleased features on a predictable schedule without the exposure
|
||||
to the potential instability of the daily commit "fire hose" from ``devel``. When a release reaches the Beta 1 milestone,
|
||||
the ``milestone`` branch will be updated to the first ``devel`` commit after the version number has been increased.
|
||||
Further testing of the same release should be done from the new ``stable-X.Y`` branch that was created. If a severe issue
|
||||
that significantly affects community testing or stability is discovered in the ``milestone`` branch, the branch contents
|
||||
may require unscheduled adjustment, but not in a way that prevents fast-forward updates (for example, ``milestone``-only
|
||||
commits will not be created or cherry-picked from ``devel``).
|
||||
|
||||
The following example is for illustrative purposes only. See the :ref:`ansible_core_roadmaps` for accurate dates. For example, the ``milestone`` branch in 2.13 ``ansible-core`` roadmap updated as follows:
|
||||
|
||||
* 27-Sep-2021: 2.13 Development Phase 1 begins; ``milestone`` contents are updated to 2.12.0b1 with version number set to
|
||||
``2.13.0.dev0``. Automated content testing that includes version-specific ignore files (e.g., ``ignore-2.12.txt``)
|
||||
should copy them for the current version (e.g., ``ignore-2.13.txt``) before this point to ensure that automated sanity
|
||||
testing against the ``milestone`` branch will continue to pass.
|
||||
* 13-Dec-2021: 2.13 Development Phase 2 begins; ``milestone`` contents are updated to the final commit from Development Phase 1
|
||||
* 14-Feb-2022: 2.13 Development Phase 3 begins; ``milestone`` contents are updated to the final commit from Development Phase 2
|
||||
* 11-Apr-2022: ``stable-2.13`` branch created with results from Development Phase 3 and freeze. ``2.13.0b1`` is released from
|
||||
``stable-2.13``. Automated content testing should continue 2.13 series testing against the new branch. The ``devel``
|
||||
version number is updated to ``2.14.0.dev0``, and ``milestone`` is updated to that point.
|
||||
Loading…
Reference in New Issue