So you've encountered some cool software on the interwebz – or better yet, you've written it yourself! You pop open the terminal and launch your package manager to install the program... and zoinks, it's not available in the repository. As you download the program and try to figure out how to compile the source, you think to yourself: wouldn't it be nice to have this in the repository and not have to worry about potential breakages (e.g. when dependent libraries change) and handling updates?

Be the change you want to see! In this article, I'll describe the process of getting a package into the Fedora official repository, and how the package's lifecycle inside the distribution looks like.

Step 1: packaging

The first step on the road to bringing a package into Fedora is, of course, packaging. (You can read about that in my previous articles – [1], [2]). If you want to become a package maintainer, you'll have to write an RPM spec file and build the package in your local environment. Once you feel the package is ready for inclusion in the distro, you can go ahead and file a package review request in RedHat bugzilla.

Step 2: package review

After you submit a review request, you must then wait for a review (rather unsurprising, I know). Reviews are performed by the community, so it can take a while before someone bothers to review your package. Often, reviewers will only leave a couple of small comments, without performing a full review. It's good to address these comments as soon as possible to display your dedication to packaging and maintaining the software in the future.

In most cases, a package review ends with one of the following events:

Approval: the package is determined fit for inclusion in the distribution. The person submitting the review request can then proceed to the next phase.

Rejection: the package is deemed not suitable for being included in Fedora. This outcome is usually caused by legal issues (such as licensing or patents). Sometimes a package may get rejected because it bundles too much other software, or because one of those dependencies (may even be a build-time-only dependency!) is not acceptable in Fedora for whatever reason.

Marking as duplicate: another person submitted a review request for a package containing the same upstream project. Unless the old review has been stalled for a long time, or is of poor quality, the new review request will be closed as DUPLICATE .

Abandonment: the person who submitted the review request either loses interest, or no longer has enough time to tend to their package. The review request may eventually get closed as a DEADREVIEW.

If nobody wants to review your package, you can write on the devel mailing list and ask for help. It's good manners to offer doing a review in return – a so called "review swap". If someone already reviewed your package and stopped responding, you may try reaching out to them personally, e.g. catch them hanging out on the IRC channel.

Either way, once your package gets reviewed and approved, it's time to use your packager privileges to request a new package. Unless you don't have these, in which case...

Step 2.5: getting sponsored into the packager group

If you're not yet a packager, you need to become one before being able to request a new package (duh). In order to do this, you need to find a person with sponsor privileges who'll be willing to sponsor you into the packagers group.

Before you can get sponsored, you need to display a good knowledge of the Packaging Guidelines, as well as general community code of conduct. This is usually achieved by reviewing a couple other packages. Note that these don't have to be full reviews – a simple comment like "you do X, but the Guidelines say you should do Y" will be good enough.

This is also a good moment to head over to the devel mailing list and introduce yourself, if you haven't done that yet. Self-introduction e-mails are meant to help build a sense of community and offer newcomers to present themselves, their background, and their skills.

Step 3: requesting a new package and importing into dist-git

Once you're granted packager privileges, you can go ahead and file a ticket for a new package. This can be done manually on Fedora Release Engineering pagure, although typically the fedpkg command-line tool is used.

user $ sudo dnf install fedpkg user $ su --login rpmbuilder rpmbuilder $ fedpkg --module-name $PACKAGE_NAME request-repo $BUGZILLA_BUG_ID

