GNOME/OscGnome

From openSUSE

With the introduction of the collaboration features of the build service, everybody can now help with packaging GNOME: the development is done in the GNOME:Factory (G:F) project, and packages submitted there will then be submitted to openSUSE:Factory (oS:F) which is where the Factory distribution lives.

However, the command line for all this might be a bit hard for first-time users, and some of the usual workflow can actually be automated. That's why we created the osc gnome plugin. This plugin provides three extremely useful commands: osc gnome todo, osc gnome update and osc gnome setup. A few other commands are available.

Example of a typical workflow

First, let's look at what can be done (the output of the todo command is truncated in this example):

vuntz@lyon ~/work/opensuse/tmp/>osc gnome todo
Downloading data in a cache. It might take a few seconds...
Package                         | openSUSE:Factory | GNOME:Factory    | Upstream        
--------------------------------+------------------+------------------+-----------------
anjuta                          | 2.23.91          | 2.23.91          | 2.24.0.1 (r)    
at-spi                          | 1.23.92          | 1.23.92          | 1.24.0          
gdm                             | 2.23.92          | 2.23.92 (s)      | 2.24.0 (s)      
gedit                           | 2.23.93          | 2.23.93          | 2.24.0

We can see that anjuta, at-spi, gdm and gedit all need an update in GNOME:Factory since there is a more recent version upstream. We notice that anjuta has already been reserved by somebody, so we can ignore it. Similarly, we notice that there is a submission for gdm waiting to be approved by a GNOME:Factory administrator. So let's just ignore this one too. It's possible to automatically remove those lines with some arguments: osc gnome todo --exclude-reserved --exclude-submitted (or osc gnome t --xr --xs for people who prefer to not type long commands).

So let's work on updating gedit:

vuntz@lyon ~/work/opensuse/tmp/> osc gnome update gedit
Package gedit has been reserved for 36 hours.
Do not forget to unreserve the package when done with it:
    osc gnome unreserve gedit
A    /home/vuntz/work/opensuse/tmp/gedit
A    /home/vuntz/work/opensuse/tmp/gedit/gedit-2.23.93.tar.bz2
A    /home/vuntz/work/opensuse/tmp/gedit/gedit-desktop.patch
A    /home/vuntz/work/opensuse/tmp/gedit/gedit.changes
A    /home/vuntz/work/opensuse/tmp/gedit/gedit.spec
A    /home/vuntz/work/opensuse/tmp/gedit/ready
Package gedit has been checked out.
gedit.spec has been prepared.
gedit.changes has been prepared.
Looking for the upstream tarball...
gedit-2.24.0.tar.bz2 has been downloaded.
Finding NEWS and ChangeLog information...
NEWS between gedit-2.23.93.tar.bz2 and gedit-2.24.0.tar.bz2 is available in osc-gnome.NEWS
ChangeLog between gedit-2.23.93.tar.bz2 and gedit-2.24.0.tar.bz2 is available in osc-gnome.ChangeLog
Running quilt...
Patches still apply.
gedit-2.23.93.tar.bz2 has been removed from the package.
gedit-2.24.0.tar.bz2 has been added to the package.
Package gedit has been prepared for the update.

The output of this command is a bit verbose, but this way, you can be sure of what's going on. In this specific case, everything went fine and so it seems you only need to update gedit.changes.

So, you first change the current directory to the checked out package with cd gedit. And then, you can now open gedit.changes in your favorite editor. You'll notice that it's already prefilled:

-------------------------------------------------------------------
Tue Sep 30 16:37:35 CEST 2008 - vuntz@novell.com

- Update to version 2.24.0:
  + 

------------------------------------------------------------------- 

So you only have to mention what has changed. The osc-gnome.NEWS and osc-gnome.ChangeLog files should be of some help here.

Now that you've updated gedit.changes, you should make sure that all patches in the package are still relevant and that the build and runtime dependencies are up-to-date. There is no magic way to do this, so it's all manual work.

After that, you can commit your changes to the build service: osc commit -m 'Update to 2.24.0'

Once this is done, make sure that the package builds correctly -- either by checking the result of the build in the build service (on the web page or via osc results home:vuntz:branches:GNOME:Factory gedit) or by using osc build.

If the build is successful, submit your package to GNOME:Factory with the following command: osc submitreq create -m 'Update to 2.24.0'

You can then unreserve the package since you've submitted your update: osc gnome unreserve gedit

What can go wrong

• if you try to update a package which is already reserved by somebody, you will get an error. You can use the --ignore-reserved option to ignore this. You should only do this after communicating with the person who reserved the package.
• sometimes, some patches don't apply anymore. In this case, you will see that the 'quilt' step failed. You will have to fix this first.

User documentation

