IPython on GitHub#
Attention
This is copied verbatim from the old IPython wiki and is currently under development. Much of the information in this part of the development guide is out of date.
Notes on working with GitHub
Milestones#
100% of confirmed issues should have a milestone.
An issue should never be closed without a milestone.
All pull requests should have a milestone.
All issues closed should be marked with the next release milestone, next backport milestone, or no action.
Open issues should only lack a milestone if:
more clarification is required (label:
needs-info
)
In general, there will be four milestones with open issues:
next minor release. This milestone contains issues that should be backported for the next minor release. See below for information on backporting.
next major release. This should be the default milestone of all issues. As the release approaches, issues can be explicitly bumped to next release + 1.
next major release + 1. Only issues that we are confident will not be included in the next release go here. This milestone should be mostly empty until relatively close to release.
wishlist. This is the milestone for issues that we have no immediate plans to address.
The remaining milestone is no action for open or closed issues that require no action:
Not actually an issue (e.g. questions, discussion, etc.)
Duplicate of an existing Issue
Closed because we won’t fix it
When an issue is closed with no action, it means that the issue will not be fixed, or it was not an issue at all.
When closing an issue, it should always have one of these milestones:
next minor release because the issue has been addressed
next major release because the issue has been addressed
no action because the issue will not be addressed, or it is a duplicate/non-issue.
In general: When in doubt, mark with next release. We can always push back when we get closer to a given release.
Labels and issues#
Issues should always be labeled once they are confirmed (not necessary for issues that are still being clarified, or may be duplicates or not issues at all).
Some significant labels:
needs-info
: issue needs more information from submitter before progress can be madebug
: errors are raised, or unintended behavior occursenhancement
: improvements that are not bugsbackport-X.Y.Z: Any fix for this issue should be backported to the maintenance branch. backports are expressed with milestones, starting with 2.1.
prio-foo
: a priority level for ranking issues - nonessential, but prio-high/low are useful for explicitly promoting/demoting issues, particularly when nearing release.ClosedPR
: This issue is a reminder for a PR that was closed for going stale.sprint-friendly
: Obvious or easy fixes, where
All confirmed issues should at least have a bug
or enhancement
label, and be marked with any affected components (e.g parallel
,
qtconsole
, htmlnotebook
), or particular sources of error (e.g.
py3k
or unicode
) if we have appropriate labels.
The sprint-friendly
label is probably the best place for new
contributors to start.
Pull Requests#
All work is submitted via Pull Requests.
Pull Requests can be submitted as soon as there is code worth discussing. Pull Requests track the branch, so you can continue to work after the PR is submitted. Review and discussion can begin well before the work is complete, and the more discussion the better. The worst case is that the PR is closed.
Pull Requests that have stalled should be closed (see [[our policy on closing PRs|Dev: Closing Pull Requests]])
Pull Requests should always be made against master (backporting PRs is described below).
Pull Requests should be tested, if feasible:
bugfixes should include regression tests
new behavior should at least get minimal exercise
Travis does a pretty good
job testing IPython and Pull Requests, but it may make sense to manually
perform tests (possibly with our test_pr
script), particularly for
PRs that affect IPython.parallel
or Windows.
Opening an Issue#
When opening a new issue, please take the following steps:
Search GitHub and/or Google for your issue to avoid duplicate reports. Keyword searches for your error messages are most helpful.
If possible, try updating to master and reproducing your issue, because we may have already fixed it.
Try to include a minimal reproducible test case
Include relevant system information. Start with the output of:
python -c "import IPython; print(IPython.sys_info())"
And include any relevant package versions, depending on the issue, such as matplotlib, numpy, Qt, Qt bindings (PyQt/PySide), tornado, web browser, etc.
Backporting#
We should keep an
A.x
maintenance branch for backporting fixes from master.That branch shall be called
A.x
, e.g.2.x
, not2.1
. This way, there is only one maintenance branch per release series.When an Issue is determined to be appropriate for backporting, it should be marked with the
A.B
milestone.Any Pull Request which addresses a backport issue should also receive the same milestone.
Patches are backported to the maintenance branch by applying the pull request patch to the maintenance branch (currently with the backport_pr script).