diff --git a/docs/docsite/rst/community/development_process.rst b/docs/docsite/rst/community/development_process.rst index 9ed2e3b7512..1e24a4cfda5 100644 --- a/docs/docsite/rst/community/development_process.rst +++ b/docs/docsite/rst/community/development_process.rst @@ -20,11 +20,13 @@ If you want to follow the conversation about what features will be added to ``an * the :ref:`roadmaps` * the :ref:`Ansible Release Schedule ` +* the :ref:`ansible-core project branches and tags ` * various GitHub `projects `_ - for example: * the `2.12 release project `_ * the `core documentation project `_ + .. _community_pull_requests: @@ -34,7 +36,7 @@ Micro development: the lifecycle of a PR If you want to contribute a feature or fix a bug in ``ansible-core`` or in a collection, you must open a **pull request** ("PR" for short). GitHub provides a great overview of `how the pull request process works `_ in general. The ultimate goal of any pull request is to get merged and become part of a collection or ``ansible-core``. Here's an overview of the PR lifecycle: -* Contributor opens a PR +* Contributor opens a PR (always against the ``devel`` branch) * Ansibot reviews the PR * Ansibot assigns labels * Ansibot pings maintainers @@ -43,6 +45,7 @@ Here's an overview of the PR lifecycle: * Contributor addresses any feedback from reviewers * Developers, maintainers, community re-review * PR merged or closed +* PR `backported `_ to one or more ``stable-X.Y`` branches (optional, bugfixes only) Automated PR review: ansibullbot -------------------------------- diff --git a/docs/docsite/rst/dev_guide/core_branches_and_tags.rst b/docs/docsite/rst/dev_guide/core_branches_and_tags.rst new file mode 100644 index 00000000000..aaef4aa5695 --- /dev/null +++ b/docs/docsite/rst/dev_guide/core_branches_and_tags.rst @@ -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. diff --git a/docs/docsite/rst/dev_guide/developing_core.rst b/docs/docsite/rst/dev_guide/developing_core.rst index eeee30fc73f..a6c8bfe4904 100644 --- a/docs/docsite/rst/dev_guide/developing_core.rst +++ b/docs/docsite/rst/dev_guide/developing_core.rst @@ -7,6 +7,7 @@ Although ``ansible-core`` (the code hosted in the `ansible/ansible repository