openSUSE:How to contribute to Factory

Jump to: navigation, search


This article will give you a view from the contributor perspective on openSUSE Factory, such as concepts, commands to execute, people to talk to and so on. It is meant as a starting point and does not intend to replace in-depth documentation for things like programming languages, compilers, packaging or the Open Build Service. You are expected to know about those things already. This article will show that contribution to Factory is both easy and very welcome.

Joining the Package Maintainers

Welcome and we're thrill that you have decided to become a package maintainer in the openSUSE Project. This guide will lead you through your first package submission. It can be a completely new package, or update to an existing package.

Setup an Account

To begin to contribute to factory, you will need to make an account on openSUSE. openSUSE has a single-sign in system.

Read the Guidelines

Familiarize yourself with our Package Management guide. You should thoroughly be familiar with these points as they govern all package submissions. If you have questions, email the Packaging List.

Understanding Responsibilities

Software components included in our distributions need to be maintained actively, and bugs — especially security issues — need to be fixed in a timely manner. As a package maintainer, it is your primary responsibility to ensure this.

If not familiar with git, do the following

If you have not configured your username and email address for Git, do the following with your info for openSUSE packages.

    git config --global user.name "John Doe"
    git config --global user.email johndoe@example.com

Getting Started

Check to see what packages could use a maintainer/s

A constant stream of information about different packages the could use help are being listed on the factory mailing list. Frequency varies, but go through the history and you're bound to find a package that would need a maintainer.

How to submit a fix to a package (Both upstream or within project)

The easiest and most convenient way to contribute to Factory is to just submit fixes. If you know why a package does not build or does not work correctly, why not send a fix? If the version of a package is outdated, why not update it? To make this possible for everybody, the openSUSE developers leverage the collaboration features of the Open Build Service for Factory contributions. This means that everyone can branch packages from openSUSE:Factory, do modifications and submit them back; it is as easy as checkers. First, you need to check what is the devel project for the package you want to fix. This can be found by

osc dp openSUSE:Factory aaa_base

If that does not work, then you can also search for it at https://build.opensuse.org or https://software.opensuse.org, and noting what project the openSUSE:Factory package is developed from.

Then you need to checkout the package with osc.

osc branch -m 'Fix XY' develproj:Name aaa_base

As you can see, the server created a copy of the package from the correct devel project and placed the result into your home project. Check it out to your local machine to do any changes.

osc checkout home:yourname:branches:Base:System/aaa_base

Alternatively, you can use `osc bco` to chain the branch+checkout actions into one command.

osc bco develproj:Name/aaa_base

After you have changed what you wanted to fix, you want to make sure that the package builds and works correctly. To make sure it builds correctly, run

osc build

and make sure it builds. If it successfully builds, then check if there are also any rpmlint errors or warnings you want to take care of. Sometimes it is acceptable to ignore them (such as if they were already present before you changed the package), other times they should be dealt with.

Remember to add an entry to the changelog so that it is easy for others to know about your changes.

osc vc -m 'Added fix XY for problem Z'

It may also be helpful to run `osc diff` to remind yourself of what you have changed.

Then, you can check in your changes to your branch.

osc checkin -m 'Added fix XY for problem Z'

Then submit them to the developer of the package for review.

osc submitrequest -m 'Added fix XY for problem Z'

The developer of the package will then get notified about your submission and will review it. We call this BURPing.

  • Branch,
  • Update,
  • Request,
  • the Package

How to add a new package to Factory

If you have never created a package before, you may want to visit this tutorial before you begin submitting packages to OBS.

The openSUSE:Factory project requires that every package reside in a so-called development project (devel project and develprj for short), which acts as a feeder project to openSUSE:Factory for your package. The home: namespace is not permitted to act as a develprj for Factory packages.

Just like it is the case for openSUSE:Factory, development projects are overseen by their respective reviewers and/or maintainers, and new package creations from non-maintainers need to be approved. Even though a submit request can create a package, the `osc submitrequest` command acts more like a request to copy, and hence always requires a source location. To truly start from scratch, one has to use the `osc mkpac` command instead. By default, users only have write permissions in their home namespace, which is home:yourname. If you haven't made a local copy of your home project, you can do so by

osc checkout home:yourname

Now that you have a local copy, you can run this

osc mkpac home:yourname/packagename

to create a blank package, inside which you can make modifications as desired. Take note that the default repositories that are set up for home:yourname are pointing to the distributions (Leap/Factory/etc.) directly, and not to the develprj—it may become necessary to edit this (`osc meta prj -e home:yourname`) if you wish to make use of packages or features not yet present in Factory.

Once you have completed your edits to the package, i.e. populating it with a .spec file, source tarball or other ancilliary files, and have verified that the build has successfully completed, the package can then be submitted like before:

osc submitrequest \
 -m 'I want to maintain python-cerealizer in Factory and would like to use devel:languages:python as the devel/feeder project.' \
 home:yourname/python-cerealizer devel:languages:python

A list of the current devel projects can be found in this list. Find a public list of all projects here. If you cannot find a corresponding topic, you need to use our catchall project devel:openSUSE:Factory. If you have a completely new collection of packages that could form their own devel project, see #How to request a new devel project.

When the devel project has accepted the new package, that package will generally have no additional permissions, which means that only develprj maintainers could edit it later. The maintainer who approves your package creation/update request can add you as a package maintainer — the OBS web interface has a checkbox for them. However, this checkbox is not enabled by default, and it may be overlooked. Based upon the example of python-cerealizer, you can check for assigned permissions by way of

