.. _maintainer-workflow:

###################
Maintainer workflow
###################

This page is for maintainers |emdash| those of us who merge our own or other
peoples' changes into the upstream repository.

As a maintainer, you are completely on top of the basic stuff
in :ref:`development-workflow`, of course.

The instructions in :ref:`linking-to-upstream` add a remote that has read-only
access to the upstream repo.  Being a maintainer, you've got read-write access.

It's good to have your upstream remote under a scary name, to remind you that
it's a read-write remote:

.. code-block:: bash

   $ git remote add upstream-rw git@github.com:odlgroup/odl.git
   $ git fetch upstream-rw

*******************
Integrating changes
*******************

Let's say you have some changes that need to go into trunk (``upstream-rw/master``).

The changes are in some branch that you are currently on.  For example, you are
looking at someone's changes like this:

.. code-block:: bash

   $ git remote add someone https://github.com/someone/odl.git
   $ git fetch someone
   $ git branch cool-feature --track someone/cool-feature
   $ git checkout cool-feature

So now you are on the branch with the changes to be incorporated upstream. The
rest of this section assumes you are on this branch.

A few commits
=============

If there are only a few commits, consider rebasing to upstream:

.. code-block:: bash

     # Fetch upstream changes
   $ git fetch upstream-rw
     # rebase
   $ git rebase upstream-rw/master

A long series of commits
========================

If there are a longer series of related commits, consider a merge instead:

.. code-block:: bash

   $ git fetch upstream-rw
   $ git merge --no-ff upstream-rw/master

The merge will be detected by GitHub, and should close any related pull requests automatically.

Note the ``--no-ff`` above.  This forces Git to make a merge commit, rather than
doing a fast-forward, so that this set of commits branch off trunk and then rejoin
the main history with a merge, rather than appearing to have been made directly
on top of trunk.

Check the history
=================

Now, in either case, you should check that the history is sensible and you have the right commits:

.. code-block:: bash

   $ git log --oneline --graph
   $ git log -p upstream-rw/master..

The first line above just shows the history in a compact way, with a text
representation of the history graph. The second line shows the log of commits
excluding those that can be reached from trunk (``upstream-rw/master``), and
including those that can be reached from current HEAD (implied with the ``..``
at the end). So, it shows the commits unique to this branch compared to trunk.
The ``-p`` option shows the diff for these commits in patch form.

Push to trunk
=============

.. code-block:: bash

   $ git push upstream-rw my-new-feature:master

This pushes the ``my-new-feature`` branch in this repository to the ``master``
branch in the ``upstream-rw`` repository.

.. include:: links.inc