Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
tree: afef5c0f52
Fetching contributors…

Cannot retrieve contributors at this time

85 lines (61 sloc) 3.569 kb
.. _contributing:
============================
How to contribute to IPython
============================
Overview
========
IPython development is done using Git [Git]_ and Github.com [Github.com]_.
(Github Ipython Repository: [IPyGithub]_) 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
.. [Git] The Git version control system. http://git-scm.com
.. [Github.com] Github.com. http://github.com
.. [IPyGithub] IPython repository on github. https://github.com/ipython/ipython
Jump to Line
Something went wrong with that request. Please try again.