============================
Public development on github
============================

The workflow describe here is mainly inspired from 
IPython development workflow and especially from a
Fernando Perez message (unfortunatly these links are no more available).

Steps to follow are :

  - configure git and github
  - fork github project you want to work on
  - create a new //branch// with explicit name (ex: //fix_app_crash_mac_os_10_9//)
  - work on your new branch
  - **prepare your work for merging**
  - submit your pull request


Configure git
=============

"--global" refer to your username on your computer. **So you need to config only once for you.**

If you want a specific config for a specific project, please use "--local"

.. code-block:: bash

    git config --global user.name "my name"
    git config --global user.email myemail@foo.com
    git config --global push.default simple
    git config --global core.editor <your_favorite_editor>

Log on github
=============

To start, you must create a github account and log in.

Fork github project
===================

On git, you **never work directly on official repository** but only on your personal repository.
Do do that, you must create a clone of the repository (a "fork") on your personal area just by clicking on **fork button**.

You can see in top-left corner : 

  yourname/project
  forked from othername/project


Now, clone it on your computer.
Just copy url displayed on your web browser and pass it to git clone command:

.. code-block:: bash

    git clone https://github.com/yourname/project


Add a reference to official repository.
.. code-block:: bash

    git remote add upstream https://github.com/official/project


Create development branch
=========================

You must create a branch for each new feature, bug fix, and so on.
Development must be short : **one branch = one task**

Please choose an explicit name for your new branch.

**If upstream_master do not exists yet**

.. code-block:: bash

    git checkout upstream/master -b upstream_master
    git checkout -b fix_app_crash_mac_os_10_9

**else**

.. code-block:: bash

    git checkout upstream_master
    git pull
    git checkout -b fix_app_crash_mac_os_10_9

Work on your development branch
===============================


.. code-block:: bash

    # edit file(s)
    git commit
    git add mynewfile.py
    git commit
    # edit file(s)
    git commit


Save your branch and commits on your personal repository on github

.. code-block:: bash

    git push origin fix_app_crash_mac_os_10_9



Commit message
==============

Please write a `good commit message <http://web-design-weekly.com/blog/2013/09/01/a-better-git-commit/>`_:

Try to limit using the -m commit flag. git commit -m "A crappy commit message" and use git commit with **no flags**.

If using the simpler git commit command it should open up Vim (if it’s your default editor) where you can construct a better commit by following some of these simple steps.

      * The **first line should be a short summary**. Referencing the bug number or the main accomplishment of the change. e.g “Fixes issue #8976″. This is the title of your commit and should be **less than 50 characters**.
      * Then a **line break**.
      * Followed by a **longer detailed description about the things that changed**. This section is a really good place to explain what and why. You could cover statistics, performance wins, roadblocks, etc. The text should be wrapped at 72 characters.

Prepare your work for merging
=============================

Before asking other to integrate your work, you must clean it.
First get last modifications and work on a new branch created especially for cleaning. 

.. code-block:: bash

    git fetch upstream
    git checkout upstream_master
    git pull
    git checkout fix_app_crash_mac_os_10_9
    git checkout -b rebased-fix_app_crash_mac_os_10_9 # create and checkout new branch
    git rebase --interactive fix_app_crash_mac_os_10_9 
    git rebase --interactive upstream_master



.. code-block:: bash

    git rebase --interactive upstream_master fix_app_crash_mac_os_10_9

If master has diverged during your work, conflicts can occur !
If your shell ask you to fix it directly, you should do it using "e" command. 
That works very well if you've defined your favorite editor.

Else, fix conflicts foreach file and finish rebase :

.. code-block:: bash

    # edit file1 and solve conflicts
    git add file1 # say to git that conflict is resolved
    # edit file2 and solve conflicts
    git add file2
    git rebase --continue



If rebase has gone wrong, for example you've rebased the wrong branch, you can cancel it with
.. code-block:: bash

    git rebase --abort


See `git rebase --interactive <https://help.github.com/articles/interactive-rebase>`_ for further information.


.. code-block:: bash

    git push origin rebased-fix_app_crash_mac_os_10_9

Submit your pull-request
========================

On github interface, select your branch fix_app_crash_mac_os_10_9 and click on pull-request (or compare & pull-request).

You must see at right :


    Able to merge
    These branches can be automatically merged 


If it's not the case, master has probably diverged. You must turn back to previous step and do it again.

Now it is OK ! 
As your branch is very clean, other developpers have absolutely nothing to do to integrate your work (except to review your changes) and so they will certainly integrate it.


Maintainer: merge pull-request
==============================

This work is done in two steps :

  - review work (read modifications, test it, ...)
  - integrate it (merge)


To review work, just checkout pull-request. See github documentation : 
`Checkout pull request <https://help.github.com/articles/checking-out-pull-requests-locally>`_.

If pull-request is ok, just click on "merge pull-request"