README.rst
=======================
flr - Fedora Lib RelEng
=======================

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

.. split here

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.

.. code-block:: python

    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.

* `Patrick Uiterwijk`_
* `Adam Miller`_

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``.

.. _flr: https://pagure.io/flr
.. _pytest: http://pytest.org/
.. _Fedora: https://getfedora.org/
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _Sphinx Doc: http://www.sphinx-doc.org/en/stable/
.. _Release Engineering: https://docs.pagure.org/releng/
.. _Fedora Release Engineering pagure git repo: https://pagure.io/releng
.. _RelEng Automation: https://pagure.io/releng-automation
.. _click: http://click.pocoo.org
.. _Patrick Uiterwijk: https://fedoraproject.org/wiki/User:Puiterwijk
.. _Adam Miller: https://fedoraproject.org/wiki/User:Maxamillion
.. _FAS: https://fedoraproject.org/wiki/Account_System
.. _git tag: https://git-scm.com/book/en/v2/Git-Basics-Tagging
.. _pagure: https://pagure.io/pagure
.. _release location: https://releases.pagure.org/flr
.. _Pagure Release Page: https://pagure.io/flr/releases
.. _topic branch:
    https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows#Topic-Branches