flr - Fedora Lib RelEng

Note

This is still under active development and should not be considered production ready or feature complete.

This is a library dedicated to making Release Engineering tasks for Fedora as generic and re-usable as possible with the primary goal to make all scripts housed in the Fedora Release Engineering pagure git repo be small simple glue code around calls to functions found within these library modules.

Also, there are a series of small comand line tools meant to expose the Python API to the user via the command line. These utilities should be small as they are meant to perform effectively "one thing" such that they can easily be delegated via sudo permissions for RelEng Automation. These utilities are written using click.

The topmost object namespace in flr is mostly just an indexing logical namespace, with the real work being broken up into submodules targets named after systems that we interact with and/or make modifications to.

An example layout is as follows:

This submodule logical layout is intended to grow organically over time as needed.

flr
├── flr.rpm
├── flr.koji
├── flr.mash
├── flr.sigul
├── flr.pungi
├── flr.disk
├── flr.datagrepper
├── flr.dkr
└── flr.fedmsg

Directory layout of this git repository:

  • flr
    • Source code of the Fedora Lib RelEng
  • docs
    • Documentation of the project in Sphinx Doc format
  • tests
    • Tests, run with runtests.sh (uses pytest for tests)

Contribution Guidelines

Below are guidelines that should be followed when submitting code to flr.

Style

Code should be PEP8.

User Experience

Command line utils should use click and multi-word commands for the command line utilities that expose the API should be implemented in a similar pattern as follows.

import click
import flr.foo

@click.group()
def cli():
    pass

@click.command()
@click.argument('bar')
def some_command(bar):
    print (bar)

cli.add_command(some_command, name="some-command")

if __name__ == '__main__':
    cli()

The desire is to have all small command-line utilities in flr have a similar unified "feel" from an user perspective.

Development Workflow

In this repository you will find two "main" branches, master and develop. All development should happen in develop and pull requests from the Release Engineering Tooling Development Team as well as the more broad Fedora Community of contributors will go to develop.

The master branch is meant to be the current stable branch that has all tests passing and has passed a code audit. This does not mean that the master branch is always the latest release but simply that the code is stable and in a known good state. Releases will happen as point in time snapshots of master via git tag operation.

Example

An example of a developer's workflow is shown in the diagram below using * to indicate a merge event.

[master]    ---+-------------------------------*------------------------>
                \                             /
              [rebase]          [pull request, code audit/review]
                  \                         /
[develop]   -------*--*----+-------+-------+------------*-------------->
                     /              \                  /
              [pull request]     [rebase]       [pull request]
[contrib           /                  \              /
topic       ------+--------------------*------------+------------------>
branch]

Here a contributing developer will submit pull requests from a topic branch within their own fork of this repository to the develop branch. Once this is done then a standard review will take place by a member of the Fedora RelEng Group in FAS and they will merge the code into develop.

At the point in time there is a desire to merge the develop branch into master because a major feature is complete or otherwise, a new pull request should be filed by a member of the Fedora RelEng Team and a code audit and final review will begin.

The develop branch should always be rebased on master when necessary.

Security Audits and Final Review

Currently the following people are approved for code security audits and final code review. However, no one should ever audit and merge their own code, no matter if they are on this list or not.

Releases

Releases are managed by git tag and tarballs can be downloaded from the release location provided by pagure.

How Releases Are Prepared

For developers working on flr that want to cut a release or for those who are curious how releases are done, the following is the process.

In the example below we are releasing the 0.0.2 version.

$ git checkout master

$ git tag 0.0.2

$ git push --tags

$ git archive --format=tar.gz --prefix=flr-0.0.2/ 0.0.2 > /tmp/flr-0.0.2.tar.gz

The resulting file /tmp/flr-0.0.2.tar.gz would then be uploaded using the Pagure Release Page.