.. _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 `_, 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 `_). To see that Bazaar is installed and knows about you, try the following: .. code-block:: bash $ bzr whoami Joe Coder This should display your name and email. Next, you will want to create an account on the `Launchpad website `_ and setup your ssh keys. For more information of setting up your ssh keys, see `this link `_. 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 `_, 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 `. * All code has tests. How to write and run tests is described in :ref:`this section `. * 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 ` 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 ` 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 ` 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