contributing.txt
190 lines
| 7.8 KiB
| text/plain
|
TextLexer
Brian Granger
|
r2276 | 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. |