Contributor's Guide
====================

.. contents:: :depth: 1


Where the Code Lives
---------------------
The upstream git repo is on `GitHub <https://github.com/storaged-project/blivet>`_.

Branching Model
----------------
Blivet uses a branching model that allows for concurrent development of
multiple major and minor versions. Since blivet provides a public API,
we use semantic versioning to convey basic information about the
compatibility of various releases. Each minor release gets its own
branch (``x.y-devel``). All work for ``2.1.2`` will be merged onto
``2.1-devel``, for example.

Releases
^^^^^^^^^
Releases will be made on separate branches (``x.y-release``) and marked
by tags, eg: ``blivet-2.0.1``.

git-merge, git-rebase, git-cherry-pick
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Blivet's workflow is based on merges. Cherry-picking and rebasing
(except, of course, rebasing a feature branch prior to merging) are
to be avoided if at all possible. What we want is for all instances
of a given commit to have the same commit id. We want to avoid
rewriting history.

**NOTE**: The exception to this is `rhel7-branch` and `rhel6-branch`,
which both get most of their commits by cherry-picking.
Perhaps this should change?

Guidelines for Commits
-----------------------
Please make sure ``make check test`` passes with your patches applied
before opening a pull request.

Commit Messages
^^^^^^^^^^^^^^^^
The first line should be a succinct description of what the commit
does. If your commit is fixing a bug in Red Hat's bugzilla instance,
you should add `` (#123456)`` to the end of the first line of the
commit message. The next line should be blank, followed (optionally)
by a more in-depth description of your changes. Here's an example::

    Wait for auto-activation of LVs when lvmetad is running. (#1261621)

    When lvmetad is running, activating the last PV in a VG will trigger
    automatic activation of the LVs. This happens asynchronously, however,
    so we have to just wait for it to be done. Since it is possible to
    configure which VGs/LVs get auto-activated, we only wait for 30
    seconds. After that, we will try to activate the LV ourselves.

Commits for RHEL Branches
^^^^^^^^^^^^^^^^^^^^^^^^^^
If you are submitting a patch for any rhel-branch, the last line of your commit
message must identify the bugzilla bug id it fixes, using the ``Resolves`` or
``Related`` keyword, e.g.:

``Resolves: rhbz#1111111``

or

``Related: rhbz#1234567``

Use ``Resolves`` if the patch fixes the core issue which caused the bug.
Use ``Related`` if the patch fixes an ancillary issue that is related to, but
might not actually fix the bug.

**NOTE**: If you're using ``Resolves`` or ``Related`` you should omit the bug id
reference from the first line of the commit message.

Creating a Pull Request
------------------------
When creating a pull request for blivet you have to give some thought
to what branch to base your pull request on. You should choose the
branch corresponding to the oldest ``x.y`` release that should include
your work. If we are currently working toward a ``2.1.0`` release and
your pull request is a bug fix, you'll want to apply it at least as
far back as ``2.0-devel``.

Note that there is a minimum review period of 24 hours for any patch.
The purpose of this rule is to ensure that all interested parties have
an opportunity to review every patch.  When posting a patch before or
after a holiday break it is important to extend this period as
appropriate.

Merging a Pull Request
-----------------------
After hitting the big green button, you will also need to merge your
work to other active development branches and to ``master``.

- if your work is on ``x.y-devel``, merge it onto ``x.{y+1}-devel``

    For example, if your pull request was against ``2.0-devel`` and
    you already merged it, now you have to merge it to ``2.1-devel``.
    Here's how you do it:

    ``git checkout 2.1-devel``

    ``git merge --no-ff 2.0-devel``

    Take a look to make sure things are as expected, then...

    ``git push``

- if there is no ``x.{y+1}-devel``, merge it onto ``{x+1}.y`` branches
  as appopriate, oldest-to-newest

  For example, if you already merged onto ``2.1-devel`` and there is
  no ``2.2-devel``, the next place to merge would be ``3.0-devel`` if
  it exists, followed by ``3.1-devel``, &c.

- after you have merged your work onto all applicable devel
  branches, merge it from the highest-version devel branch onto
  ``master``

If the merge of your work onto a given branch has significant
conflicts, you should open a separate pull request against that
branch.
