openSUSE:Build Service Collaboration
Introductie
De Build Service biedt verschillende manieren van samenwerking. De gemakkleijkste manier is om schrijftoegang te geven aan meer mensen in een pakket of project. Op deze manier kan een klein team hecht samenwerken snel tot stand komen.
| Dit artikel is nog maar gedeeltelijk vertaald. Als u mee wilt helpen met vertalen lees dan Wiki vertalen naar het Nederlands. |
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
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
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
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
- 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>