RFC: the perfect release process

[evgeni]

RFC: the perfect release process

Decision Due Date: 2025-09-09

Context and Problem Statement

Usually, a release process consists of the following steps:

1. decision a release is due
2. preparation of release metadata (version bump, changelog, contributors etc)
3. storing the release in VCS (commiting the metadata, creating a tag)
4. creating of release artifacts (gem etc)
5. publishing release artifacts (rubygems.org, GH release)
6. notifying downstream consumers of the release (mail/blog/social announcement, packaging)

Ideally, most of these steps can be automated and human interaction is only needed to kick off the process (pipeline) and verify the steps were executed as expected.

The Foreman ecosystem consists of many projects, in different languages, and with different (release) workflows. This makes performing releases complicated and increases reliance on selected persons who know how to do them.

Proposal

To improve the current situation, the following changes are proposed:

1. the release process is documented in a dedicated file – release.md or releasing.md in either the repository root or in the documentation subfolder:
   • docs/releasing.md of foreman-ansible-modules
   • release.md of kafo
2. there is a single command to prepare the release metadata
   • optionally automated like prepare_release of voxpupuli which updates the version, generates a changelog and opens a PR
3. creating and publishing the release artifacts happens via GitHub Actions
   • Ruby projects use voxpupuli/ruby-release to build the gem and publish it to rubygems.org using Trusted Publishing when a tag is pushed
   • Python projects use pypa/gh-action-pypi-publish to pypi.org using Trusted Publishing when a tag is pushed
   • Puppet Module projects use voxpupuli/gha-puppet/release.yml when a tag is pushed
   • release.yml of foreman-ansible-modules builds the collection and publishes it to Ansible Galaxy and GH Releases when a tag is pushed

Many Ruby projects already implement publishing via GitHub Actions, but are still using the less secure method of authentication with an API token. Updating those to Trusted Publishing should require very small changes.

Implementing a single command for release preparation can be challenging, depending on the actual project workflows, so we should aim to implement documentation and publishing first.

Decision Outcome

• A project MUST document its release process
• The release documentation SHOULD be in the repository itself using RELEASE.md
• The release documentation SHOULD NOT be in the released artifact.
• A project SHOULD publish artifacts using GitHub Actions
• If the project publishes artifacts using GitHub Actions, the workflow file MUST be called .github/workflows/release.yml
• A project MAY implement a single-command release process so developers can run make release VERSION=x.y.z

To make it easier for projects, the Foreman project as a whole MUST provide a list of recommended GitHub Actions to publish artifacts.

MUST/SHOULD/MAY as described in RFC2119.

We implement “release documentation” and “GitHub Actions publishing” in 2025, with “single-command release process” being a long-term goal of the project.

Impacts

This proposal applies to all repositories in the theforeman, Katello, Apipie, dynflow, RedHatSatellite, dm-drogeriemarkt and markt-de organizations that regularly produce artifacts.

We’ll create a GitHub project board to track this, and either Redmine or GH issues (depending on the project) for the documentation and publishing tasks. Maintainers, and everyone else who wishes to contribute, please pick up these and help us improve the release process. Ideally we can implement those changes by the end of 2025.

[ekohl]

First of all, for this effort.

@evgeni

the release process is documented in a dedicated file – release.md or releasing.md in either the repository root or in the documentation subfolder:

Yes please. Documenting the steps is the first step to automating them.

Over time I wouldn’t mind having some common process documented somewhere (like on theforeman.org) and the release.md file just points to that.

Some implementation detail: I’d prefer not to have this file end up in release artifacts (like gems). Otherwise we need to deal with it in packaging (RPM/deb). There’s also a tiny saving on size (both storage and transfer).

@evgeni

there is a single command to prepare the release metadata

I suggested this in the past:

Standard tool to do version bumps

Hello everyone, I’d like to introduce tooling to do version bumps of projects. Currently we have a lot of projects that do bumps in slightly different ways. By using a tool that has config in the projects git repository it’ll be standardized. Personally I like bump2version. Maybe because I’m one of the maintainers or that it’s packaged in Fedora. Either way, you can add a config: Then it’s simply bumpversion patch (or minor/major). My question is: which tool do people prefer.

@evgeni

Many Ruby projects already implement publishing via GitHub Actions, but are still using the less secure method of authentication with an API token. Updating those to Trusted Publishing should require very small changes.

I’ve already removed all API tokens from our own theforeman account and converted workflows where needed.

[ehelms]

@evgeni

the release process is documented in a dedicated file – release.md or releasing.md in either the repository root or in the documentation subfolder:

• docs/releasing.md of foreman-ansible-modules
• release.md of kafo

I would prefer a single file name. There is a mix of usage currently, but that can be fixed over time. If the goal is standardization, then let’s make the spec aim for that.

@evgeni

there is a single command to prepare the release metadata

