Build Service/Collaboration

From openSUSE

Revision as of 19:57, 24 August 2009

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 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 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 then submit all the contributions to openSUSE:Factory. This process is visualized in these slides.

Example

Template:Warning1

Here is another example mentioning the use of the web client, of layering, linking, patching and aggregating for one project (PackageKit) is here:

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

Create Branch Project

Firstly, we create a branch of the package (and its project) we want to work on in our home 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.

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 work with it
vi ...
osc status
vi ...
osc vc

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 Build Service takes care of all that, by comparing your branch and the original and creating diffs in your (unexpanded) on the 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

Submit your changes to be merged

Template:Warning1

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

Special handling for openSUSE:Factory

Each package in openSUSE:Factory have 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.) If you do a osc branch openSUSE:Factory <package> don't 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 doesn't 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've 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's 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>