Skip to content

Salt package versioning #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vzhestkov wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Salt package versioning #111

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
43fafeb
Salt package versioning
vzhestkov Oct 15, 2025
6b76477
Update accepted/00000-salt-package-versioning.md
vzhestkov Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions accepted/00000-salt-package-versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
- Feature Name: Salt packages versioning
- Start Date: 2025-10-15

# Summary
[summary]: #summary

We are releasing our branch of Salt with its original version (currently `3006.0`) without any changes in version number with each next release.
This approach is causing some confusions on detecting the exact salt code used with the package as the `release` of the packages, delivered
for different clients can't be aligned and is not reliable. The only reliable for now is the data from the package changelog.

The aim of this RFC is to improve the visibility of the state of the salt code released with each maintenance update.

# Motivation
[motivation]: #motivation

- We need to have clear way to identify the exact salt code used with the salt packages as the release number is not reliable.
- There were some issues detected for the cases when the outdated salt is used either on `salt-master` or `salt-minion` side, but such cases are hard to identify as the only reliable data is the changelog of the package.
- Make it easier to ensure that newer version of Salt is used on the `salt-master` side by enforce preventing adding higher `salt-minion` version to bootstrap repos.
Copy link
Member

@rjmateus rjmateus Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not just Bootstrap repositories, but alsothe client tools repository. The bootstrap repo is the first obvious issue, but user can apply all the updates after registration, and if the package is available, it would lead to the same issue.

- Unify the same approach for classic salt package used on the `salt-master` side and for the salt bundle to make the check, if the versions aligned, clear for the supporters and the users.

# Detailed design
[design]: #detailed-design

With each salt version bump we are using certain version from upstream Salt, like `3006.0` now (before we had `3004`, `3002.2`, `3000` etc.).
While backporting the fixes and adding the features we are releasing Salt packages with each maintenance update without chaning the version of the packages.
The only changing part is the `release` of the package, but it depends on the project where it was building and there is no any alignment possible.

To avoid the confusions and better tracking the alignment of the package version across different targets for classic salt package and the salt bundle,
we could extend the version of the package with the patch level like `MAJOR.MINIOR.PATCH` instead of `MAJOR.MINOR` which is used now.

The patch level could be either increased manually on each maintenance update submission or adjusted automatically on the build time with the current number of patches included.
Copy link
Member

@rjmateus rjmateus Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have a suggestion on which approach should be followed? Automating can avoid one manual step before releasing, but it can be less reliable if, for some reason, we remove some patches (I know it can be hard to imagine now).
Also, we would need to adapt it when moving to git workflow.
I would vote for manually incrementing it since we already need to make some changes by merging the change logs, right?

Copy link
Member

@agraul agraul Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The version should probably be unrelated to the number of patches and be updated "manually". In #105 we propose to stop applying patches at build time and use a newer openSUSE/salt checkout (via a git submodule or via a tarball downloaded from github.com), which would still work with a "manual" patch level bump.

I put "manual" in quotes because I'd still automate it. I would do it when $user (which could be a bot) updates Salt packaging sources in OBS / src.opensuse.org


With such approach we would have constantly increasing version number and the content of each package release will be easier to identify.

The examples of new versions to be released:
`3006.0.1`, `3006.0.2`, `3006.0.3` ... `3008.0.0` - in case of manual version increase
`3006.0.179`, `3006.0.180`, `3006.0.183` ... `3008.0.25` - in case of alignment with the numbers of patches included

The suggestion with the number of patches could be not relevant in case of switching to git workflow with the packaging,
in this case as an alternative we can check if we can use the amount of commits between the latest one and the original for the certain version.
Copy link
Member

@agraul agraul Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Counting commits has a problem when we have differences between package git (e.g. pool/salt) on the internal vs external git forge or different branches. Like we have now if we want to compare the number of changelog entries between different OBS/IBS projects.


This way of package versioning could improve the process of creating the bootstrap repositories for different types of the clients as
the salt packages in the bootstrap repos could be checked to prevent populating the bootstrap repositories with the salt package versions higher
than used on the salt-master side.

The suggested way of versioning by adding patch level to the version number does not require ECOs for each next version bump, except the case,
when major or minor part of the version is changing. In this case, only single request to add salt package to the list of the packages that may
receive version updates without ECO is required.

# Drawbacks
[drawbacks]: #drawbacks

Why should we **not** do this?

* slightly increase the complexity of submitting new maintenance update, but can be mitigated by automation with either RPM macro or OBS service
* in case of manual version increase could affect the speed of preparing the submission
* with manual version increase could cause issues due to the typos or not expected values of the version

# Alternatives
[alternatives]: #alternatives

- Leave the package versioning as it is now
- Add extra pre-defined prefix for the `release` of the package, but prefixes are already used there, so it could cause way too long `release` section.
- Use metadata fields instead of adding patch level to the version number, for example with `Provides` field, but it doesn't provide enough visibility and bit more complex to implement as requires parsing package metadata each time when we need to compare packages.

# Unresolved questions
[unresolved]: #unresolved-questions

- It's not clear how to align it with git workflow integration for OBS.
Copy link
Member

@agraul agraul Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The git workflow does not need to change the approach, but it probably changes how it's implemented.

Right now we have salt.spec in openSUSE/salt-packaging and can update the patchlevel in PRs that add/modify/remove patches.

In the future, we plan to have salt.spec in openSUSE/salt and update it there when we fix bugs / add features. In that repo we could have a version bump, together with a git tag at the time we (either a human or a bot) prepare a submission.

- What should we do with the old product versions which are not using any conditions for adding the new versions of the bundle to the bootstrap repositories?
Copy link
Member

@rjmateus rjmateus Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When we update the code that generates the bootstrap script we may need to backport it to all supported versions. I'm not expecting that it would be too difficult.

Copy link
Member

@agraul agraul Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to change the bootstrap script at all?

This goes into the "how do we use the Salt version" part that's covered briefly above. I think we still need to discuss the details on how we want to make sure that clients never see incompatible updates.

Personally I don't like that we're enforcing the update of the master first when it's not required, but I that's the trade-off when we use our own patch level instead of e.g. the transport version that I proposed in uyuni-project/uyuni#10639

For the mechanism, I would pick one that's on 100% the Server side, i.e. the download repositories that Uyuni provide don't include Salt Bundle packages with versions higher than the currently running Salt Master. To get there, we can either filter when we sync channels (reposync) or later when we create the download repository (mgr-create-bootstrap-repo and Java's repository generator). We need more information on both approaches (upsides/downsides) to decide which is a better fit.