infra-docs-fpo/modules/release_guide/pages/contributing.adoc

== 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 https://pagure.io/releng[releng git repository] hosted on
https://pagure.io/pagure[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 http://www.git-scm.com[git]
repository (where the source reStructured Text version of these docs
live), you should first have a
https://admin.fedoraproject.org/accounts[Fedora Account System] (FAS)
account, log into https://pagure.io[pagure.io] and the fork the
https://pagure.io/releng[releng git repository].

Once you've forked the https://pagure.io/releng[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.

[source,bash]
----
$ git remote add upstream https://pagure.io/releng.git
----

[NOTE]
.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
"http://www.git-scm.com/book/en/v2/Git-Branching-Branching-Workflows#Topic-Branches[Topic
Branch]" based workflow in git nomenclature. This is how Fedora Release
Engineering contributors can submit changes to the
https://pagure.io/releng[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.

* https://pagure.io/koji[koji] -Build System used by Fedora
* https://pagure.io/mash[mash] -Tool that creates repositories from koji
tags, and solves them for multilib dependencies.
* https://pagure.io/pungi[pungi] -Fedora Compose tool
* https://github.com/release-engineering/product-definition-center[Product
Defintion Center (PDC)] -Repository and API for storing and querying
product metadata
* https://github.com/release-engineering/koji-containerbuild[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.

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