Build Service/Collaboration

From openSUSE

Introduction

The Build Service offers different ways of collaboration. The easiest way is to grant write access for more people in a package or project. This is the fastest way to work together with other people who do work closely together.

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.
• Permanent 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 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 Build Service helps the user to develop against these projects and to submit contributions there. The project owners of the development project can submit the contributions as whole to openSUSE:Factory later. This process is visualized in these slides.

NOTE: This page talks about the osc UI since version 0.119, older versions had slightly different commands.

Example

Another example, mentioning the use of the web client, of layering, linking, patching and aggregating for one project (PackageKit) is here: http://duncan.mac-vicar.com/blog/archives/334

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 should guide through the steps to do.

Create a Branch Package

Create Branch Project

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

This command 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. 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.

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. This means that instead of the source _link file, the original sources/files plus eventually existing changes get checked out.

# now, you work with it
vi ...
osc status
vi ...
vi *.changes

Your changes can be new features, fixes, improvements etc.

# build it locally
osc build

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

Once you are finished, it's time to inform the 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 backend takes care of all that.

After a while you can see if everything works out fine 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

Offer your Change 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, using the examples elsewhere in this document, by the maintainers of the openSUSE:Factory project -- you can go ahead and request a submit.

osc sr -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 sr 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 it's a good change, 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

Special handling for openSUSE:Factory Each package in openSUSE:Factory should have a "development Repository", which normally is home:<maintainer>:Factory - these development repositories are used if external packagers do a osc branch openSUSE:Factory <package> so don't be surprised if you get the package from another location if you want to make changes for a package in openSUSE:Factory. Currently just SUSE and Novell employees are allowed to do a submitrequest to openSUSE Factory (Note: if they accept a submitrequest for their development project, this doesn't trigger a submitrequest for Factory automatically!). For security reasons, it's necessary that the official package maintainer reviews the package in his development project before submitting it to openSUSE:Factory and add a new Changelog entry like: - reviewed changes from <external packager>