Introduction

If you are reading this post that means you are interested in contributing to Package Hub. You have come to the right place. I’ll share with you the process I followed while doing my internship at Linux Foundation. During the internship I worked on different softwares and packaged them for s390x machines. Thanks to IBM LinuxONE Community Cloud because of which I was able to get a s390x machine for packaging and testing of ported packages. If you are interested you can request a three month trial. I hope this blog post will help you understand the process better. Please remember to visit SUSE documentation also to get more insight and latest updates.

SUSE Package Hub

SUSE Package Hub contains popular open source packages for SUSE Linux Enterprise Server (SLES). SUSE Package Hub packages are built and maintained by a community of users and “packagers” utilizing the Open Build Service (OBS). That means you don’t need to build everything alone yourself! If you want to use an open source software package on your SLES and want that SLES remains supported and supportable when using the software, you should use the package available in SUSE Package Hub. If you need a newer version or the software package is not available in SUSE Package Hub you can always contribute and the purpose of this post is to explain the process of contributing to SUSE Package HUB using Open Build service.

openSUSE Backports

openSUSE Backports or openSUSE:Backports is the community project maintaining the packages that feed into SUSE Package Hub. These packages are built using the openSUSE Build Service a publically hosted instance of the Open Build Service. The packages are essentially copies of packages from openSUSE distributions built for use with SUSE Linux Enterprise products.

Factory Project

Factory is built in its own project openSUSE:Factory on public OBS server. The project contains large number of packages and maintains the rolling development codebase for openSUSE Tumbleweed and openSUSE Leap distributions. The exact same packages qualified and approved for those distributions is used for the SUSE Package Hub. So, any package that is going into SUSE Package Hub must be first checked into openSUSE:Factory.

Devel Projects

All the development work for the packages in openSUSE:Factory project is done in packages present in respective devel projects. All the contributions to a package like bug fixing, version upgrate etc, are submitted to the pacakge in devel project. You can get a list of current devel projects that are feeding to openSUSE:Factory here.

Engaging with Maintainers

The one important thing you should do before you start contributing is to reach out to maintainers of pacakges and top level projects. Since they are the maintainers and know best about the state of the packages and projects they can guide you where is the room for improvement and where to branch from. Engage with maintainers tell them what are you trying to do and why. Contacting the maintainers at start will result in quicker acceptance of submit requests by maintainers since they already know what you are trying to do. You can get the information about maintainer(s) of an package using following commands, in this case project is server:monitoring and package is cacti

$ osc maintainer server:monitoring cacti
<maintainer_username>
$ osc whois <maintainer_username>
Contact information will be printed

Mailing Lists

Another great source of information is Opensuse mailing lists. Here you will find discussions between community of packagers. Opensuse-packaging, opensuse-buildservice, opensuse-factory lists can be very helpful for you in packaging. You can subscribe to these mailing lists and get your questions directly answered by the great experienced community.

Concept

The main concept is that in order to contribute to SUSE Package Hub you need to have an account on OBS public server. Then you can submit your work to a devel project and subsequently to openSUSE:Factory. Once your contribution reaches in openSUSE:Factory project you are ready to create a submit (maintenance) request to openSUSE:Backports. If your request to Backports is accepted your work will be automatically submitted to SUSE Package Hub.

Getting Ready

SUSE Package Hub packages are built and maintained utilizing the Open Build Service (OBS). OBS system enables developers and package maintainers to build and distribute packages from sources in an automatic, consistent and reproducible way. So, first you need to register an account at OBS server here. After registering the account, you should install and setup the OSC tool on your computer. The rest of the blog assumes that you have completed these two steps.

Contributing to Existing Software Package:

Open build service contains almost all popular open source software packages and chances are that the software you are interested in is already present in a project on OBS server. Let us assume that the package you are interested in is already present in openSUSE:Factory project and you want to contribute to that. The contribution could be a bux fix, version upgrade, adding a functionality or even adding support for another architecture etc. As said earlier, when you are satisfied with the package in openSUSE:Factory you can send the package to Package Hub by a making a submit request. Let us assume that the original software package you want to work on is cacti and OBS username is testuser

<username> testuser
<original_package> cacti

Now, let us now look at the steps invloved

1. Step: Devel Project

   Find the devel project for the package and branch from there. To find devel project you can use OSC. For example, if you want to know about the devel project of the cacti package in openSUSE:Factory project you can use following command

   $ osc develproject openSUSE:Factory cacti
   server:monitoring

   So server:monitoring is the devel project for openSUSE:Factory/cacti package.

2. Step: Branching

   Now branch the pacakge from the devel project using the command

   $ osc branch server:monitoring cacti

   This will create a new branch project

   home:<your_user_name>:branches:<original_project_name>

3. Step: Checkout

   You should now checkout the package to download all the files from the server to a local directory. The generic command for checking out a branched package is

   osc checkout home:<your_user_name>:branches:<original_project_name>/<original_package_name>

   In our case the command will be

   $ osc checkout home:testuser:branches:server:monitoring/cacti

   This will download the files from the server to local directory

   home:testuser:branches:server:monitoring/cacti

   Go to the directory and set usual default mask to 0022 $ cd home:testuser:branches:server:monitoring/cacti $ umask 0022

4. Step: Make Changes

   Go to the local directory and make changes you want. You may

   • Fix a bug in the package
   • Make changes to specfile (eg to add support for an architecture like s390x, or to update the version of package)

