docs/source/development/contributing.txt

.. _contributing:

============================
How to contribute to IPython
============================

Overview
========

IPython development is done using Bazaar [Bazaar]_ and Launchpad [Launchpad]_.
This makes it easy for people to contribute to the development of IPython.
There are several ways in which you can join in.

If you have a small change that you want to contribute, you can edit your
Bazaar checkout of IPython (see below) in-place, and ask Bazaar for the
differences:

.. code-block:: bash

    $ cd /path/to/your/copy/of/ipython
    $ bzr diff > my_fixes.diff

This produces a patch file with your fixes, which we can apply to the source
tree. This file should then be attached to a ticket in our `bug tracker
<https://bugs.launchpad.net/ipython>`_, indicating what it does.

This model of creating small, self-contained patches works very well and there
are open source projects that do their entire development this way. However,
in IPython we have found that for tracking larger changes, making use of
Bazaar's full capabilities in conjunction with Launchpad's code hosting
services makes for a much better experience.

Making your own branch of IPython allows you to refine your changes over time,
track the development of the main team, and propose your own full version of
the code for others to use and review, with a minimum amount of fuss. The next
parts of this document will explain how to do this.

Install Bazaar and create a Launchpad account
---------------------------------------------

First make sure you have installed Bazaar (see their `website
<http://bazaar-vcs.org/>`_). To see that Bazaar is installed and knows about
you, try the following:

.. code-block:: bash

    $ bzr whoami
    Joe Coder <[e-mail]>

This should display your name and email. Next, you will want to create an
account on the `Launchpad website <http://www.launchpad.net>`_ and setup your
ssh keys. For more information of setting up your ssh keys, see `this link
<https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair>`_.

Get the main IPython branch from Launchpad
------------------------------------------

Now, you can get a copy of the main IPython development branch (we call this
the "trunk"):

.. code-block:: bash

    $ bzr branch lp:ipython

Create a working branch
-----------------------

When working on IPython, you won't actually make edits directly to the
:file:`lp:ipython` branch. Instead, you will create a separate branch for your
changes. For now, let's assume you want to do your work in a branch named
"ipython-mybranch". Create this branch by doing:

.. code-block:: bash

    $ bzr branch ipython ipython-mybranch

When you actually create a branch, you will want to give it a name that
reflects the nature of the work that you will be doing in it, like
"install-docs-update".

Make edits in your working branch
---------------------------------

Now you are ready to actually make edits in your :file:`ipython-mybranch`
branch. Before doing this, it is helpful to install this branch so you can
test your changes as you work. This is easiest if you have setuptools
installed. Then, just do:

.. code-block:: bash

    $ cd ipython-mybranch
    $ python setupegg.py develop

Now, make some changes. After a while, you will want to commit your changes.
This let's Bazaar know that you like the changes you have made and gives you
an opportunity to keep a nice record of what you have done. This looks like
this:

.. code-block:: bash

    $ ...do work in ipython-mybranch...
    $ bzr commit -m "the commit message goes here"

Please note that since we now don't use an old-style linear ChangeLog (that
tends to cause problems with distributed version control systems), you should
ensure that your log messages are reasonably detailed.  Use a docstring-like
approach in the commit messages (including the second line being left
*blank*)::

  Single line summary of  changes being committed.

  * more details when warranted ...
  * including crediting outside contributors if they sent the
    code/bug/idea!

As you work, you will repeat this edit/commit cycle many times. If you work on
your branch for a long time, you will also want to get the latest changes from
the :file:`lp:ipython` branch. This can be done with the following sequence of
commands:

.. code-block:: bash

    $ ls
    ipython
    ipython-mybranch
    
    $ cd ipython
    $ bzr pull
    $ cd ../ipython-mybranch
    $ bzr merge ../ipython
    $ bzr commit -m "Merging changes from trunk"

Post your branch and request a code review
------------------------------------------

Once you are done with your edits, you should post your branch on Launchpad so
that other IPython developers can review the changes and help you merge your
changes into the main development branch. To post your branch on Launchpad,
do:

.. code-block:: bash

    $ cd ipython-mybranch
    $ bzr push lp:~yourusername/ipython/ipython-mybranch

Then, go to the `IPython Launchpad site <http://www.launchpad.net/ipython>`_,
and you should see your branch under the "Code" tab. If you click on your
branch, you can provide a short description of the branch as well as mark its
status. Most importantly, you should click the link that reads "Propose for
merging into another branch". What does this do?

This let's the other IPython developers know that your branch is ready to be
reviewed and merged into the main development branch. During this review
process, other developers will give you feedback and help you get your code
ready to be merged. What types of things will we be looking for:

* All code is documented.  How to document your code is described in 
  :ref:`this section <documenting-ipython>`.
* All code has tests.  How to write and run tests is described in 
  :ref:`this section <testing>`.
* The entire IPython test suite passes.

You should also provide us with a list of changes that your branch contains.
See the :ref:`What's new <whatsnew_index>` section of our documentation
(:file:`docs/source/whatsnew`) for details on the format and content of this.

Once your changes have been reviewed and approved, someone will merge them
into the main development branch.


Merging a branch into trunk
===========================

Core developers, who ultimately merge any approved branch (from themselves,
another developer, or any third-party contribution) will typically use
:command:`bzr merge` to merge the branch into the trunk and push it to the
main Launchpad site. There are a number of things to keep in mind when doing
this, so that the project history is easy to understand in the long
run, and that generating release notes is as painless and accurate as
possible.

* When you merge any non-trivial functionality (from one small bug fix to a
  big feature branch), please remember to always edit the appropriate file in
  the :ref:`What's new <whatsnew_index>` section of our documentation.
  Ideally, the author of the branch should provide this content when they
  submit the branch for review. But if they don't it is the responsibility of
  the developer doing the merge to add this information.

* When merges are done, the practice of putting a summary commit message in
  the merge is *extremely* useful. It is probably easiest if you simply use
  the same list of changes that were added to the :ref:`What's new
  <whatsnew_index>` section of the documentation.

* It's important that we remember to always credit who gave us something if
  it's not the committer. In general, we have been fairly good on this front,
  this is just a reminder to keep things up. As a note, if you are ever
  committing something that is completely (or almost so) a third-party
  contribution, do the commit as::
  
    $ bzr commit --author="Someone Else"

  This way it will show that name separately in the log, which makes it even
  easier to spot. Obviously we often rework third party contributions
  extensively, but this is still good to keep in mind for cases when we don't
  touch the code too much.


.. [Bazaar] Bazaar. http://bazaar-vcs.org/
.. [Launchpad] Launchpad. http://www.launchpad.net/ipython