• optionally automated like prepare_release of voxpupuli which updates the version, generates a changelog and opens a PR

Do you mean a single command that is the same command across all repositories?

[evgeni]

@ehelms

I would prefer a single file name. There is a mix of usage currently, but that can be fixed over time. If the goal is standardization, then let’s make the spec aim for that.

I was aiming for fewer “rename” commits, but if everyone can agree on a single name…

@ehelms

Do you mean a single command that is the same command across all repositories?

Ideally, yes. In most cases a make release VERSION=1.2.3 that wraps language-specific-tool-of-the-day would be perfect.
But having a repo-specific single-command would also be great (as people should look at the docs anyway )

[ehelms]

@evgeni

I was aiming for fewer “rename” commits, but if everyone can agree on a single name…

I like defining a standard and aiming towards it – RELEASE.md with a CHANGELOG.md sounds good.

@evgeni

Ideally, yes. In most cases a make release VERSION=1.2.3 that wraps language-specific-tool-of-the-day would be perfect.
But having a repo-specific single-command would also be great (as people should look at the docs anyway )

This sounds like:

1. Have a project preference that is stated as make release VERSION=1.2.3
2. Have a project requirement that the process must be documented

[ekohl]

My RFC2119 style requirements:

• A project MUST document its release process
• The release documentation SHOULD be in the repository itself using RELEASE.md
• A project SHOULD publish artifacts using GitHub Actions
• A project MAY implement a release process so developers can run make release VERSION=x.y.z

To make it easier for projects, the Foreman project as a whole MUST provide a list of recommended GitHub Actions to publish artifacts.

[evgeni]

@ekohl

To make it easier for projects, the Foreman project as a whole MUST provide a list of recommended GitHub Actions to publish artifacts.

Where would we document such things? As part of the @theforeman/actions readme?

[ekohl]

I didn’t want to prescribe that. I was thinking more about theforeman.org in some developer focused guide.

[evgeni]

Thanks, updated the “outcome” section with your wording

[aruzicka]

Where would this put string extraction and pulling from transifex in repos where that’s appropriate? Is that expected to be included in step 2 or is will it be left to the person doing the release to be done manually as it can in theory be done at any time?

[evgeni]

Right now (the way it’s written, or rather, not explicitly written), translations are “just another feature PR” that need to be merged before the release train starts.

If I’d be king (and y’all should be glad I am not), I’d make the “upload strings to translation service” a continuous thing (= happens on every push to the main branch) and “pull new translations from the translation service” would be a (weekly?) cron-based PR.

Some translation services even support direct pushing into Git when translators save, but I am not sure I like that (esp as we need to generate JS-stuff from the translation files).

[ekohl]

@evgeni

If I’d be king (and y’all should be glad I am not), I’d make the “upload strings to translation service” a continuous thing (= happens on every push to the main branch) and “pull new translations from the translation service” would be a (weekly?) cron-based PR.

We already have an automatic poll in Transifex that polls the locale/$domain.pot file.

This means you can could set up a cron-based PR to update the translation strings easily. One complexity is that every now and then we ask Red Hat’s translators to update the translations for officially supported languages for code shipped in Satellite. We do this by syncing Transifex to some other system used by Red Hat. Once they’re done the updated translations are synced back into Transifex. If we start updating strings in between I’m not sure how that would work. Normally this is why you have a string freeze period, but with plugins having their own release cycles it’s a bit harder.

My hope is that we first write down the process(es) we have today and then try to optimize them.

[ehelms]

@evgeni

Decision Outcome

This reads really good to me now. ACK

[evgeni]

I’d like to extend the proposal to have:

• If the project publishes artifacts using GitHub Actions, the workflow file MUST be called .github/workflows/release.yml

[evgeni]

Should this RFC also apply to repositories in the ATIX-AG, dm-drogeriemarkt and markt-de namespaces?

cc @Bernhard_Suttner @nadjaheitmann @TimoGoebel @ochnerd @fraenki

[ochnerd]

@evgeni I think this would be a good idea for everybody. So that the plugins are consistent. We already switched to Trusted Publishing when it was proposed, because it is easy to implement and automates the publishing.

I try to add a RELEASE.md to our projects when i have time.

[fraenki]

I’ll try to implement these suggestions for markt-de/foreman_ovirt in 10/2025

[evgeni]

Thanks everyone! As the date is passed and we’ve had only positive (and clarifying!) feedback, this RFC is accepted.

I’ll prepare the tracking stuff in the next couple of weeks, but you can of course implement things faster than me!

[Bernhard_Suttner]

From my side, I think this make totally sense. Thank you vey much.

@nadjaheitmann Some more thoughts from your side?

[nadjaheitmann]

Thanks @evgeni I appreciate the effort and I think it is a good idea to unify the process for all Foreman plugins. We are already using trusted publishing in most of our repos - works very well!