openSUSE:Build Service Collaboration

Jump to: navigation, search

Introduction

The Open Build Service offers different ways of collaboration. The easiest way is to grant write access for more people in a package or project. This way allows a small team working closely together to collaborate very quickly.

However, this approach does not work in a number of cases:

  • Unknown contributors have no write access and therefore can't submit changes.
  • The trust of a project decreases with the number of people who have write access.
  • Even people with write access might want to get a review of their changes, before becoming active in a project.
  • Continual changes in a large project lead to the situation where the project never finishes to build. Changes to base packages can block other packages indefinitely.

Therefore, the Open Build Service offers another way of making contributions. You can prepare changes in a branched project and then request to have the changes merged back.

Large projects, such as KDE, GNOME, Apache, and YaST, often need another layer of review, where submissions can be staged before being checked in to the main project. This is the case with openSUSE:Factory, for example. This project defines a development project for each package. The Open Build Service helps the user to develop against these projects and to submit contributions there. The project owners of the development project can then submit all the contributions to openSUSE:Factory. This process is visualized in these slides.

Example with CLI

Open Build Service command line tool (osc).

How do I contribute my changes to someone else packages?

Let's say you want to work on the package openSUSE:Factory/initviocons, and later submit your work back into the openSUSE:Factory project.

The following shows you what to do, step by step.

Create a Branch Package

First, we create a branch of the package we want to work on in our home project.

# osc branch <source project> <source package>
osc branch openSUSE:Factory initviocons

This command first creates a new personal 'branch project' below home:$yourself:branches, if it does not exist yet. This branch project has the same build setup as the original source project. Then the command also creates the package inside of the branch as a source link.

Many packages have a 'Devel Project' defined. In that common case, the server creates a link to that devel project instead of the source project. You see this in the 'osc branch' output, like this:

# branch a package from factory but which is developed in a different project
osc branch openSUSE:Factory glib2

will create home:$yourself:branches:GNOME:UNSTABLE/glib2.

This ensures that your changes follow the existing flow of changes into the package's real home.

Work on Changes

Now that you have branched a package, you can start working on it. The following commands:

osc checkout home:$yourself:branches:openSUSE:Factory initviocons
cd home:$yourself:branches:openSUSE:Factory/initviocons

check out the package to your local file system. The source link is expanded. When you branch a package, a link to the original is created instead of copying everything. With this link, our branch stays up to date if the original changes. To do work on your branch, you want to have the real package sources, not a _link XML file. So by default, checking out a linked package expands the link into the contents of the original package. You therefore get the original sources/files plus any existing changes in the checkout.

Now prepare your changes. If the source files are not inside a .tar.gz archive, simply edit the files:

vim <path/to/file>
...
osc diff
...


If the source files are in a .tar.gz archive, you will need to do things a little differently. Prepare your patch with quilt (install it with sudo zypper install quilt):

# Unpack the .tar.gz archive
quilt setup <name of package>.spec
cd <name of package-version number>

# Create a patch file to hold your changes
quilt new <desired name of your patch>.patch

# Edit the files
# Option 1:
quilt edit <path/to/file>
# Option 2:
quilt add <path/to/file>
<edit the file in the graphical editor of your choice>

# Give your patch a clear description
quilt header -e

# Complete the patch file once you're done editing everything
quilt refresh

# Integrate your patch into the package
cp patches/<name of your patch>.patch ..
cd ..
/usr/lib/build/spec_add_patch <name of your patch>.patch

# Add your patch to the repo
osc add <name of your patch>.patch


Now Give your change a clear description, mentioning the bug in this format: "(bsc#<number of bug>)"

osc vc

Do a local test-build to make sure everything works:

osc build

Local builds help to lower the turnaround times while you develop; there's no need to wait for the Open Build Service to finish building (or failing to build) your package each time you make a change.

Once your changes package builds locally, it's time to inform the Open Build Service about your changes:

# commit the changes
osc commit -m "changed this and that"

Your changes go to the server, and a build is scheduled.

Even though you checked out expanded sources, there's no need to create patches against the base package yourself. The Open Build Service takes care of all that, by comparing your branch and the original and creating diffs in your (unexpanded) on the Open Build Service.


After a while you can see if it all worked out with:

# check whether it builds
osc results

Sometimes you'll want to see how your work is different from the original package. You may want to discuss your changes with somebody else, for example, or you may simply want to see what other developers have been doing at the same time. To do so, use:

# show differences between your version and the one in openSUSE:Factory
osc rdiff home:yourself:branches:openSUSE:Factory initviocons

Debugging the build

osc build leaves some files in the build directory that can help you diagnose the problem. The last statement output by osc build is:

The buildroot was: /var/tmp/build-root

If you go there, you can examine the following files of interest:

name meaning
.build.log Examine the build and identify the error
.build.command The command used to do the actual build
.build.packages The directory where the object files are

If the build fails, you might be tempted to try to fix something in the build directory; this is usually not a good idea because the command osc build usually discards everything there ( rm -rf ) and restarts from scratch. This strategy is unfortunately not viable for incremental changes: if the build takes a long time, which is quite likely for large projects. To work around this problem, look at the file .build.command; it usually contains a line of the form

rpmbuild -ba package.spec

