Contributing to SUSE Package Hub Step-by-Step
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 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 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.
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
$ osc whois
Contact information will be printed
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.
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.
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
Now, let us now look at the steps invloved
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
So server:monitoring is the devel project for openSUSE:Factory/cacti package.
Now branch the pacakge from the devel project using the command
$ osc branch server:monitoring cacti
This will create a new branch project
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:
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
Go to the directory and set usual default mask to 0022 $ cd home:testuser:branches:server:monitoring/cacti $ umask 0022
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)
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
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
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
Once you are satisfied that the changes you have made are working fine you are ready to commit the changes to server.
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
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
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
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
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.
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
Request hisotry will be printed
$ osc maintainer server:monitoring cacti
$ osc whois
Contact information will be printed
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
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.
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 firstname.lastname@example.org.
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.
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/
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. ‘
Step: Submit Package to Backports
Submit to Backports to get the package in to SUSE Package Hub (SLE12)
$ osc submitrequest openSUSE:Factory/
Again once the Package Hub team is happy with the request the package will be moved to SUSE Package Hub.
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.
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.