|
|
.. _contributing:
|
|
|
|
|
|
============================
|
|
|
How to contribute to IPython
|
|
|
============================
|
|
|
|
|
|
Overview
|
|
|
========
|
|
|
|
|
|
IPython development is done using Git_ and Github_ (`Github Ipython Repository`_).
|
|
|
This makes it easy for people to contribute to the development of IPython.
|
|
|
There are several ways in which you can join in.
|
|
|
|
|
|
|
|
|
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:`git merge` to merge the branch into the trunk and push it to the main
|
|
|
Git repository. 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::
|
|
|
|
|
|
$ git commit --author="Someone Else <who@somewhere.com>"
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Commit messages
|
|
|
===============
|
|
|
|
|
|
Good commit messages are very important; they provide a verbal account of what
|
|
|
happened that is often invaluable for anyone trying to undestand the intent of
|
|
|
a commit later on (including the original author!). And git's log command is a
|
|
|
very versatile and powerful tool, capable of extracting a lot of information
|
|
|
from the commit logs, so it's important that these logs actually have useful
|
|
|
information in them.
|
|
|
|
|
|
In short, a commit message should have the form::
|
|
|
|
|
|
One line summary.
|
|
|
<THIS LINE MUST BE LEFT BLANK>
|
|
|
More detailed description of what was done, using multiple lines and even
|
|
|
more than one paragraph if needed. For very simple commits this may not be
|
|
|
necessary, but non-trivial ones should always have it.
|
|
|
|
|
|
Closes gh-NNN. # if the commit closes issue NNN on github.
|
|
|
|
|
|
This format is understood by many git tools that expect a *single line*
|
|
|
summary, so please do respect it.
|
|
|
|
|
|
An excellent reference on commits message is `this blog post`_, please take a
|
|
|
moment to read it (it's short but very informative).
|
|
|
|
|
|
.. _this blog post: http://who-t.blogspot.com/2009/12/on-commit-messages.html
|
|
|
.. _Github IPython Repository: ipython_github_
|
|
|
|
|
|
.. include:: ../links.rst
|
|
|
|