That command will discard everything you have built, so it is of no use either. However, this command is likely to resume the build:

rpmbuild -bc --short-circuit package.spec #compile
rpmbuild -bi --short-circuit package.spec #install

These options are explained in detail in the Fedora RPM Guide.

Submit your changes to be merged

Once you are satisfied and believe that your changes have a good chance of being accepted by the maintainers of the upstream project -- that is, if you are using the examples elsewhere in this document, by the maintainers of the openSUSE:Factory project -- you can go ahead and request a submit.

osc submitrequest -m 'version update to 3.3'

This submits the changes of the package in your local working copy to the project defined in the source link.

You can also do so without a checked out working copy by calling

osc submitrequest home:$yourself:branches:openSUSE:Factory initviocons openSUSE:Factory -m 'version update to 3.3'

This creates a request that indicates that you're offering something brilliant for Factory. :-) The maintainers of the project will quickly check it out. If the change is acceptable, they can merge it into their project. If it needs more work, they can send you further feedback.

How is my contribution handled?

The maintainer of a project (like openSUSE:Factory) is supposed to check for contributions (i.e. for submit requests) like this:


 % osc request list openSUSE:Factory
37   new         home:poeml/initviocons  ->  openSUSE:Factory/initviocons    'version update to 3.3'


The maintainer will look at the change by comparing it with the current package source, and either accept it or decline it and give a reason.

 % osc request show -d 37
Request to submit (id 37): 

    home:poeml/initviocons  ->  openSUSE:Factory/initviocons

Source revision MD5:
    f839321325a0b5582def283c3520bf13

Message:
    'version update to 3.3'

State:   new          2008-03-20T19:57:02 poeml



changes files:
--------------
--- initviocons.changes
--- initviocons.changes
@@ -20 +20 @@
-    which sends a characteristic primary da
+    which sends a characteristic primary DA
[...]


After that, the maintainer can accept the submission:

osc request accept 37

Or reject it, with a reason:

osc request decline -m "changelog missing, but required by policy" 37

Example with web interface

This describes how to change sources via the web interface.

The webui is nice to get an overview and to change simple things, like obvious errors or package descriptions. For doing more complex changes, like fixing merge conflicts the osc is recommended.

How do I contribute my changes to someone else packages?

Let's say you want to work on the package openSUSE:Factory/initviocons, and later submit your work back into the openSUSE:Factory project.

The following shows you what to do, step by step.

Create a Branch Package

You need to create a branch, which is basically a copy of the original package, because you usually don't have write access in the target. Or you want to experiment first, before shipping your code to all users.

The branch is always merging by default with changes from the branched package.

For openSUSE:Factory go to the package list and find your package.

Create Branch Project

Firstly, we create a branch of the package (and its project) we want to work on in our home project. Click on the "Actions" menu and afterwards on "Branch package".

This server creates a new project below home:$yourself:branches, the branch project. This branch project has the same build setup as the original source project. The command also creates the package inside of the branch as a source link.

Many packages have a 'Devel Project' defined. In that common case, the server creates a link to that devel project instead of the source project.

Work on Changes

Click on the "source files" tab and edit your sources as wanted. You should wait and see if they are really building.

You may also want to download the packages and try if your changes really make a difference at runtime.

Submit your changes to be merged

Icon-warning.png
Warning: This feature is currently not implemented for frozen projects like openSUSE:11.0, Fedora:9 or the :Update projects. This requires changes in our maintenance handling which will come later :)

Once you are satisfied and believe that your changes have a good chance of being accepted by the maintainers of the upstream project -- that is, if you are using the examples elsewhere in this document, by the maintainers of the openSUSE:Factory project -- you can go ahead and request a submit.

You can either create a submit request via the "Actions" menu or find the link "show diff and submit these changes back" on the "Source Files" page.

This will create a request for the target author, who will review your change and usually accept it. Your branched package is usually remove after merging back (except you denied this).

Special handling for openSUSE:Factory

Each package in openSUSE:Factory has a "development repository". These development repositories are used for development of the package itself. (You can "see" the develproject of a package via osc meta pkg openSUSE:Factory <package> | grep devel or simpler with osc dp openSUSE:Factory <package>.) If you do a osc branch openSUSE:Factory <package> do not be surprised if you get the package from another location if you want to make changes for a package in openSUSE:Factory.

To do a submitrequest to openSUSE Factory (Note: accepting a submitrequest in the development project does not trigger a submitrequest for Factory automatically!), a maintainer of the Devel-Project has to do something like:

       osc sr -m "- updated package, thanks to foo bar" <devel:project> <package> openSUSE:Factory

So we have two scenarios here:

Branch, non-official Devel Project maintainer's workflow

  1. osc branch openSUSE:Factory <package>
  2. osc submitrequest (sends the submitrequest to the devel project)
  3. Devel-Project maintainer accepts via osc sr accept <id>
  4. Devel-Project maintainer creates a new submitrequest against Factory
  5. Autobuild people accept the change

Devel Project maintainer's workflow

  1. Devel-Project maintainer creates a new submitrequest against Factory
  2. The autobuild (openSUSE:Factory team) people accept the change
So for Devel Project maintainers, it is always a good idea to configure their Hermes notifications to get informed about submitrequests against their project and/or check for submitrequests against their project via
osc request list <devel:project>