======================= 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