-
Notifications
You must be signed in to change notification settings - Fork 79
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #945 from ATIX-AG/release_process_docs
Update the plugin maintenance docs (cherry picked from commit b15bb1f)
- Loading branch information
1 parent
1c7fab9
commit a5a3a34
Showing
1 changed file
with
38 additions
and
121 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 <using_the_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 <using_the_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: [email protected] | ||
| 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 | ||