5. Step: Building Package Locally build the package to verify any changes you made. To get the possible build targets for your package use following command inside the local directory

   $ osc repos
   openSUSE_Tumbleweed    x86_64
   openSUSE_Tumbleweed    i586
   openSUSE_Leap_42.3        x86_64
   openSUSE_Leap_15.0        x86_64
   SLE_12_SP1                       x86_64
   SLE_12_Backports              s390x

   The output is a two column table. First column represents the REPOSITORY and second column represents ARCH. Lets say you are intersted in s390x and SLE_12_Backports then use the following command to build the package

   $ osc build SLE_12_Backports s390x

6. Step: Test the Package

   If the package is successfully built that means, there are no build errors and you can further test your changes by installing it on the machine. If you are using zypper you can install the package

   $ zypper in -f <PATH-TO-RPM>

   Once you are satisfied that the changes you have made are working fine you are ready to commit the changes to server.

7. Step: Record Changes

   The changes files should be updated to record changes you made to the package. If you have fixed a bug you can refer to it using bnc#xxxxxx. Run following command in local directory to edit the changes file

   $ osc vc

8. Step: Update Version Control Status

   Now its time to update the version control status. Run following command in local directory

   $ osc addremove

   After doing this make sure there are no files with status “!” or “?”. You can check this by running the command

   $ osc status

9. Step: Commit to OBS Server

   If all the files have correct status you are ready to upload the local source files into the already branched package on OBS server. Once upload completes an automatic re-build is triggered for the package. Run the following command to commit

   $ osc commit

10. Step: Verify Build Result on Server

    Once the build at server is completed you should verify that build is “succeeded” for all build repositories that are enabled for the original package. You can check this through webpage or by using following osc command in local directory

    $ osc results –verbose SLE_12_SP3                        s390x             succeeded(unpublished) SLE_12_SP3                        arch64           failed SLE_12_SP3                        ppc64le         succeeded(unpublished) SLE_12_SP2                        x86_64          succeeded(unpublished) SLE_12_SP1_Backports      x86_64          succeeded(unpublished) SLE_11_SP4                        i586               disabled

11. Step: Submit Changes to Original Package

    If build for all the desired repositories have a “succeeded” status create a submit request to original package by running the following command

    $ osc submitrequest –message=’Right a short message that tells about your changes’ home:testuser:branches:server:monitoring cacti server:monitoring cacti

    This will create a request from your branched package to original package. The command will ouput a request id remember that. The maintainer will either accept or decline the request.

12. Step: Status of Request

    You can check the status of your submit request using osc. You can get the username of the maintainer and his email address using osc commands. This could be useful if there is a need to contact the maintainer

    $ osc request show <submit_request id>
    Request hisotry will be printed
    $ osc maintainer server:monitoring cacti
    <maintainer_username>
    $ osc whois <maintainer_username>
    Contact information will be printed

13. Step: Submit to Facatory

    If the maintainer is happy with your submit request and accepts it, you are now ready to submit the changes to Factory. Make a submit request to Factory

    $ osc submitrequest –message=’A messge for Factory’ server:monitoring/cacti openSUSE:Factory cacti

14. Step: Submit to Backports

    After request to Factory is accepted. Make a submit request, a maintenance request, to Backports (SLE12) using the following command

    $ osc submitrequest openSUSE:Factory/cacti openSUSE:Backports:SLE-12

    Once the Package Hub team is happy with the request the package will be moved to SUSE Package Hub.

Contributing New Software Package:

A new software package, package not already in Factory, can be submitted to openSUSE factory through a devel project. Devel projects act as feeders to openSUSE:Factory project. Packages from home: namespace are not allowed to be directly submitted to Factory. You can get a list of current devel projects that are feeding to openSUSE:Factory here.

1. Step: Select Devel Project

   So, first you need to find an appropriate devel project where you can maintain your package. For example if you want to maintain a package that provides network monitoring functionalities an appropriate devel project would be server:monitoring. If you think you need a new devel project you can always ask the maintainers of an existing top-level project and ask them to create a subproject for you. If there is no suitable top-level project then you can ask OBS maintainers to create a project for you by opening a bug or contacting them at admin@opensuse.org.

2. Step: Devel Project Whitelist

   So you have a new devel project for your new package but Factory does not know about them yet. The submit request from this new devel project will be auto-declined by Factory project. So, the new project needs to be added to devel-whitelist and you can do this by asking in #openSUSE-factory IRC channel. The new project will be able to successfully feed the packages to Factory once it added to devel-whitelist. If you select an already present devel project that can feed into Factory you do not need this step.

3. Step: Submit Package to Devel project

   After you have a devel project, which is able to feed to Factory, you can now submit your package to this devel project.

   $ osc submitrequest -m ‘ Maintaining <package-name> in Factory with <devel-project-name> as devel project.’ home:username/<package-name> <devel-project-name>

4. Step: Submit Package to Factory

   Submiting to Factory is easy now, just create a submit request from your devel project to Factory. Please write a description of your new package in the submit request so that it can serve as an introduction to openSUSE:Factory.

   $ osc submitrequest -m ‘ This is a new package. Add description or a link that gives detail about the new package. ‘ <devel-project-name> openSUSE:Factory

5. Step: Submit Package to Backports

   Submit to Backports to get the package in to SUSE Package Hub (SLE12)

   $ osc submitrequest openSUSE:Factory/<package-name> openSUSE:Backports:SLE-12

   Again once the Package Hub team is happy with the request the package will be moved to SUSE Package Hub.

Conclusion

In this post, I tried to summarize the steps involved in contributing to openSUSE:Factory project and SUSE Package Hub. I hope that after reading this blog post you have gained more understanding on how to contribute to Factory and SUSE Package Hub using Open Build Service.

Acknowledgements

I thank Linux Foundation for providing me with the opportunity to work on this great open source project. I also thank my mentor Wolfgang Engel from SUSE who guided and helped me in uderstanding the process.