This part of the documentation is intended as an aid to current and future plugin maintainers.
Plugin Version Semantics¶
Release version strings of the
pulp_deb plugin use the following format:
X version release, signifies one or more of the following:
There are major new features.
There has been a major overhaul of existing features.
The plugin has entered a new stage of its development.
The plugin is compatible with a new pulpcore
X version release, is more of a high level “marketing” communication, than something with a detailed technical definition.
It is up to the judgement of plugin maintainers when a new
X version is warranted.
Y version release, signifies the following:
Yversion is the same, as the pulpcore-
Yversion that the release is for.
Yversion release is given its own release branch.
Yversion release may contain new features or any other type of change.
Yversion release is generally performed when a new pulpcore
Yversion has been released.
Z version release, signifies the following:
Zversion release may contain only bugfixes (semantic versioning).
Zstream changes are cherry-picked to the relevant
Yversion release branch.
Zstream changes may be released as soon as they are ready, and as needs arise.
Using the Plugin Template¶
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
You can then issue the below template commands within the root of the plugin template repository to apply changes.
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.
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
--github commands can mostly be committed in full (check for master versus main branch naming), while changes from the
--bootstrap commands may overwrite a lot of existing plugin code, but may sometimes add useful changes.
To generate an up to date
template_config.yml file in the base of the
pulp_deb repository, use:
./plugin-template --generate-config pulp_deb
You can adjust this configuration to affect the other plugin template commands. For documentation on each parameter, see the Pulp plugin template README.
In order to apply the latest GitHub actions pipeline changes use:
./plugin-template --github pulp_deb
In order to apply the latest documentation changes from the template use:
./plugin-template --docs pulp_deb
In order to apply a full plugin skeleton from the plugin template use:
./plugin-template --bootstrap pulp_deb
Building the docs and API docs¶
The content for the pulp_deb REST API documentation is extracted via API call to a running pulp instance. It will contain various docstrings from the plugin code as deployed to that instance. As a result, building the docs can only be done via the CI pipelines or a full fledged development environment.
This can be done within a
pulp3-source-* vagrant box from the
pulp_installer repository, that has the
pulp_deb plugin installed.
Within such a box run the following commands:
cd /home/vagrant/devel/pulp_deb/docs/ make html
You can now find the built documentation at
docs/_build/html/index.html within your local
You can also find the API doc contents within
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.
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 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 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
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
This presupposes that we have already removed any dependencies on any deprecations announced for pulpcore
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
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.
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
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).
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.
To: email@example.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