An improved workflow for maintaining Salt #96
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 |
|---|---|---|
| @@ -0,0 +1,256 @@ | ||
| - Feature Name: An improved workflow for maintaining Salt | ||
| - Start Date: 2024-11-14 | ||
|
|
||
| # Summary | ||
| [summary]: #summary | ||
|
|
||
| This RFC proposed an improved workflow for maintaining the Salt package for openSUSE/SUSE distributions, and therefore for Uyuni and SUSE Manager. | ||
|
|
||
| # Motivation | ||
| [motivation]: #motivation | ||
|
|
||
| Our current workflow for maintaining Salt requires manual user intervention after the changes are merged into our `openSUSE/salt` codebase, in order to make this changes available in OBS. Moreover, the Salt spec file and patches are tracked in a separated GitHub repository `openSUSE/salt-packaging`, that is also used to generate the changelog entries for the final RPM. | ||
|
|
||
| All these steps needs to be performed manually, with the help of some tooling, to eventually create a manual Submit Request to our Salt package in OBS. | ||
|
|
||
| With Salt Extensions appearing now in the upcoming Salt 3008 release, we want to introduce a new workflow that suits better and solves some the limitations we currently have. | ||
|
|
||
| The purpose of this RFC is: | ||
| - Define an new workflow for Salt that reduces user intervention to zero after a given PR is merged in `openSUSE/salt` repository until getting the package ready to consume at OBS. | ||
| - Make the Salt maintaining workflow aligned with openSUSE practices. | ||
| - Provide a workflow that can also work the same way with packaged Salt Extensions. | ||
| - Deprecate the usage of `salt-packaging` repository. | ||
|
|
||
| # Detailed design | ||
| [design]: #detailed-design | ||
|
|
||
| In this new workflow the `openSUSE/salt` GitHub repository will become the unique source of trust, and it will contain: | ||
|
|
||
| - Salt codebase | ||
| - Packaging artifacts: spec file, changelog and extra sources | ||
| - OBS workflow file | ||
|
|
||
| Taking inspiration from the [OBS/SCM integration guide](https://openbuildservice.org/help/manuals/obs-user-guide/cha-obs-scm-ci-workflow-integration), the new workflow will use OBS workflows and GitHub Webhooks to automate pulling the changes from GitHub to OBS. | ||
|
|
||
| In addition to this, as new Jenkins job will take care of making the OBS package ready to be submitted to openSUSE or SLE. | ||
|
|
||
| This is how the proposed OBS structure would look like: | ||
|
|
||
| - `systemsmanagement:saltstack/salt`: | ||
| * no services enabled - package ready to be submitted to openSUSE or SLE. | ||
| * linked to `systemsmanagement:saltstack:github/salt` | ||
| - `systemsmanagement:saltstack:github/salt`: | ||
| * services enabled | ||
| * package building based on `openSUSE/release/xxxx` GitHub branch. | ||
| - `systemsmanagement:saltstack:github:CI:...:PR-XXXX/salt`: | ||
| * services enabled | ||
| * package building according to PR branch. | ||
| * branched and removed automatically from `systemsmanagement:saltstack:github/salt` by OBS workflow. | ||
|
|
||
| The same OBS structure will apply these other OBS targets, allowing us to deal with different Salt versions if necessary ensuring the packages are also ready to be consumed, without enabled services that could run unexpectely on targets that are linked to them (like i.a. `systemsmanagement:Uyuni:Master`): | ||
| - `systemsmanagement:saltstack:products:testing` | ||
| - `systemsmanagement:saltstack:products:next` | ||
|
|
||
| For `systemsmanagement:saltstack:products` OBS target, it is not really necessary to follow the above structure, as this target gets updated once we run our "Salt Promote pipeline" (which does copypac whatever is in `products:testing` to `products`). | ||
|
|
||
| ### Packaging artifacts | ||
|
|
||
| All current extra "Sources" files in our RPM package, together with spec file and changelog file will go now to a `pkg/suse/` directory in `openSUSE/salt`: | ||
|
|
||
| ``` | ||
| pkg/suse/README.SUSE | ||
| pkg/suse/html.tar.bz2 | ||
| pkg/suse/salt-tmpfiles.d | ||
| pkg/suse/transactional_update.conf | ||
| pkg/suse/update-documentation.sh | ||
| pkg/suse/salt.spec | ||
| pkg/suse/salt.changes | ||
| ``` | ||
|
|
||
| This is the place now where all those files will be maintained. | ||
|
|
||
| #### Salt RPM changelog | ||
|
|
||
| As mentioned this is now at `pkg/suse/salt.changes` in `openSUSE/salt` GitHub repo. | ||
|
|
||
| When creating a PR to `openSUSE/salt` the user must also include the corresponding changes to the changes file, that can be generated as usual with `osc vc`. | ||
|
There was a problem hiding this comment. Does this work for the different changelogs we currently maintain in parallel? There was a problem hiding this comment. I missed to cover on the current proposal our requirement on maintaining different changelogs for the different target codestream we maintain. I'll add some more text to cover these cases. |
||
|
|
||
| Similarly to the main Uyuni repository, we should add a GitHub action to warn the user in case no changelog entry is added in the PR. | ||
|
There was a problem hiding this comment. Are we also merging the changelog like we do in Uyuni or do we need to resolve merge conflicts manually? |
||
|
|
||
| ### OBS project structure | ||
|
|
||
| #### `systemsmanagement:saltstack:github/salt` | ||
|
|
||
| This OBS package will only contain `_multibuild` file and a `_service` file that should look like: | ||
|
There was a problem hiding this comment. Can we have the There was a problem hiding this comment. Hmmm, indeed probably yes. I'll check and adjust this. |
||
|
|
||
| ``` | ||
| <services> | ||
| <service name="obs_scm"> | ||
| <param name="url">https://github.com/openSUSE/salt.git</param> | ||
| <param name="scm">git</param> | ||
| <param name="versionformat">@PARENT_TAG@</param> | ||
| <param name="versionrewrite-pattern">v(.*)</param> | ||
| <param name="revision">openSUSE/release/xxxx</param> | ||
| <param name="extract">pkg/suse/salt.*</param> | ||
| </service> | ||
| <service name="set_version" /> | ||
| <service name="tar" mode="buildtime"/> | ||
| <service name="recompress" mode="buildtime"> | ||
| <param name="file">*.tar</param> | ||
| <param name="compression">gz</param> | ||
| </service> | ||
| </services> | ||
| ``` | ||
|
|
||
| The rest of the files will be automatically pulled by the service, as they are enabled here. This package will be automatically refreshed by OBS at any new commit at `openSUSE/release/xxxx` branch. | ||
|
|
||
| #### `systemsmanagement:saltstack/salt` | ||
|
|
||
| This is our ready-to-consume OBS package. It is linked to `systemsmanagement:saltstack:github/salt`, but here we disable the services and manually run them to get the spec file, changelog and obsinfo/obscpio files, so the package can be submitted to openSUSE or SLE. | ||
|
|
||
| The `_service` file should look like: | ||
|
|
||
| ``` | ||
| <services> | ||
| <service name="obs_scm" mode="manual"> | ||
| <param name="url">https://github.com/openSUSE/salt.git</param> | ||
| <param name="scm">git</param> | ||
| <param name="versionformat">@PARENT_TAG@</param> | ||
| <param name="versionrewrite-pattern">v(.*)</param> | ||
| <param name="revision">openSUSE/release/xxxx</param> | ||
| <param name="extract">pkg/suse/salt.*</param> | ||
| </service> | ||
| <service name="set_version" mode="manual" /> | ||
| <service name="tar" mode="buildtime"/> | ||
| <service name="recompress" mode="buildtime"> | ||
| <param name="file">*.tar</param> | ||
| <param name="compression">gz</param> | ||
| </service> | ||
| </services> | ||
| ``` | ||
| And it should only contain the following files: | ||
|
|
||
| ``` | ||
| _multibuild | ||
| _service | ||
| salt-xxxx.obscpio | ||
| salt.changes | ||
| salt.obsinfo | ||
| salt.spec | ||
| ``` | ||
|
|
||
| Since services are disabled here, to allow submissions to openSUSE and SLE, this OBS package will be automatically synced with `openSUSE/release/xxxx` by a Jenkins job. | ||
|
|
||
| ### OBS and GitHub Webhook integration | ||
|
|
||
| As described in the [SCM/CI Workflow integration guide](https://openbuildservice.org/help/manuals/obs-user-guide/cha-obs-scm-ci-workflow-integration#sec-obs-obs-scm-ci-workflow-integration-setup-token-authentication-how-to-authenticate-obs-with-scm), a "GitHub Personal Access Token" must be created and a "GitHub Webhook" configure at `openSUSE/salt` repository. | ||
|
|
||
|
|
||
| #### OBS workflow file | ||
|
|
||
| A `.obs/workflows.yml` will be also added to `openSUSE/salt` to define the OBS workflow as the following: | ||
|
|
||
| ``` | ||
| main_workflow: | ||
| steps: | ||
| - branch_package: | ||
| source_project: systemsmanagement:saltstack:github | ||
| source_package: salt | ||
| target_project: systemsmanagement:saltstack:github:CI | ||
| filters: | ||
| event: pull_request | ||
|
|
||
| rebuild_master: | ||
| steps: | ||
| - trigger_services: | ||
| project: systemsmanagement:saltstack:github | ||
| package: salt | ||
| filters: | ||
| event: push | ||
| branches: | ||
| only: | ||
| - openSUSE/release/xxxx | ||
| ``` | ||
|
|
||
| This workflow will take care of: | ||
|
|
||
| - Setting up a new subproject at `systemsmanagement:saltstack:github:CI:...:PR-XXXX/salt` for every incoming PR to build the Salt package according to the changes in the PR. | ||
| - Triggering the services at `systemsmanagement:saltstack:github/salt` on any new push to `openSUSE/release/xxxx` to build the package accordingly. | ||
|
|
||
| ### Making OBS packages ready to be submitted to Maintenance | ||
|
|
||
| Since the package at `systemsmanagement:saltstack:github/salt` has "services" enabled, and we cannot enable/disable services using OBS workflows, this means this package is not yet ready to be submitted to openSUSE or SLE, as they don't accept enabled services on their submissions. We must disable the services. | ||
|
There was a problem hiding this comment. To me it sounds like a conceptual problem using services to sync the sources. An alternative we could at least look at is using src.opensuse.org as the git forge (according to https://openbuildservice.org/help/manuals/obs-user-guide/cha-obs-scm-bridge#sec-obs-obs-scm-bridge-update-notifications this does not require a _service to sync the sources) There was a problem hiding this comment. Hmmm, interesting. I'll give it a try 👍 |
||
|
|
||
| In order to do this we will use an Jenkins job that monitors when a new build is done at `systemsmanagement:saltstack:github/salt` to trigger the following actions at the main `systemsmanagement:saltstack/salt` package: | ||
rjmateus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ``` | ||
| # osc checkout systemsmanagement:saltstack/salt | ||
| # cd systemsmanagement:saltstack/salt | ||
| # osc service manualrun | ||
| # osc commit -m "Push new changes from GitHub" | ||
| ``` | ||
|
|
||
| This way, we ensure `salt.spec` and `salt.changes` and obscpio/obsinfo files gets upgraded according to latest changes. | ||
|
|
||
| ### Proof-of-Concept | ||
|
|
||
| I've implemented this structure and automation here: | ||
|
|
||
| - GitHub repository: https://github.com/meaksh/salt/ (`openSUSE/devel/master` branch) | ||
| - OBS: | ||
| * https://build.opensuse.org/package/show/home:PSuarezHernandez:tests/salt | ||
| * https://build.opensuse.org/package/show/home:PSuarezHernandez:tests:github/salt | ||
| * https://build.opensuse.org/package/show/home:PSuarezHernandez:tests:github:CI:....:PR-XX/salt | ||
|
|
||
| - Example PR: | ||
| * https://github.com/meaksh/salt/pull/10 | ||
| * https://build.opensuse.org/package/show/home:PSuarezHernandez:tests:github:CI:meaksh:salt:PR-10/salt | ||
|
|
||
| Feel free to open new PRs against `openSUSE/devel/master` to see this in action. | ||
|
|
||
| ### Salt Extensions | ||
|
|
||
| #### Builtin extensions | ||
|
There was a problem hiding this comment. This has been part of the other RFC, but for me it's still not so clear that we can have "builtin extensions". How do we publish these to PyPI from the main repository? How do we get them to show up on https://extensions.saltproject.io/? |
||
| The sources for the builtin Salt Extensions will be located together with the main Salt codebase at the `openSUSE/salt` GitHub repository. No new packages or subpackages will be created for these extensions as they will be part of the main `python3*-salt` package. | ||
|
|
||
| If a fix is needed for any of the builtin extensions, workflow would be the same as for a code fix in the main Salt package. | ||
|
|
||
| #### Packaged Salt Extensions | ||
rjmateus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| For the Salt Extensions that are packaged separately from the main Salt package, we will create a separated GitHub repository where we will maintain these extensions. | ||
|
|
||
| This "openSUSE/salt-extensions" repository will contain: | ||
| - a common salt-extension spec file that will generate all RPM packages | ||
rjmateus marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - The sources for each Salt Extension we package | ||
| - A changelog file | ||
| - OBS workflow file | ||
|
|
||
| When it comes to OBS, we will use the same SCM integration and OBS subprojects schema than the proposed for the main Salt codebase. Unique workflow for Salt and Salt Extensions. | ||
|
|
||
| - PoC: | ||
| * https://github.com/meaksh/test-repo-1 | ||
| * https://build.opensuse.org/package/show/home:PSuarezHernandez:tests/salt-extensions | ||
|
|
||
| - Example PR: | ||
| * https://github.com/meaksh/test-repo-1/pull/6 | ||
| * https://build.opensuse.org/project/show/home:PSuarezHernandez:tests:github:CI:meaksh:test-repo-1:PR-6 | ||
|
|
||
| NOTE: We are using a single GitHub repo and single OBS package which provides all different salt-extensions RPM packages. This is preferred against having a separated GitHub repositories and OBS package for each Salt Extension, as it will reduce the number of submissions, maintenance incidents and resources needed. | ||
|
|
||
| # Drawbacks | ||
| [drawbacks]: #drawbacks | ||
|
|
||
| - A bit more complex OBS structure than the current one. Including `obs_scm` service. | ||
| - Having to still rely on Jenkins to get the packages ready to be released. | ||
|
|
||
| # Alternatives | ||
| [alternatives]: #alternatives | ||
|
|
||
| 1. Stick to our current workflow based on "salt-packaging" -> The workflow doesn't currently fit with Salt Extensions and we don't want to have different workflows between Salt and Salt Extensions. | ||
| 1. One dedicated GitHub repository and OBS package per each Salt Extension -> It won't save resources and will cause more submissions. | ||
| 2. The usage of "git submodules" as an alternative to adding the Salt Extensions sources manually would make it tricky to generate patches manually and also to integrate with "obs_scm". | ||
|
|
||
| # Unresolved questions | ||
| [unresolved]: #unresolved-questions | ||
|
|
||
| TBD | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just to make is clear, any patch that we want to apply on top of salt code base should go to this folder
pkg/suse/right?So basically you are moving all the content from the github project
openSUSE/salt-packaging(subfolder salt) to this noewpkg/susefolder (at the start we will not have patches since we start from the same base as upstream)?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not really. We won't be carrying patch files anymore in our new OBS packages, as any code change will automatically inside the source tarball by the
obs_scmintegration.The exception to this would be EMBARGOED bugs, where we cannot proceed publicly via GitHub, so we will put a patch file manually in IBS than will be removed the bug is public and we push the changes to GitHub.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A side question; currently, we have a lot of commits that are not in upstream, due to various reasons. With
salt-packaging, we can easily check which patches are in upstream, and which patches are not. With removing the patch workflow, we're losing this insight.Do you perceive this as a problem? Are we still sticking with the "fork & cherrypick commits" development style, or are we moving towards rebasing more frequently?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a good point! We should probably want to have a way to easily identify what is upstreamed and what is not.
I'll elaborate this a bit on the RFC text. Thanks for the note 👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thank you @m-czernek , that was exactly my concern when I made the comment. Commits that are not yet upstrem, and currently are maintained on salt-packaging project.
We we start merging commit to our salt project that are not merge upstream yet, it can make it harder to integrate upstream version and know what is merge already or not.
@meaksh thank you for look into this topic.