Skip to content

Packaging Overview

Jump to bottom
Alexander Graul edited this page Feb 22, 2024 · 13 revisions

Our Salt packages are done in the "SUSE traditional way", where patch files are inside the RPM source package. In the past it was not possible to generate a tarball from this repository, because the package must provide an original .tar.gz source tarball and apply patches on top of it. We still stick to that workflow as it helps with showing what's coming from us vs what's coming from upstream.

Since the diff between the upstream tarball and in our openSUSE/salt repository can be quite large, we maintain a separate repository with generated .patch files. These are generated manually with the help of git-format-pkg-patch

An overview of the Salt Packaging workflow can be seen in the diagram below.

Build Service Projects

There are two main code streams that we need to handle:

  1. Latest & greatest Salt for openSUSE Tumbleweed
  2. Tested & stable Salt for openSUSE Leap / SUSE Linux Enterprise (SLE)

For openSUSE Tumbleweed we have a devel project systemsmanagement:saltstack that receives SRs, mostly independent of our other projects. Due to the factory-first policy, we need to make sure to update this package and send an SR to openSUSE:Factory before anything gets submitted to SLE. openSUSE Leap does not have it's own copy of Salt, it gets it from the SLE codestream.

For Uyuni / Leap / SUMA / SLE (all get what's in "production", albeit from different codestreams with different changelogs) we have a few projects, ordered by stability in descending order:

  1. "production": systemsmanagement:saltstack:products
  2. "testing": This version is being tested and will move to "production" once all tests pass systemsmanagement:saltstack:products:testing
  3. "next": This version is a testbed. It might move to "production" (via "testing") + Tumbleweed, or it might be replaced. systemsmanagement:saltstack:products:next
  4. "next testing": This version is for testing before it moves to "next". systemsmanagement:saltstack:products:next:testing

Since there are so many projects and it is easy to forget which Salt version is being built in each project, we have a small tool that queries OBS: saltversions.

"Promoting" packages from systemsmanagement:saltstack:products:testing to systemsmanagement:saltstack:products is done with the use of a Jenkins pipeline. The workflow is documented in How to promote Salt packages.

From Pull Request to Package

Once a Pull Request is merged, there are still a few steps needed to get the change into Salt packages. As the image above shows, our packages are based on the upstream release tarballs with added .patch files, that change the source code in the package build process. These patches are maintained kept in openSUSE/salt-packaging.

Simple Patch

This example shows how you can integrate a merged Pull Request targeting openSUSE-3002.2 into the Salt package in systemsmanagement:saltstack:products. Remember that all changes go through the :testing subproject!

  1. Create a Patch using openSUSE/git-packaging-tools 
cd ~/src/salt
mkdir patches && cd $_
git-format-pkg-patch --format v3006.0-suse # important: directory must be empty!
  1. Copy the Patch into your local salt-packaging repository
cd ~/src/salt-packaging/salt
git switch 3006.0
git pull --ff
git-format-pkg-patch --update ~/src/salt/patches
  1. Adapt salt.spec:
  • At the bottom of the list of Patch<N>, add a comment with the link to the upstream PR:# PATCH-FIX_UPSTREAM: https://github.com/saltstack/salt/pull/123, where N is the number of the last patch that's already listed
  • Add Patch<N+1>: name-of-patch.patch
  1. Commit the changes. Important: The commit message is will be turned into a changelog entry. Regular commit message etiquette does not apply here.
  2. Push the new commit to openSUSE/salt-packaging.
  3. Branch systemsmanagement:saltstack:products:testing/salt with osc:
cd ~/obs
osc bco systemsmanagement:saltstack:products:testing salt # bco = branch + checkout
cd home:$geeko:branches:systemsmanagement:saltstack:products:testing/salt
  1. Use our obs source service to pull the latest patches from GitHub:
# Install necessary services
sudo zypper in obs-service-extract_file obs-service-download_url obs-service-salt_bundle_patches
# Install https://github.com/openSUSE/obs-service-update_changelog before you continue
osc service runall
osc status # check that salt.spec and salt.changes are marked as modified
  1. Track the new patch and verify the changes:
osc add name-of-patch.patch
osc diff
  1. If everything looks good, the change can be committed into OBS:
osc commit
# wait while OBS builds the package after the latest modification, then check build results
osc results
  1. If the build is successful, you can open a Submit Request (SR). By default, the SR will target the project you have branched from:
osc sr
  1. You are done! Someone else will review and (hopefully accept) your SR!

Submit Requests differ from GitHub's Pull Request in one big way: You can't change them once opened. If you want to change an SR, you need to open a new one. Use osc sr --supersede <old request id> to indicate that the new SR replaces the old one.

Salt Bundle (venv-salt-minion) patches

The same workflow described above applies when pushing new patches to venv-salt-minion package at obs://systemsmanagement:saltstack:bundle:testing.

In this case, there is an special OBS service to do the necessary changes to the "venv-salt-minion.spec" file and include the new patches. You need to install this custom OBS service which is provided here: https://build.opensuse.org/package/show/home:vzhestkov:obs-services/obs-service-salt_bundle_patches

New Release

TODO

Update Documentation

The salt-doc package is one of the subpackages built from salt.spec file.

The content of this package is provided in the html.tar.bz2 tarball that we have in the "salt" OBS/IBS packages together with the rest of the files. For example here: https://build.opensuse.org/package/show/systemsmanagement:saltstack:products/salt

This tarball is not generated during build time of the package, and therefore we need to take care of updating the content at least when we do a major version update to Salt.

To regenerate the html.tar.bz2 simply execute the update-documentation.sh script that we have in OBS as follows:

# sh update-documentation.sh salt-maintainers@suse.de --without-sphinx

This will update the html.tar.bz2 based on the current state contains the generated documentation.

Clone this wiki locally