Fedora Release Engineering Contributing Guide¶

Fedora Release Engineering works with many different utilities that are maintained in respective upstream locations. Fedora Release Engineering maintains an “Upstream First” policy such that if there is a bug in an utility or a feature needed, we pursue that upstream before entertaining the idea of carrying a Fedora specific patch.

Fedora Release Engineering also has a number of scripts and utilities that are strictly Fedora centric in order to automate tasks and processes as they relate to Fedora itself which is what is contained in the releng git repository hosted on Pagure. If you would like to contribute to something in this repository, please reference the Contributing to releng section.

Contributing to releng¶

In order to contribute to the releng git repository (where the source reStructured Text version of these docs live), you should first have a Fedora Account System (FAS) account, log into pagure.io and the fork the releng git repository.

Once you’ve forked the releng git repository, you will need to set the remote upstream git clone of your fork in order to track the official releng repository. While not mandatory, it’s conventional to call the remote upstream the name upstream which can be done with the following command while within the directory of your local git clone of your fork.

$ git remote add upstream https://pagure.io/releng.git

Note

If you are not currently familiar with git, it is highly recommended to visit git’s upstream and familiarize yourself.

http://www.git-scm.com/

RelEng Developer Workflow¶

There are many options for developer workflow, but the recommended workflow for Fedora releng repository is known as a “Topic Branch” based workflow in git nomenclature. This is how Fedora Release Engineering contributors can submit changes to the releng git repository for both code and documentation.

The general workflow is as follows:

Checkout main branch of the local git clone of your releng repository clone.
```
$ git checkout main
```
Pull upstream and merge into local main to make sure that your main branch is in line with the latest changes from upstream. Then push it to your clone so that origin knows about the changes.
```
$ git pull --rebase upstream main
$ git push origin main
```
Create a topic branch from main.
```
$ git checkout -b my-topic-branch
```

Make changes in your topic branch and commit them to your topic branch.

$ vim somefile.py

.... make some change ...

$ git add somefile.py
$ git commit -s -m "awesome patch to somefile.py"

This step is optional but recommended in order to avoid collisions when submitting upstream. Here we will checkout main again and merge upstream/main so that we can resolve any conflicts locally.
```
$ git checkout main
$ git pull --rebase upstream main
$ git push origin main
```

Rebase on main before submitting a pull request

$ git rebase main

..... Resolve any conflicts if needed ......

Push your topic branch to your fork’s origin in pagure.
```
$ git push origin my-topic-branch
```
Open a pull request in Rel Eng Pagure. https://pagure.io/releng/pull-requests

Developer Workflow Tips and Tricks¶

Below are some Fedora Release Engineering Developer Workflow Tips and Tricks used by current members of the team in order to help assist with development.

pullupstream¶

The following is an useful shell function to place in your ~/.bashrc to help automate certain aspects of the developer workflow. It will allow you to merge in the upstream main or devel branch into your forked repository for easily keeping in line with the upstream repository.

The following is the bash function to be added to your ~/.bashrc and make sure to source ~/.bashrc after adding it in order to “enable” the function.

pullupstream () {
    if [[ -z "$1" ]]; then
        printf "Error: must specify a branch name (e.g. - main, devel)\n"
    else
        pullup_startbranch=$(git describe --contains --all HEAD)
        git checkout $1
        git pull --rebase upstream $1
        git push origin $1
        git checkout ${pullup_startbranch}
    fi
}

With the function in place you can easily pull and merge in the releng main branch even while using a topic branch as follows:

$ git status
On branch docs
nothing to commit, working directory clean

$ pullupstream main
Switched to branch 'main'
Your branch is up-to-date with 'origin/main'.
Already up-to-date.
Everything up-to-date
Switched to branch 'docs'

$ git status
On branch docs
nothing to commit, working directory clean

Now that you’re back on your topic branch you can easily rebase on your local main branch in order to resolve any merge conflicts that may come up for clean pull request submission.

$ git rebase main
Current branch docs is up to date.

RelEng Upstream Tools¶

Fedora Release Engineering uses many tools that exist in their own upstream project space. These are tools that every Fedora Release Engineer should be familiar with and in the event there is a bug or a feature needed, we should participate in the respective upstream to resolve the issue first before considering carrying a Fedora specific patch.

Tools List¶

Tools Release Engineering is actively involved with upstream¶

Below are a set of tools that are centric to the Release Engineering team and our processes. We actively engage with upstreams of these projects. For these tools, we recommend the same git contribution workflow that is outlined above for this git repository.

koji - Build System used by Fedora
mash - Tool that creates repositories from koji tags, and solves them for multilib dependencies.
pungi - Fedora Compose tool
Product Defintion Center (PDC) - Repository and API for storing and querying product metadata
koji-containerbuild - Koji plugin to integrate OSBS with koji

Tools Release Engineering is actively mostly consumers of¶

Below are the set of tools that the Release Engineering team either consumes directly or as the side effect of other tools in the Release Engineering Infrastructure. Tools here should always be engaged upstream in the event of a bug or enhancement needed but are not tools that the Release Engineering team is extremely active in their continued upstream development and will defer to each upstream for recommended contributions workflow.

fedpkg - command line utility for Fedora (and EPEL) developers. It interacts with dist-git, koji, rpmbuild, git, etc.
rpkg - library for dealing with rpm packaging in a git source control (used by fedpkg)
dist-git - remote Git repository specificaly designed to hold RPM package sources.
creatrepo - A python program which generate repodata from a set of rpm files.
createrepo_c - C implementation of createrepo
oz - set of programs and classes to do automated installations of operating systems.
imagefactory - imagefactory builds images for a variety of operating system/cloud combinations.
sigul - An automated gpg signing system
mock - a tool for building packages in prestine buildroots
fedmsg - Fedora Infrastructure Message Bus
lorax - tool to build install trees and images
OpenShift - Open Source Platform as a Service by Red Hat
OSBS - set of utilities that turn OpenShift into a layered image build system
taskotron - a framework for automated task execution.
pulp - a platform for managing repositories of content, such as software packages, and pushing that content out to large numbers of consumer
crane - Crane is a small read-only web application that provides enough of the docker registry API to support “docker pull”
pagure A git centered forge
rpm-ostree - Store RPMs in OSTree repository, and atomically upgrade from commits
ostree - a tool for managing bootable, immutable, versioned filesystem trees.