|
|
.. _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 <jcoder@gmail.com>
|
|
|
|
|
|
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
|
|
|
|