osc meta pkg devel:languages:python/python-cerealizer

If you see your username in a `<person role="maintainer" ...>` line, all is set. If not, you can request edit permissions after the fact using

osc reqms devel:languages:python/python-cerealizer

Whether or not you have edit permissions on the package, you can trigger a submit request of the package to openSUSE:Factory. That submit request should contain a note with information about the package. Preferably, you introduce the package to the opensuse-factory list and point to that introduction in your submitrequest. A good introduction contains information on the state of the upstream project and how maintainable it is and what the purpose of having it in the distribution will be.

osc submitrequest -m 'New package see http://lists.opensuse.org/opensuse-factory/2011-05/msg00018.html ' devel:languages:python/python-cerealizer openSUSE:Factory

How to request a new devel project

Scenario: There is a piece of software that is not in Factory, it is not maintained anywhere in the openSUSE Build Service (except possibly in the home: space), and you want to get it into Factory/Tumbleweed.

First, you need an OBS project somewhere outside of the home: namespace. In most cases, one of the existing devel projects will be appropriate for your new package. Just submit an SR to the appropriate devel project.

If you need a new devel project, one way to get one is to contact the maintainers of an existing top-level project and ask them to create a subproject for you. If none of the existing namespaces are a good fit, ask the OBS maintainers to create a new project space by opening a bug or writing to admin@opensuse.org.

If the project your package ends up in is an existing devel project, you can now submit the package to Factory.

However, if you had to make a new project for your package, there is more work to do. Each package in Factory/Tumbleweed has a "devel package" associated with it. These are the projects in the drop-down menu on top of the openSUSE:Factory project page or list in dashboard container. The location of the devel package (i.e. the project where it lives) determines what the devel project for that package is. In our case, both the package and the project are new: Factory doesn't know about them. When you submit from an project that is not in the list, the submission will be auto-declined.

This appears to be a Catch-22 situation. There is a way out, however, by whitelisting the new project in the Target Project's OSRT:Config attribute utilized by the bot that vets Factory submissions. To do this ask that the project be added to the devel-whitelist space separated list in the config either by asking in #openSUSE-factory or in the opensuse-releaseteam mailing list. Once the project has been added submit requests will not be declined based on source project.

Any new devel project must also have factory-maintainers defined as a maintainer, to enable the Release Team the ability to fully handle any stuck submissions and changedevelrequests.

If a package is already in Factory and is merely being moved to a new location, and that new location is not a Factory devel project yet, it can be made into one by issuing a changedevelreq for that package to the new location (after moving the package). If that new location was not yet a devel repo, upon accepting the chgdev, it will become a devel repo and all future submissions from this repo, including all other packages there, will be accepted.

How to become a maintainer of a package in Factory

Just talk to the current developer if you want to help or take over responsibility and be aware of the duties and rights of a Factory maintainer

You determine the current maintainer by accessing build.opensuse.org or with this command:

osc maintainer openSUSE:Factory aaa_base

To get an email-address for contact, use

osc maintainer -e openSUSE:Factory aaa_base

Apart from just writing to the current maintainer, there are two more options:

  • osc requestmaintainership openSUSE:Factory aaa_base
  • go to build.opensuse.org, login, then search for the package you're interested in, then "Request role addition".

How to merge a fix for a package in a devel project

The Open Build Service will notify you about new requests via email. You also can also query it for all the new request.

osc request -s new

Merging the changes is as simple as accepting the request. Its a good idea to examine the changes first.

osc request show -d 12345

And if you like what you see you accept it

osc request accept 12345

How to submit a package to openSUSE:Factory

Once you are satisfied with the state of your package in your devel project, simply submit it to openSUSE:Factory.

osc submitrequest devel:languages:python/python-cerealizer openSUSE:Factory

Mass submissions

If you submit a lot of related packages in a short period, be prepared to equally receive declines. Time has shown that, if there is a problematic change in one package, there is a fair chance the same issue is present in other packages of the mass submit. We would therefore recommend that, if you plan on doing a mass submission, that you split it up into batches, and that the first batch has only on the order of 5–10 packages. Subsequent batches of a mass submit can increase in size linearly.

How to submit a package to a released product

If you want to fix a package in a released distribution, like openSUSE 11.4, you have to do some additional steps. They are described in the package maintenance guidelines.

How to drop a package

Icon-warning.png
Warning: If you are not the maintainer of the package, please talk to the maintainer before doing any of the steps below.
Before you drop any package please consider our drop policy for openSUSE:Factory. Thanks in advance.

Let's assume that we want to drop the oldstuff package from Factory, and that its devel project is devel:openSUSE:Factory. You should first check that no other packages depend on oldstuff in Factory.

osc whatdependson openSUSE:Factory/vim standard i586

If some packages depend on it, you have several options:

  1. give up and accept to keep oldstuff
  2. drop those packages first
  3. change those packages to not depend on oldstuff

Once you have found a solution, just file a drop request for oldstuff in openSUSE:Factory, explaining why you want to drop the package.

osc deleterequest -m "Dropping oldstuff because XXX" openSUSE:Factory oldstuff

When a package is removed from Factory, it is not automatically removed from the devel project. The reason is that the package could still be used outside of Factory, in the devel project for some other reasons. So, depending on your needs, you might want to remove the package from the devel project too.

osc deleterequest -m "Dropping oldstuff because XXX" devel:openSUSE:Factory oldstuff

How to restore a dropped package

TBA

How to request a change in a package with SLE origin?

Please see Portal:Leap/SLEFeatureRequests for more guidance.