Skip to content

README.md

Latest commit

 

History

History
163 lines (119 loc) · 7.41 KB

README.md

File metadata and controls

163 lines (119 loc) · 7.41 KB

Development script

This directory contains scripts useful for Agama development.

Git autosubmission to OBS

The branch2obs.sh script creates an OBS project and configures the GitHub Actions for automatic submission from the specified Git branch or the current branch. Each branch can be submitted to a different OBS project.

There are several use cases for this script. You can use it for building testing images with patched Agama so the testers can easily test your fixes. Another use case is using it for a long running feature or refactoring, especially when more people work on that.

And last but not least, it can be used for preparing a new version for release. The release branch can be configured to be submitted to a special OBS release project while the master continues in accepting new features for the future release and is submitted to the usual development project.

Used tools

The script requires the git, gh, jq and osc command line tools to be installed. The osc and gh tools need to be configured/authenticated against OBS and GitHub, respectively. Do not worry the script checks for that.

Use the following commands if you don't want to remember your usernames:

GH_USER=$(gh auth status | sed -n 's/.*Logged in to github.com account \([^[:space:]]*\) .*/\1/;T;p;q')
OBS_USER=$(osc user | sed "s/^\([^:]*\):.*$/\\1/")

GitHub configuration

If you run the script in your GitHub fork then you need to configure the OBS credentials. When running in the original repository it will use an already pre-configured OBS user, you do not need to change anything.

You need to create the OBS_USER action variable containing your OBS login name. You can do that from command line running command

gh -R ${GH_USER?}/agama variable set OBS_USER --body ${OBS_USER?}

where $GH_USER is your GitHub login name and $OBS_USER your OBS login name.

Alternatively you can create the variable manually by visiting URL

xdg-open https://github.com/${GH_USER?}/agama/settings/variables/actions/new

where $GH_USER is your GitHub login name. On that page create variable OBS_USER with your OBS login name.

Similarly we need to enter the OBS password, but as this is sensitive private value we use GitHub secret for that. From command line run this command

gh -R ${GH_USER?}/agama secret set OBS_PASSWORD

where $GH_USER is your GitHub login name. The command will interactively ask for the password.

Or you can create the secret in browser going to this page

xdg-open https://github.com/${GH_USER?}/agama/settings/secrets/actions/new`

where $GH_USER is your GitHub login name. Create a new secret with name OBS_PASSWORD and enter your OBS password as the value.

Testing builds

This works in both original repository and in a fork.

  • Create a new branch in git and push it to GitHub
  • Run the branch2obs.sh script
  • The Git branch name is by default used in the OBS project name
    • systemsmanagement:Agama:branches:<branch_name> for the original repository
    • home:<your_name>:Agama:branches:<branch_name> for forks

Release builds

This works only in the original repository because is uses the systemsmanagement:Agama:Release project for submitting.

  • Create a new release branch in git and push it to GitHub
    • git checkout -b beta2
    • git push origin beta2
  • Configure submission, use the systemsmanagement:Agama:Release project as the target
    • branch2obs.sh -p systemsmanagement:Agama:Release
  • Bump the version in master branch for the next release
    • git checkout master
    • Update the ISO version in live/src/agama-installer.kiwi, use the pre suffix to distinguish between a development version and the final version. I.e. for Beta3 change the version from 12 to 13.pre.
    • Push the changes
      • git commit -a
      • git push
    • Configure that the version tag is submitted to the Devel project as well:
      • branch2obs.sh -b v13.pre -p systemsmanagement:Agama:Devel
      • Important: The version tag needs to contain the dot separator between the version and "pre" suffix! It is used in the Agama Ruby gem version and Ruby Gemspec is quite picky about the version format.
    • Create the version tag and push it to GitHub
      • git tag -s -m "Version v13.pre" v13.pre
      • git push origin v13.pre
      • Important: The new version tag must not be reachable from the release branch otherwise it would use this version as well. That special version bump commit created before ensures that.
  • Now the new features can be committed to the master branch without breaking the release code.
  • Do not forget to merge the fixes from the release branch also to master.
  • When the development for the next release is open in master remove the pre suffix from the version (use the same process as described above without the pre suffix).
  • The "pre" tag can be removed from Git, it is not used anymore.
  • You might remove the mapping for the previous release branch from the OBS_PROJECTS GitHub variable. Just to avoid accidentally updating the packages with the old code when a commit is added to the old branch.

Cleanup

After deleting a branch in Git (either explicitly or automatically after merging a pull request) the respective OBS project should be deleted.

That can be done by running branch2obs.sh -c, it scans the OBS subprojects and deletes the ones which do not have a matching Git branch. It also removes the brach from the mapping stored in the OBS_PROJECTS GitHub Action variable.

To just print the obsolete projects without deleting them run command branch2obs.sh -o.

Implementation details

The mapping between the Git branch and the target OBS project is stored in the OBS_PROJECTS GitHub variable. It is in JSON format and maps the Git branch name to the OBS project name.

The GitHub submission actions check the mapping value for the current branch/tag and if no mapping is found the submission is skipped.

Detailed implementation

  • check if needed tools are installed, else terminate (git gh jq osc)

  • check if user is authenticated to gh and osc, else terminate

  • modes of operation:

    • print obsolete projects (those where the branch no longer exists)
    • cleanup obsolete projects
    • setup a project for submission (described in the following)

  • if setting up a fork, check that OBS_USER and OBS_PASSWORDS are defined, else terminate

  • if the OBS project does not exist yet, create it:

    • branch a set of packages from systemsmanagement:Agama:Devel to the target project
    • disable building for archs: aarch64, i586, ppc64le and s390x (unless -a is given)
    • disable building for targets: Leap 16.x (unless -t is given)
    • for package agama-installer-Leap, disable building for target: images(TW)
    • enable publishing the packages and images (which is off by default in OBS)
    • set the project url, title, description: to point to the git repo and branch

  • update gh variable OBS_PROJECTS for the repo to include this branch->project

  • for each of the set of CI Workflows (last major change: PR#2145)

    • trigger the workflow
      • if the remote branch already exists, do it
      • otherwise print the command to do it

  • print the URL of the OBS project