From a5a3a34b0f089d28e99b5c7712a246911aedf471 Mon Sep 17 00:00:00 2001 From: Quirin Pamp Date: Mon, 20 Nov 2023 17:46:08 +0100 Subject: [PATCH] Merge pull request #945 from ATIX-AG/release_process_docs Update the plugin maintenance docs (cherry picked from commit b15bb1fd8245a1ea208ea357f342989053e7b859) --- docs/plugin_maintenance.rst | 159 +++++++++--------------------------- 1 file changed, 38 insertions(+), 121 deletions(-) diff --git a/docs/plugin_maintenance.rst b/docs/plugin_maintenance.rst index abf33260f..a617a329f 100644 --- a/docs/plugin_maintenance.rst +++ b/docs/plugin_maintenance.rst @@ -19,77 +19,75 @@ A ``X`` version release, signifies one or more of the following: * The plugin is compatible with a new pulpcore ``X`` version. .. note:: - A ``X`` version release, is more of a high level "marketing" communication, than something with a detailed technical definition. + A ``X`` version release, is more of a high level communication, than something with a detailed technical definition. It is up to the judgement of plugin maintainers when a new ``X`` version is warranted. -A ``Y`` version release, signifies the following: +A ``Y`` version release, signifies one or more of the following: -* The ``Y`` version is the same, as the pulpcore-``Y`` version that the release is for. +* This release contains new features. +* This release may require a newer version of pulpcore (or some other dependency) than the ``Y-1`` release branch did. * A ``Y`` version release is given its own release branch. -* A ``Y`` version release may contain new features or any other type of change. -* A ``Y`` version release is generally performed when a new pulpcore ``Y`` version has been released. A ``Z`` version release, signifies the following: * A ``Z`` version release may contain only bugfixes (semantic versioning). -* ``Z`` stream changes are cherry-picked to the relevant ``Y`` version release branch. -* ``Z`` stream changes may be released as soon as they are ready, and as needs arise. +* A ``Z`` version change is cherry-picked to the relevant ``Y`` version release branch. +Pulp plugins follow a "release whenever" policy, this means both ``Y`` and ``Z`` releases may happen whenever there are relevant changes, and as the need arises. -.. _using_the_plugin_template: -Using the Plugin Template +Plugin Release Steps -------------------------------------------------------------------------------- -The `Pulp plugin template`_ is used to collect changes relevant to all Pulp plugins. -When there are new changes, the plugin template can then be used to automatically apply those changes to plugins that do not yet include them. - -To use the plugin template, make sure you have cloned the Git repository to the same folder as the ``pulp_deb`` repository. -You can then issue the below template commands within the root of the plugin template repository to apply changes. - .. note:: - It is generally fine to check out the latest ``master`` branch of the plugin template to apply changes. - Alternatively, use the latest tag the plugin template has received. - It is a good idea to reference the point in the plugin template history used in any commit messages, so others can reproduce what was done. + The `pulpcore release guide`_ wiki article is now badly out of date, but may still be of interest as a reference. -.. important:: - Not all plugin template commands cleanly destinguish between things needed to bootstrap a new plugin and things that should be applied to existing plugins again and again. - As a result it is essential to manually go through any changes applied by the template, and only committing those that actually make sense. - Changes from the ``--generate-config`` and ``--github`` commands can mostly be committed in full (check for `master` versus `main` branch naming), while changes from the ``--docs`` and ``--bootstrap`` commands may overwrite a lot of existing plugin code, but may sometimes add useful changes. +At the time of this writing the release process required the following steps: --------------------------------------------------------------------------------- +#. (optional) Run the "CI Update" action and review and merge any resulting PRs. +#. (``Y`` version release only) Run the "Create New Release Branch" action. +#. Run the "Release Pipeline" action from the relevant release branch and merge any resulting PRs. +#. Check that each of the following has been released: + * The `pulp_deb python package`_ on pypi.org. + * The `pulp-deb-client package`_ on pypi.org. + * The `pulp_deb_client Ruby Gem`_ on rubygems.org. + * This ``pulp_deb`` documentation. +#. (``Y`` version release only) Update the ``ci_update_branches`` variable in the ``template_config.yml`` file in the `pulp_deb source repository`_. +#. (optional) Run the "changelog update" action to add any release branch changelog commits to the main branch. + If you skip this, it will be picked up by the nightly CI. +#. Post a release announcement under `Pulp community forum announcements`_. + Hint: Simply copy and past from past release announcements making adjustments as necessary. -To generate an up to date ``template_config.yml`` file in the base of the ``pulp_deb`` repository, use: -.. code-block:: none +.. _using_the_plugin_template: - ./plugin-template --generate-config pulp_deb +Using the Plugin Template +-------------------------------------------------------------------------------- -You can adjust this configuration to affect the other plugin template commands. -For documentation on each parameter, see the `Pulp plugin template README`_. +For existing plugins, the `Pulp plugin template`_ is used to keep the plugin CI up to date and synchronized across all plugins. +Applying the latest plugin template is primarily performed via GitHub actions pipeline. +This pipeline is periodically run or can be triggered manually (for example before a new ``Y`` release). +The pipeline will open a PR against every branch listed in the ``ci_update_branches`` variable of the ``template_config.yml`` file of the ``pulp_deb`` source repository. --------------------------------------------------------------------------------- +It is also possible (and sometimes useful) to run the plugin template locally. +Make sure you clone the ``plugin_template`` repository in the same folder as the ``pulp_deb`` repository. +You can then issue the below template commands within the root of the plugin template repository to apply changes. -In order to apply the latest GitHub actions pipeline changes use: +.. important:: + The following commands are usually applied via the GitHub actions pipeline, which is the preferred way for creating the needed PRs. .. code-block:: none + ./plugin-template --generate-config pulp_deb ./plugin-template --github pulp_deb --------------------------------------------------------------------------------- - -In order to apply the latest documentation changes from the template use: +.. important:: + The following plugin template commands are primarily intended for creating the skeleton for a new plugin. + It sometimes makes sense to apply them to an existing plugin, but the applied changes will clash with the existing plugin content, and need to be manually evaluated. .. code-block:: none ./plugin-template --docs pulp_deb - --------------------------------------------------------------------------------- - -In order to apply a full plugin skeleton from the plugin template use: - -.. code-block:: none - ./plugin-template --bootstrap pulp_deb @@ -112,84 +110,3 @@ You can now find the built documentation at ``docs/_build/html/index.html`` with You can also find the API doc contents within ``docs/_static/api.json``. You can open the locally built documentation in a browser, but you will not be able to view the API docs, since those make use of an external service, that obviously has no access to your local build. - - -Plugin Release Process --------------------------------------------------------------------------------- - -The general release steps are maintained in the `pulpcore release guide`_ wiki article. -This article also includes clear hints how those steps should be interpreted for plugins. -The release process tends to experience some churn, so this guide should always be consulted as the most up to date, single source of truth. - -The following subsections collect ``pulp_deb`` specific hints and details, that go beyond the pulpcore release guide. - -.. note:: - The plugin is released to pypi.org as the `pulp_deb python package`_. - In addition a new `pulp-deb-client package`_ and `pulp_deb_client Ruby Gem`_ will be released. - Client packages based on the latest plugin ``main`` branch are also released daily. - See the :ref:`plugin template ` and the ``template_config.yml`` file for more information on daily client releases. - - -Updating the Release Branch CI -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -It is generally desirable to apply at least the latest GitHub actions :ref:`plugin template ` before *every* release. -This means applying the plugin template to the main branch, before new Y-release branches are created, and also applying it to existing release branches before performing Z-releases. -For the most part, the plugin template can be applied more or less blindly from its latest main branch. -However, around major pulpcore, or CI changes, or when applying the plugin template to very old release branches careful understanding and review is sometimes required. -The older the release branch, the more likely it is the ``template_config.yml`` on the branch needs to be adjusted before applying the template. - -For cherry-picking backports the ``.ci/scripts/cherrypick.sh`` script is used locally. -This will also be updated by applying the GitHub actions plugin template. - - -The pulpcore Deprecation Cycle -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -pulpcore will introduce breaking changes to the plugin API over a cycle of two ``Y`` releases. -Affected functions will be deprecated in some ``Y`` release, but will only be removed with the next ``Y`` release after that. -As a result, if we are releasing for the pulpcore ``3.8`` release, it should be safe to declare an upper bound of strictly smaller than ``3.10`` (up to and including ``3.9.*``). -This presupposes that we have already removed any dependencies on any deprecations announced for pulpcore ``3.8``. -See `pulpcore plugin API deprecation policy`_ for more information. - -The lower bound should be changed directly in the ``main`` branch whenever some change actually requires a newer pulpcore version. -Therefore it should not normally be necessary to raise this at release time (beyond what it already was in the ``main`` branch). - - -Release Steps -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Careful reading of the `pulpcore release guide`_ wiki article is currently the best way to perform up to date release steps. -If you find any mistakes in the wiki article, start a community discussion to suggest changes. - -.. note:: - Performing a ``pulp_deb`` release requires permissions to run the relevant `pulp_deb GitHub actions pipelines`_. - Closing the relevant `pulp_deb milestone`_ also requires permissions on the issue tracker. - Backport cherry-picks can be prepared by anyone who can open a ``pulp_deb`` PR. - -.. note:: - The release pipeline may run into trouble if issues are assigned to the wrong `pulp_deb milestone`_. - In such cases it is always possible to remove the problematic association and re-run the release pipeline (which is designed to be idempotent). - - -.. _release_announcements: - -Release Announcements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Currently, release announcements are posted as `Pulp community forum announcements`_. -The easiest thing to do is to copy and amend an existing announcement like this `example pulp_deb release announcement`_. - -Also send an email to the `Pulp project mailing list`_ (not to be confused with the `Pulp project development mailing list`_), that simply references the community announcement as follows: - -.. code-block:: none - - To: pulp-list@redhat.com - Subject: pulp_deb 2.14.1 is generally available - - Please see the community release announcement for more information: - https://github.com/pulp/community/discussions/71 - - Kind regards, - Quirin Pamp (quba42) - Software Engineer, pulp_deb plugin maintainer, ATIX AG