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 master branch of the local git clone of your releng repository clone.

    $ git checkout master
    
  • Pull upstream and merge into local master to make sure that your master 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 master
    $ git push origin master
    
  • Create a topic branch from master.

    $ 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 master again and merge upstream/master so that we can resolve any conflicts locally.

    $ git checkout master
    $ git pull --rebase upstream master
    $ git push origin master
    
  • Rebase on master before submitting a pull request

    $ git rebase master
    
    ..... 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 master 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. - master, 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 master branch even while using a topic branch as follows:

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

$ pullupstream master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.
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 master branch in order to resolve any merge conflicts that may come up for clean pull request submission.

$ git rebase master
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.