Here we will cover the really basic steps to get you running with osc gnome.

Installation

The easy way to install this plugin is to install the osc plugins for GNOME.

You can also install the latest version of the plugin from git:

• Install osc and git: zypper in osc git-core
• Checkout the osc-plugins repository: git clone http://www.vuntz.net/git/osc-plugins.git/
• Copy the plugin: mkdir -p ~/.osc-plugins/ && cp osc-plugins/obs-dissector/osc-gnome.py ~/.osc-plugins/

To make sure the plugin is installed, simply run osc gnome --help and you should see the help summary of the plugin.

The first time you will run the plugin to do an actual command, it will ask you for an email address. This email address is saved in ~/.oscrc and will be used when updating .changes files.

What can I do?

One issue in a big team is that often, people don't know what they can do: there are so many things to do that you get lost since you don't know what should really be done and what people are working on. The osc gnome todo helps you here. It will display all the packages that need an update to a new upstream version. It's generally the easiest way to start working on the packages.

You can use the --exclude-reserved and --exclude-submitted options to hide packages which are already being worked on by someone else, or to hide packages which are already submitted to GNOME:Factory. Those packages are identified with (r) and (s) in the normal output.

Reservation system

To avoid people duplicating work, we are using a really simple reservation system. When you run osc gnome update or osc gnome setup, you automatically reserve the package for work. To ignore this reservation step, you can use the --no-reserve option.

A reservation lasts 36 hours. After this time, the reservation expires and is automatically removed. The other way to remove a reservation is to automatically cancel it with osc gnome unreserve.

Note that you can manually reserve a package for work with osc gnome reserve. This command is provided for completeness only, since you would generally use osc gnome update or osc gnome setup.

It is possible to see who is working on what with the osc gnome listreserved, and you can also check if a package is reserved with the osc gnome isreserved command.

Updating a package to a new upstream version

The most common task during the early development cycle of a new version of openSUSE is to update packages to new upstream versions. The osc gnome update command can be used for that.

This command will do the following:

• check if there is an update for the package. If this is not the case, the command stops.
• check that nobody is working on the package, unless the --ignore-reserved option is used.
• reserve the package for you, unless the --no-reserve option is used.
• branch the package from GNOME:Factory and check it out in the current directory.
• do the required updates that can be determined to the .spec file (usually, update the Version tag).
• prepend a new .changes entry that you will later fill.
• download the upstream tarball.
• extract the relevant NEWS and ChangeLog information for this new upstream tarball.
• check that patches in this package still apply with the new upstream tarball.
• remove the old tarball from the build service and add the new tarball to the build service.

In general, the only thing left to do after running this command is to fill the .changes file. You also have to make sure that all patches are still relevant and that all the build and runtime dependencies are correct.

Working on a package

The other common task when working on a package is to modify a package, to add a new patch or to fix a packaging issue. The osc gnome setup command helps you prepare the package.

This command will do the following:

• check that nobody is working on the package, unless the --ignore-reserved option is used.
• reserve the package for you, unless the --no-reserve option is used.
• branch the package from GNOME:Factory and check it out in the current directory.

You can then easily do the work you wanted to do.

Other useful commands

There are a few other commands in osc gnome that might be of interest to you.

Tasks for administrators

osc gnome todoadmin lets you do a sanity check of GNOME:Factory. It will display a list of things you might want to do to clean the GNOME:Factory project. For example:

• packages with a patch that don't apply anymore
• packages which are not links to openSUSE:Factory
• packages which shouldn't exist in GNOME:Factory (either because they're dead or because they're maintained elsewhere)
• packages which should exist in GNOME:Factory (generally, this is new packages that haven't been linked in GNOME:Factory yet)
• packages which should be submitted to openSUSE:Factory
• etc.

You can use the --exclude-submitted option to hide packages which are submitted to openSUSE:Factory but waiting for a review there.

Generally, the way to fix the issues are trivial to know for an administrator. For reference, the following commands are generally helpful:

• osc linkpac openSUSE:Factory $pkg GNOME:Factory: to link a package from openSUSE:Factory to GNOME:Factory
• osc checkout -u GNOME:Factory $pkg: to check out a package in unexpanded mode, to fix patches that don't apply anymore, eg.

Contributing

Everybody is welcome to contribute to the development of the osc gnome plugin. Feel free to report bugs or send patches to the mailing list:

• opensuse-gnome@opensuse.org - openSUSE GNOME Mailing List

Subscribe | Unsubscribe | Help | Archives

Also, you can publish your git branch of osc-plugins on the Internet to ease collaboration in the development.

Backend details

Right now, osc gnome works thanks to a database that is created by various scripts. Those scripts are living in osc-plugins/obs-dissector/. Feel free to look at them and improve them too.