##// END OF EJS Templates
doc: add link to ipython on github
Valentin Haenel -
Show More
@@ -1,82 +1,84
1 .. _contributing:
1 .. _contributing:
2
2
3 ============================
3 ============================
4 How to contribute to IPython
4 How to contribute to IPython
5 ============================
5 ============================
6
6
7 Overview
7 Overview
8 ========
8 ========
9
9
10 IPython development is done using Git [Git]_ and Github.com [Github.com]_.
10 IPython development is done using Git [Git]_ and Github.com [Github.com]_.
11 This makes it easy for people to contribute to the development of IPython.
11 (Github Ipython Repository: [IPyGithub]_) This makes it easy for people to
12 There are several ways in which you can join in.
12 contribute to the development of IPython. There are several ways in which you
13 can join in.
13
14
14
15
15 Merging a branch into trunk
16 Merging a branch into trunk
16 ===========================
17 ===========================
17
18
18 Core developers, who ultimately merge any approved branch (from themselves,
19 Core developers, who ultimately merge any approved branch (from themselves,
19 another developer, or any third-party contribution) will typically use
20 another developer, or any third-party contribution) will typically use
20 :command:`git merge` to merge the branch into the trunk and push it to the main
21 :command:`git merge` to merge the branch into the trunk and push it to the main
21 Git repository. There are a number of things to keep in mind when doing this,
22 Git repository. There are a number of things to keep in mind when doing this,
22 so that the project history is easy to understand in the long run, and that
23 so that the project history is easy to understand in the long run, and that
23 generating release notes is as painless and accurate as possible.
24 generating release notes is as painless and accurate as possible.
24
25
25 * When you merge any non-trivial functionality (from one small bug fix to a
26 * When you merge any non-trivial functionality (from one small bug fix to a
26 big feature branch), please remember to always edit the appropriate file in
27 big feature branch), please remember to always edit the appropriate file in
27 the :ref:`What's new <whatsnew_index>` section of our documentation.
28 the :ref:`What's new <whatsnew_index>` section of our documentation.
28 Ideally, the author of the branch should provide this content when they
29 Ideally, the author of the branch should provide this content when they
29 submit the branch for review. But if they don't it is the responsibility of
30 submit the branch for review. But if they don't it is the responsibility of
30 the developer doing the merge to add this information.
31 the developer doing the merge to add this information.
31
32
32 * When merges are done, the practice of putting a summary commit message in
33 * When merges are done, the practice of putting a summary commit message in
33 the merge is *extremely* useful. It is probably easiest if you simply use
34 the merge is *extremely* useful. It is probably easiest if you simply use
34 the same list of changes that were added to the :ref:`What's new
35 the same list of changes that were added to the :ref:`What's new
35 <whatsnew_index>` section of the documentation.
36 <whatsnew_index>` section of the documentation.
36
37
37 * It's important that we remember to always credit who gave us something if
38 * It's important that we remember to always credit who gave us something if
38 it's not the committer. In general, we have been fairly good on this front,
39 it's not the committer. In general, we have been fairly good on this front,
39 this is just a reminder to keep things up. As a note, if you are ever
40 this is just a reminder to keep things up. As a note, if you are ever
40 committing something that is completely (or almost so) a third-party
41 committing something that is completely (or almost so) a third-party
41 contribution, do the commit as::
42 contribution, do the commit as::
42
43
43 $ git commit --author="Someone Else <who@somewhere.com>"
44 $ git commit --author="Someone Else <who@somewhere.com>"
44
45
45 This way it will show that name separately in the log, which makes it even
46 This way it will show that name separately in the log, which makes it even
46 easier to spot. Obviously we often rework third party contributions
47 easier to spot. Obviously we often rework third party contributions
47 extensively, but this is still good to keep in mind for cases when we don't
48 extensively, but this is still good to keep in mind for cases when we don't
48 touch the code too much.
49 touch the code too much.
49
50
50
51
51
52
52
53
53 Commit messages
54 Commit messages
54 ===============
55 ===============
55
56
56 Good commit messages are very important; they provide a verbal account of what
57 Good commit messages are very important; they provide a verbal account of what
57 happened that is often invaluable for anyone trying to undestand the intent of
58 happened that is often invaluable for anyone trying to undestand the intent of
58 a commit later on (including the original author!). And git's log command is a
59 a commit later on (including the original author!). And git's log command is a
59 very versatile and powerful tool, capable of extracting a lot of information
60 very versatile and powerful tool, capable of extracting a lot of information
60 from the commit logs, so it's important that these logs actually have useful
61 from the commit logs, so it's important that these logs actually have useful
61 information in them.
62 information in them.
62
63
63 In short, a commit message should have the form::
64 In short, a commit message should have the form::
64
65
65 One line summary.
66 One line summary.
66 <THIS LINE MUST BE LEFT BLANK>
67 <THIS LINE MUST BE LEFT BLANK>
67 More detailed description of what was done, using multiple lines and even
68 More detailed description of what was done, using multiple lines and even
68 more than one paragraph if needed. For very simple commits this may not be
69 more than one paragraph if needed. For very simple commits this may not be
69 necessary, but non-trivial ones should always have it.
70 necessary, but non-trivial ones should always have it.
70
71
71 Closes gh-NNN. # if the commit closes issue NNN on github.
72 Closes gh-NNN. # if the commit closes issue NNN on github.
72
73
73 This format is understood by many git tools that expect a *single line*
74 This format is understood by many git tools that expect a *single line*
74 summary, so please do respect it.
75 summary, so please do respect it.
75
76
76 An excellent reference on commits message is `this blog post`_, please take a
77 An excellent reference on commits message is `this blog post`_, please take a
77 moment to read it (it's short but very informative).
78 moment to read it (it's short but very informative).
78
79
79 .. _this blog post: http://who-t.blogspot.com/2009/12/on-commit-messages.html
80 .. _this blog post: http://who-t.blogspot.com/2009/12/on-commit-messages.html
80
81
81 .. [Git] The Git version control system. http://git-scm.com
82 .. [Git] The Git version control system. http://git-scm.com
82 .. [Github.com] Github.com. http://github.com
83 .. [Github.com] Github.com. http://github.com
84 .. [IPyGithub] IPython repository on github. https://github.com/ipython/ipython
General Comments 0
You need to be logged in to leave comments. Login now