|
|
How to contribute to IPython
|
|
|
============================
|
|
|
|
|
|
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 send to the team, you can edit your
|
|
|
bazaar checkout of IPython (see below) in-place, and ask bazaar for the
|
|
|
differences::
|
|
|
|
|
|
$ 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::
|
|
|
|
|
|
$ 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")::
|
|
|
|
|
|
$ 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::
|
|
|
|
|
|
$ 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::
|
|
|
|
|
|
$ 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::
|
|
|
|
|
|
$ ...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::
|
|
|
|
|
|
$ ls
|
|
|
ipython
|
|
|
ipython-mybranch
|
|
|
|
|
|
$ cd ipython
|
|
|
$ bzr pull
|
|
|
$ cd ../ipython-mybranch
|
|
|
$ bzr merge ../ipython
|
|
|
$ bzr commit -m "Merging changes from trunk"
|
|
|
|
|
|
Along the way, you should also run the IPython test suite. You can do this
|
|
|
using the :command:`iptest` command (which is basically a customized version of
|
|
|
:command:`nosetests`)::
|
|
|
|
|
|
$ cd
|
|
|
$ iptest
|
|
|
|
|
|
The :command:`iptest` command will also pick up and run any tests you have
|
|
|
written. See :ref:`testing documentation <devel_testing>` for further details
|
|
|
on the testing system.
|
|
|
|
|
|
|
|
|
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::
|
|
|
|
|
|
$ cd ipython-mybranch
|
|
|
$ bzr push lp:~yourusername/ipython/ipython-mybranch
|
|
|
|
|
|
Then, go to the `IPython Launchpad site <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.
|
|
|
* All code has tests.
|
|
|
* The entire IPython test suite passes.
|
|
|
|
|
|
Once your changes have been reviewed and approved, someone will merge them
|
|
|
into the main development branch.
|
|
|
|
|
|
|
|
|
Some notes for core developers when merging third-party contributions
|
|
|
=====================================================================
|
|
|
|
|
|
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 Launcphad site. This is a short list of things to keep in mind when doing
|
|
|
this process, 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 :file:`changes.txt`
|
|
|
file accordingly. This file has one main section for each release, and if
|
|
|
you edit it as you go, noting what new features, bug fixes or API changes
|
|
|
you have made, the release notes will be almost finished when they are
|
|
|
needed later. This is much easier if done when you merge the work, rather
|
|
|
than weeks or months later by re-reading a massive Bazaar log.
|
|
|
|
|
|
- When big merges are done, the practice of putting a summary commit message
|
|
|
in the merge is *extremely* useful. It makes this kind of job much nicer,
|
|
|
because that summary log message can be almost copy/pasted without changes,
|
|
|
if it was well written, rather than dissecting the next-level messages from
|
|
|
the individual commits.
|
|
|
|
|
|
- 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.
|
