Metadata-Version: 1.0
Name: flr
Version: 0.0.4
Summary: Fedora Lib Rel-Eng
Home-page: https://pagure.io/flr
Author: Adam Miller
Author-email: maxamillion@fedoraproject.org
License: GPLv2+
Description: 
        
        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
Platform: UNKNOWN
