diff --git a/doc/obs_integration.md b/doc/obs_integration.md deleted file mode 100644 index 19c91a8ea..000000000 --- a/doc/obs_integration.md +++ /dev/null @@ -1,215 +0,0 @@ -# The Open Build Service (OBS) Integration - -- [The Open Build Service (OBS) Integration](#the-open-build-service-obs-integration) - - [Development Project](#development-project) - - [Releasing a New Version](#releasing-a-new-version) - - [OBS Synchronization](#obs-synchronization) - - [Details](#details) - - [Synchronizing GitHub Fork with OBS Branch](#synchronizing-github-fork-with-obs-branch) - - [OBS Branch](#obs-branch) - - [GitHub Fork](#github-fork) - - [Configuring the GitHub Actions](#configuring-the-github-actions) - - [Triggering the Rebuild](#triggering-the-rebuild) - - [Devel Package Versioning](#devel-package-versioning) - - [Release Project](#release-project) - - [Release Package Versioning](#release-package-versioning) - ---- - -The Agama installer packages are built in the openSUSE [Open Build Service]( -https://build.opensuse.org/). - -## Development Project - -The [systemsmanagement:Agama:Devel](https://build.opensuse.org/project/show/systemsmanagement:Agama:Devel) -contains the latest packages built from the `master` Git branch. This project -contains unstable development version of Agama. It is intended for development -and testing. - -The packages are automatically updated whenever the `master` branch is changed -or when a new version is released. See more details below. - -## Releasing a New Version - -For releasing a new version just create a new version tag. The process is then -fully automated. See more details in the [Packaging documentation]( -../PACKAGING.md#bumping-the-version). - -## OBS Synchronization - -The automatic OBS synchronization is implemented using the [GitHub Actions]( -https://github.com/features/actions). The actions are defined in the -`obs-staging-*.yml` files in the [.github/workflows](../.github/workflows) -directory. - -Because the process of updating a package is the same for several packages -the definition is shared in the [obs-staging-shared.yml]( -../.github/workflows/obs-staging-shared.yml) file. - -The packages in the devel project are updated only when a respective source -file is changed. That saves some resources for rebuilding and makes -synchronization faster. But that also means the packages might not have exactly -the same version. - -The project to which the packages are submitted is configured in the -`OBS_PROJECT` GitHub Actions variable. - -### Details - -The packages in OBS are updated by running the OBS service which downloads the -sources from GitHub and dependencies from other repositories (Rust or NPM -packages). - -The process of updating a package is basically: - -- `osc co systemsmanagement:Agama:Devel ` - checkout the package - from OBS -- `osc service manualrun` - update the sources and dependencies by running - the OBS services locally -- `osc commit` - upload the changes to the OBS server, it will rebuild the - updated package automatically - -To run the services locally you need to install the OSC tool and several -packages with the used OBS services: - -```shell -zypper install osc obs-service-cargo_audit obs-service-cargo_vendor \ - obs-service-download_files obs-service-format_spec_file obs-service-obs_scm \ - obs-service-node_modules -``` - -The `rubygem-agama` package uses a different approach because the Ruby packages -use `*.gem` files which are not supported by OBS services. It uses the -[osc:commit](https://github.com/openSUSE/packaging_rake_tasks#osccommit) Rake -task, same as the YaST packages. - -## Synchronizing GitHub Fork with OBS Branch - -It is possible to synchronize your GitHub fork with your OBS brach -automatically. This allows easily build your own updated packages or even the -Live ISO. - -### OBS Branch - -First you need to create an OBS project where the packages will be built. - -The easiest way is to branch the Agama package which you want to modify from the -[systemsmanagement:Agama:Devel]( -https://build.opensuse.org/project/show/systemsmanagement:Agama:Devel) -repository. This will inherit the repository setup for building the packages, -images and containers. - -``` shell -osc branch systemsmanagement:Agama:Devel agama-web-ui -``` - -This will create `home:$OBS_USER:branches:systemsmanagement:Agama:Devel` -project where `$OBS_USER` is your OBS account name. This `$OBS_USER` placeholder -is also used in the following text. - -By default the project will build packages and ISO images for all architectures. -But if you want to test the packages on a single architecture then it is a good -idea to remove the other architectures and save some OBS build power. - -To remove all architectures except the x86_64 run this command: - -``` shell -osc meta prj home:$OBS_USER:branches:systemsmanagement:Agama:Devel | \ -sed "/aarch64<\/arch>/d;/i586<\/arch>/d;/ppc64le<\/arch>/d;/s390x<\/arch>/d;" | \ -osc meta prj -F - home:$OBS_USER:branches:systemsmanagement:Agama:Devel -``` - -The branched package is still linked to the original package. This might cause -conflicts after the original package is updated. To avoid this problem you -should detach the branched package from the original repository: - -``` shell -osc detachbranch home:$OBS_USER:branches:systemsmanagement:Agama:Devel agama-web-ui -``` - -If you want to also build the Live ISO from your modified packaged then you need -to branch (and detach) also the `agama-installer` package: - -``` shell -osc branch systemsmanagement:Agama:Devel agama-installer -osc detachbranch home:$OBS_USER:branches:systemsmanagement:Agama:Devel agama-installer -``` - -*Please delete your branched OBS project once you do not need it anymore, it -will save quite some OBS build power.* - -### GitHub Fork - -Then you can fork the [Agama](https://github.com/openSUSE/agama) repository at -GitHub. - -When creating a fork GitHub by default copies only the `master` branch. It does -not copy the other branches nor tags. The code supports this option, just be -prepared that the package versions might be different than in the original Agama -OBS repository because the tags are used to get the version number. If tags are -missing the version will be set to the commit Unix time stamp followed by a -short commit hash. - -If you want to have similar versions as the original packages then create a full -fork including all branches and tags (unselect the "Copy the master branch only" -option). - -### Configuring the GitHub Actions - -The GitHub Actions needs some configuration to allow the automatic submission. - -1. Go to the Settings -> Secrets and variables -> Actions -> New Repository - Secret option in your Agama GitHub fork. Create two secrets with names - `OBS_USER` and `OBS_PASSWORD` and set them to your OBS credentials. - - Tip: If you do not want to put your credentials for your main OBS account - to GitHub then you might create a new separate testing OBS account. - -2. Switch to "Variables" tabs and click "New Repository Variable". - Create `OBS_PROJECT` variable with name of your OBS branch project - ("home:$OBS_USER:branches:systemsmanagement:Agama:Devel"). If the variable - is not created or is empty the autosubmission is disabled. - -3. Enable the GitHub Actions in the "Actions" tab. - -### Triggering the Rebuild - -*The autosubmission only works in the `master` branch in your fork, not in any -other branch!* - -To trigger an update and rebuild of your package with the new sources just push -a commit to the `master` branch. - -Alternatively you can trigger the package submission manually. Go to the -"Action" tab in GitHub, select the respective "Submit" action in the left side -bar and in the main area click the "Run workflow" selector. Then in the popup -keep the default `master` branch and click the "Run workflow" button. - -### Devel Package Versioning - -The packages in the Devel project use a version built from the last released -version with a number of commits in the `master` branch since that release. - -The version is automatically constructed by the OBS service, for the -`rubygem-agama` package the version is built using the `git describe --tags` -command. - -## Release Project - -For relasing a public version of Agama we use the -[systemsmanagement:Agama:Release]( -https://build.opensuse.org/project/show/systemsmanagement:Agama:Devel) project -and respective [release](https://github.com/agama-project/agama/tree/release) -branch in Git. The reason for a separate project is that we might need to -release a hot fix but the `master` branch might already contain a new feature -for the next version. - -The integration works the same way as for the Devel project above, the only -difference is that it uses the `OBS_PROJECT_RELEASE` GitHub Action variable -to define the target OBS project to allow submitting to a different project. - -### Release Package Versioning - -The packages in the Release project use a version based on the version tag -matching `v[0-9]+`. Use `rake tag` command for creating a tag. See more details -in the [packaging documentation](../PACKAGING.md#bumping-the-version).