OBS Major Release HOWTO

How do we release?

A major OBS release usually involves a couple of iterations of releases until we release the official, new major release. This starts with an development version (alpha), continues with one or more beta releases and ends with the final release.

To make the different stages of this workflow visible to others it's recommended to add a ~alpha, ~beta1, ~beta2 suffix to the $VERSION of our appliances and obs-server package. Note that this has to be suffixed with a tilde ~ char to avoid version conflicts, eg. 2.9.0-beta would be consider newer than 2.9.0.

Project setup (before the release)

Before we can do the first beta release, we need to create and set up various projects in OBS, openQA, etc. All this is explained below.

Prepare the github repository

1. Create a new branch for the release, eg. '2.9'
2. Protect the git version branch
   • Go to the 'Settings' tab
   • Select 'Branches' from the list menu
   • Choose the newly created branch
   • Enable the 'Protect this branch' checkbox and save
3. Add a new ReleaseNotes-$VERSION file in the root of the git version branch

Create the stable project

1. Get our stable project meta example.

   wget https://raw.githubusercontent.com/openSUSE/open-build-service/master/dist/stable_project_meta.xml.example
   

2. Adapt the example file. Basically replace $VERSION with the major version and check that the openSUSE/SLE versions it builds against are the latest ones.

3. Create the project using the meta file

   osc meta prj -e OBS:Server:$VERSION:Staging -F stable_project_meta.xml.example
   

Create the staging project

1. Get our staging project meta example:

   wget https://raw.githubusercontent.com/openSUSE/open-build-service/master/dist/staging_project_meta.xml.example
   

2. Adapt the example file:

   • Replace $VERSION with the major version and check that the openSUSE/SLE versions it builds against are the latest ones.
   • Change the project description to reflect that this is a development project (or an alpha/beta release):

   This is the development version 2.9 of OBS.
   

3. Create the project using the meta file:

   osc meta prj -e OBS:Server:$VERSION:Staging -F staging_project_meta.xml.example
   

4. Copy the prjconf file from OBS:Server:Unstable and apply the needed modification:

   osc meta prjconf OBS:Server:Unstable > prjconf_$VERSION
   

5. Apply the current prjconf:

   osc meta prjconf OBS:Server:$VERSION:Staging -F prjconf_$VERSION
   

6. Adjust the project conf, eg. remove repositories and architectures we don't support in our stable release.

Create the obs-server package and dependencies

1. At least we will need the following packages to build obs-server correctly:

   deltarpm libarchive libmemcached memcached perl-BSSolv perl-Devel-Cover perl-common-sense perl-Diff-LibXDiff perl-File-Sync perl-GD perl-JSON-XS perl-Socket-MsgHdr phantomjs containment-rpm-docker obs-signd createrepo build ruby-common ruby2.4 rubygem-bundler rubygem-gem2rpm rubygem-hoe rubygem-rake-compiler yum sphinx travis-deps nodejs obs-server

2. Copy those packages from OBS:Server:Unstable:

   osc copypac OBS:Server:Unstable $PACKAGE OBS:Server:$VERSION:Staging
   osc setlinkrev OBS:Server:$VERSION:Staging $PACKAGE
   

   The second command is needed as the first one doesn't set the revision even if it is already set in OBS:Server:$VERSION:Staging.

Adapt the obs-server package and get it building

1. Checkout obs-server package to have it locally:

   osc co OBS:Server:$VERSION:Staging obs-server
   

2. Change the versionformat and revision inside the _service file to $VERSION:

   <service name="obs_scm" mode="disabled">
     <param name="versionformat">$VERSION~pre.git%cd.%h</param>
     <param name="revision">$VERSION</param>
     ...
   </service>

3. Copy the changelog file from the previous version. So for example, for 2.9 we use 2.8:

   osc cat OBS:Server:2.8 obs-server obs-server.changes > obs-server.changes
   osc addremove
   

4. Create a changelog entry from the ReleaseNotes-$VERSION file:

   osc vc obs-server.changes
   

5. Check in the changes and make it build:

   osc ci
   osc r -v OBS:Server:$VERSION:Staging obs-server
   

Create the OBS-Appliance package

1. At least we will need the following packages, and its dependencies, to build obs-server correctly:

   OBS-Appliance apache2-mod_xforward changelog-generator-data rubygem-passenger rubygem-changelog-generator
   

2. Copy the appliance packages from OBS:Server:Unstable:

   osc copypac OBS:Server:Unstable $PACKAGE OBS:Server:$VERSION:Staging
   osc setlinkrev OBS:Server:$VERSION:Staging $PACKAGE
   

Adapt the appliance and get it building

1. Checkout the OBS-Appliance package:

   osc co OBS:Server:$VERSION:Staging OBS-Appliance
   

2. Set the version tag inside the OBS-Appliance.kiwi file to $VERSION:

   <version>$VERSION</version>
   

3. Set the version in the repository section inside the config.sh file with the correct $VERSION:

   #======================================
   # Add Default Repositories
   #--------------------------------------
   zypper ar http://download.opensuse.org/distribution/leap/42.3/repo/oss/                  openSUSE:Leap:42.3
   ...
   zypper ar http://download.opensuse.org/repositories/OBS:/Server:/$VERSION/openSUSE_42.3/ OBS:Server:$VERSION

4. Check in the changes and make it build:

   osc ci
   osc r -v OBS:Server:$VERSION:Staging OBS-Appliance
   

Testing

Enable openQA for the appliance

1. Add a new "Medium type" in openqa.opensuse.org with the name of the new version. You need admin rigths in openQA. For example, for version 2.9:

   Distri	Version	Flavor	  Arch	Settings	Actions
   obs	2.9	Appliance  	x86_64	
   

2. Add a new line to (or adjust) the dist/schedule-obs.sh script with the new version to be tested. Have a look at openQA-Setup for locating the script.

3. In our openQA setup we currently install some packages from OBS:Server:$VERSION (why FIXME?). To make sure that these packages are available run osc release OBS:Server:$VERSION:Staging.

Integration tests

• Download the built appliance and test LDAP support as described in our wiki.

Releasing

As mentioned before, there probably will be multiple (beta) releases before we do the final release. All these releases follow the same steps, with small differences.

Updating the version

Example

Let's say you want to release the beta 1 for OBS 2.9. Your version would then be '2.9.0~beta1'.

For the obs-server package you would edit the _service file:

  <param name="versionformat">2.9.0~beta1.git%cd.%h</param>

For our OBS-Appliances you would edit the config.xml of the OBS-Appliance package. This will affect all OBS-Appliance:* multibuild packages:

 <image schemaversion="5.3" name="obs-server-beta1" displayname="OBS_Server_Beta_1">

Release the staging project

1. Release the staging project with osc release --no-delay OBS:Server:$VERSION:Staging:

   • The --no-delay option will make the command to run immediately the release, and wait for a result. Otherwise there is no way to know if it has finished or didn't start yet.
   • Wait until the staging project gets released.

2. Write a mail like this to our public mailing list.

3. [optional] Write a blog post for our blog.

4. Tag the released code:

   git fetch upstream
   git checkout upstream/$VERSION
   git tag -a $NEW_VERSION
   git push upstream $VERSION

5. Update description of OBS:Server:$VERSION.

6. Update documentation of OBS:Server:$VERSION, eg. version bump