If you're wondering why the name of the command is request-repo , that's because the packages themselves are stored in plain git repositories. (Well, not exactly plain, but we'll get to that in a while.) After you file a request for a new repository, you must wait some time (varying from couple of minutes up to a day) for the request to be processed and accepted. Once the repository is created, you can clone it using the fedpkg tool.

$ fedpkg clone $PACKAGE_NAME

After cloning the repository and cd'ing into it, you should import your package. This is a semi-automated process that takes your SRPM and prepares the repository to be used for building the package.

$ fedpkg import $PATH_TO_SRPM

If you paid attention to the import process, you probably noticed source files being uploaded. That's why I wrote that package repositories are not exactly plain git repos – the source files are not stored inside git, but rather using a helper service. The git repo stores a special file, sources , which contains a list of source files (the name and a SHA512 hash are stored). This allows to keep the git repos small, making the work of packagers easier. If you fail to see the benefit, think of being a co-maintainer on a package and having to pull in a couple mebibytes whenever the other person upgraded the package to a new upstream version. Or consider that proven packagers – that is, people with distro-wide write access – sometimes perform automated changes on thousands of packages at once (e.g. when the Packaging Guidelines change). If they had to download gibibytes of source files, this would take an extremely long time; by downloading only the distro-specific files, their time and traffic usage are significantly reduced.

Once you finish the import, create a commit and push it to the remote, your git work is basically finished. You can go ahead and build the package for Fedora Rawhide, which is the current development version (kind of like a rolling release, except that there's no guarantees about stability). What about the stable releases, you may ask? Stable releases use their own git branches, named fXX (like f28 for Fedora 28). Alas, you can't just create a new git branch and push it to the remote; you'll have to file a request first. As when requesting a new repository, you can do this manually on pagure, but using the fedpkg command-line tool is preferred.

$ fedpkg request-branch $BRANCH

Once the branch request(s) are processed, you can pull them, merge stuff from master and push to remote. After all of that's done, it's time to finally proceed to the next step.

Step 4: building in koji

After pushing the package into its dist-git repository, it's time to perform a build. The build system used in Fedora is called koji, and using it with fedpkg is rather straightforward.

$ fedpkg build

Running this command will trigger a new build for the current branch, using the latest commit on given branch (or, put otherwise, the HEAD). It's recommended to start with master and then follow with stable release branches, starting with the youngest (highest numbered) one.

If you're wondering what are the advantages of using koji over having maintainers build packages on their own systems and uploading that, these boil down mostly to:

Configuration: your local environment is, most likely, tweaked in various ways to make it more suitable for your liking. Some of these changes may affect the RPM build process in subtle ways. Also, if you're working on a package together with some else (co-maintaining), your system configurations may differ. As such, the resulting package can be different based on who built it. koji fixes this issue by providing a "factory settings" build environment.

Reproducibility: Thanks to the "factory settings" build environments, with koji, it's possible to record the exact versions of packages used and reenact a build; as long as the software doesn't store any build timestamps, the result package will be bit-for-bit identical.

Security: if your local environment gets compromised, it's possible for an attacker to be able to target the RPM build process. Of course, an attacker could just as well target your dist-git usage, but in this scenario, at least it's easy to pinpoint who and when introduced the problematic changes to the software.

Either way, once the koji build succeeds, you can continue on to the next step. Should the build fail for whatever reason, you should make appropriate changes to the package in the repository and try again. While working on the package, you can also perform test builds (called scratch builds). These are identical to "real" builds in terms of the build process itself; the main difference is that a scratch build cannot be later submitted as an update, and any "if this package builds, do stuff" processes that may be in place will not react to scratch builds. koji will also remove scratch builds after some time; while this happens to "real" builds, too, the lifetime for scratch builds is shorter.

$ fedpkg build --scratch

The command above will perform a scratch build for the current dist-git HEAD. If you're concerned about not polluting dist-git history with trial-and-error commits, you can build the package locally first, and then perform a scratch build using an SRPM.

$ fedpkg local $ fedpkg build --scratch --srpm $PATH_TO_SRPM

You can also perform koji scratch builds for any SRPM found on your local system; this is often done when submitting a review request, to prove that the package will actually build once imported.

$ koji build --scratch $TARGET $PATH_TO_SRPM

The $TARGET variable represents the Fedora release you want to build against. For a review request, you'll most likely use rawhide , but obviously you can also use f28 , f27 and so on.

Step 5: submitting the update to bodhi and testing

Once your package has built successfully, you can submit an update using yet another Fedora system, called bodhi. You can create an update using the bodhi web interface, or by using the fedpkg command-line tool.

$ fedpkg switch-branch $BRANCH $ fedpkg update

When using the command-line tool, you will be asked to fill out the required information via means of editing a temporary file (opened in $EDITOR ). You can specify the update type (newpackage, enhancement, bugfix, security), link to relevant bugs, and specify autopush karma (I'll explain that in a while).

After the submitting the update, the package will be pushed into updates-testing repository (although this may take a day or two). Once the package is pushed to the testing repository, distro users can then download it and give you feedback. Feedback can be, obviously, both positive and negative. Apart from just leaving a comment, bodhi allows testers to leave a simple +1/0/-1 rating for the package – called the package's karma. Once your package reaches the amount of autopush karma you specified earlier, it will be automatically pushed to stable (or un-pushed from testing, in the case of negative karma).

If your update doesn't attract any testers (or not enough testers), it can be pushed to stable once the testing period will have passed. The length of the testing period depends on which release you are submitting to:

For yet-unreleased (beta) Fedora versions, the testing period is 3 days.

For stable versions, the testing period is 1 week.

For EPEL (extra packages for RHEL/CentOS), the testing period is 2 weeks.

Step 6: maintenance

Your package has made it to the stable repository. Time to rejoice! Now all that's left is to regularly check your inbox for any e-mails from Bugzilla informing you about bugs reported against your package, and to visit the project's webpage every once in a while to check for new releases.

If you need to make any changes to the package – be it bugfixes, or updating to new upstream releases – the process is rather straightforward, as you basically repeat steps 3, 4, and 5 – make your changes to dist-git, then proceed onto building in koji and finally submit the update to bodhi.

Step 7: orphaning

At some point, you may decide that you no longer perceive the package as useful, or that it requires too much attention – more than you can spare. In such a case, as a maintainer, you can relinquish maintenance of a package. If the package doesn't have any other co-maintainers, it will become an orphan package, hence it's common to say about "orphaning" a package.

A package can also become orphaned when a maintainer is non-responsive. The process for marking a maintainer as unresponsive takes slightly over three weeks, though commonly it's only invoked as a final measure, after other attempts to contact the maintainer have been unsuccessful.

Step 8: adoption

Being orphaned doesn't necessarily mean the end of life for a package, as someone may volunteer to take over the deed of maintaining the package. This process is called adopting a package.

Adoption is usually a simple process; after the current maintainer announces on the mailing list that they're orphaning the package, the person interested in continuing the work should write a message stating their willingness to adopt the package, and open a ticket with the Release Engineering team.

Step 9: retiring

If a package has been orphaned for six weeks, it will become retired.

A package can also be "directly" retired by its maintainer, without going through the orphan period. This is typically used for software with serious security bugs or substantial usability issues, where the upstream development has ceased and there's not much hope for a new version which would address these problems. Of course, in theory, the package maintainer can keep writing relevant fixes to the software by themselves... but that takes a lot of effort and hardly any maintainer will be willing to take on the ordeal. (Not to mention that if there is enough interest, the community will probably come up with a fork.)

Step 10: un-retiring (?)

It is not dead which can eternal lie...

H. P. Lovecraft, "The Call of Cthulhu"

...and a package being retired doesn't have to mean "good bye". If there is an individual with interest the package, and enough determination to bring it back up-to-shape and up-to-date, a package can be un-retired and brought back into the distribution.

If a package has been retired for more than two weeks, it must go through another review.

Once the review's finished, the submitter must file a ticket with the Release Engineering team, asking to be made the package's new maintainer, and for the package to be marked as un-retired. Once that's done, they can go back to step 3 and start working in dist-git.

References