openSUSE:Build Service Collaboration
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
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
- osc branch openSUSE:Factory <package>
- osc submitrequest (sends the submitrequest to the devel project)
- Devel-Project maintainer accepts via osc sr accept <id>
- Devel-Project maintainer creates a new submitrequest against Factory
- Autobuild people accept the change
Devel Project maintainer's workflow
- Devel-Project maintainer creates a new submitrequest against Factory
- The autobuild (openSUSE:Factory team) people accept the change
osc request list <devel:project>