openSUSE:Factory dos and donts

Jump to: navigation, search


Few general hints about what maintainers should do and what they shouldn't do.


Maintainers should ...

... keep in mind that others will work on the package

This is probably the most important rule: everything that is done in the package should be easily understandable by anybody else who steps up to help.

This includes good documentation, both in the .changes file and in comments in the .spec file, but also links to relevant resources (for patches, with patch tags).

This also means that quick fixes that are cryptic should be avoided.

... respond to the submit requests in a timely and friendly way

A good maintainer will make sure that contributors get motivated. The best way to achieve that is to respond to submit requests in a timely way (waiting more than a few days without any feedback is demotivating) and in a friendly way. Do not reject requests in a blunt way, but try to clearly explain the issues you have with the submission. The review features of the build service can help there.

... document every change in changes file

Every time you submit a fix or update to the Factory, you have to document all changes in .changes file. You can use osc vc to help you create a template for the new .changes entry.

A good .changes entry does not simply describe the changes, but explain why the changes are needed. For instance: "Add pkgconfig(coolstuff) BuildRequires" is purely descriptive, while "Add pkgconfig($coolstuff) BuildRequires to enable $cool feature" gives a quick overview of why the changes is important.

Also, do not forget to reference the bug entries or feature requests that are being closed thanks to the change. "Fix bnc#12345" of "Close fate#12345" can be used for this.

... use %{optflags}

Make sure that %{optflags} (or $RPM_OPT_FLAGS) are passed to C/C++ compiler as CFLAGS/CXXFLAGS. Using %configure might help, but sometimes using export CFLAGS="%{optflags}" before running make is necessary. It also happens that patching is required.

... look at the rpmlint warnings

At the end of the build, rpmlint is used to analyze the built packages and to warn about common packaging errors. The report is at the end of the build log and starts after the RPMLINT report: line. Fixing those warnings usually improves the package.

... follow FHS

Put all files in your packages to the correct locations. Respect filesystem hierarchy standard. Usually, a well-maintained upstream project will do this for you when you use %make_install (or make install).

... use a consistent packaging style

A .spec file can be written in several ways to achieve the same result, so it is nice to adopt a specific packaging style to lower the effort of contributors.

The spec-cleaner tool (available in openSUSE:Tools) can update a .spec file to use a packaging style that is easily readable. For instance, it only puts one BuildRequires dependency per line (while you can put as many as you want) because it then makes it easier to see changes in a submit request with the diff.

... read corresponding documentation

Read the packaging guidelines relevant to your package.

Maintainers shouldn't ...

... include bundled libraries

Whenever possible, try to use system libraries instead of bundled one. Bug upstream, create patches. We want everybody to use shared libraries, not to carry around their own version.

... make changes if they have any unprocessed submit requests

If you are updating/fixing package, take a brief look before at your queue with submit requests. Somebody might already have done it. And they would be really demotivated if you just break it and do it again.

... keep patches for themselves

If you have to fix something and patch the software you are packaging, don't keep patches just to yourself. Put them in the upstream bug tracker. Communicate with upstream. If you do so, you wouldn't need to port it when upstream creates a new version, and others will benefit from your patch as well.