GNOME packaging howto

Here you should find all singularities that set openSUSE's GNOME development projects apart from the others, regarding its way of packaging. Following those guidelines will help make sure your contributions get accepted without much ado, making the overall process smoother to all parties involved.

This article is a work in progress!

Setting up your system for casual package updating

If you're an openSUSE GNOME user and would like to help keeping any package you use up-to-date, it's really worth learning basic packaging skills and development tools used in the process of package update. Most of the time, updating a package is a fairly trivial task. Sometimes upstream GNOME will release a couple of fixes for a software in there stable branch, sometimes they'll make translation improvements available. Those kinds of updates are easy to handle. However, what makes it difficult for openSUSE GNOME maintainers and contributors is the number of releases that upstream makes.

Although, the process is not totally automated (full automation probably can't be achieved because changes files need first class human attention). It's expected that trivial package updates is going be really easy in the future, once some issues are taken care of and a couple of features are implemented on OBS. And openSUSE, being an Open Source project that keeps going with the help of a lot of contributors around the world, is always opening its arms for new people interested in give their time and effort, and looking for a chance to give back to the community.

Let's take a look at how you can set up an environment for updating openSUSE GNOME packages -- this basic setup should allow you to work with packages even outside of openSUSE GNOME development projects, though.

openSUSE Tumbleweed user

openSUSE Leap user

Spec file

Changes file

When it comes to .changes files, we try to be as much consistent as possible. Let's see then what specifics are expected to be used when contributing to packaging for openSUSE's GNOME development projects.

Layout of changes file entries

Standard bullet points

Level one bullet points are always a - (minus);
Level two bullet points are always a + (plus);
Level three bullet points are always a - (minus);
Level four bullet points are always a . (period).

Examples

Version update. A.K.A. version bump

This is how a simple version bump looks like:

-------------------------------------------------------------------
Mon Feb 06 00:00:00 UTC 2023 - Geeko, The Chameleon <geeko@opensuse.org>

- Update to version x.y.z:
  + This is change number one.
  + This is change number two.
  + This is change number three:
    - This is change a.
    - This is change b.
    - This is change c:
      . This is change foo.
      . This is change bar.
      . This is change baz.

Multi-version update

This is how a multiple version bump -- when more than one version got released upstream without the openSUSE package getting updated accordingly -- looks like:

-------------------------------------------------------------------
Mon Feb 06 00:00:00 UTC 2023 - Geeko, The Chameleon <geeko@opensuse.org>

- Update to version x.y.z:
  ...
- Changes from version a.b.c:
  ...

Translation-related entries

Whenever a language translation gets added, or just updated, we only use one second level bullet point to sum them up (and it should be the last second level bullet point):

-------------------------------------------------------------------
Mon Feb 06 00:00:00 UTC 2023 - Geeko, The Chameleon <geeko@opensuse.org>

- Update to version x.y.z:
  ...
  + Updated translations.

Packages that use OBS services

When a package uses a _service facility to produce a(n) tarball/archive while using the option to generate changes entries automatically out of Git commits, remember that they need to be edited in order to fit the above standards. It may look like this at first:

-------------------------------------------------------------------
Mon Feb 06 00:00:00 UTC 2023 - geeko@opensuse.org

- Update to version x.y.z:
  * First change.
  * Second change.
  * Third change, with a looooooooooooooooooooooooooooooooooooooong line.
  * Fourth change with another looooooooooooooooooooooooooooooooooooong line.
  * Fifth change with yet another looooooooooooooooooooooooooooooooong line.

However, it should look more like this, instead:

-------------------------------------------------------------------
Mon Feb 06 00:00:00 UTC 2023 - Geeko, The Chameleon <geeko@opensuse.org>

- Update to version x.y.z:
  + First change.
  + Second change.
  + Third change, with a wrapped looooooooooooooooooooooooooooooong
    line.
  + Fourth change with another wrapped
    looooooooooooooooooooooooooooooooooooong line.
  + Fifth change with yet another wrapped loooooooooooooooooooooong
    line.

Please don't forget to make sure that the header contains full name <email>, rather than just the email (this is a shortcoming of the obs-service-tar_scm package, hopefully it will get fixed).

Wrapping the line when it gets longer than 67 characters is a guidelines that any project, not just openSUSE GNOME, should follow!

Glossary

Here you can look up some terms used in this page that you may not be familiar with.

Upstream and downstream - The idea here is that an organization, in our case the GNOME project, -- or just an individual -- develops/maintains open source software, the goodies. And whenever they release their goodies up in the stream, whoever is downstream -- openSUSE, many other Linux distributions, other operating systems like the BSD family (FreeBSD, NetBSD, OpenBSD, and others), individual, etc -- benefits from the river flow to get to those goodies.