Statistics
| Branch: | Revision:

iof-tools / networkxMiCe / networkx-master / CONTRIBUTING.rst @ 5cef0f13

History | View | Annotate | Download (5.56 KB)

1
Developer overview
2
==================
3

    
4
1. If you are a first-time contributor:
5

    
6
   * Go to `https://github.com/networkx/networkx
7
     <https://github.com/networkx/networkx>`_ and click the
8
     "fork" button to create your own copy of the project.
9

    
10
   * Clone the project to your local computer::
11

    
12
      git clone git@github.com:your-username/networkx.git
13

    
14
   * Add the upstream repository::
15

    
16
      git remote add upstream git@github.com:networkx/networkx.git
17

    
18
   * Now, you have remote repositories named:
19

    
20
      - ``upstream``, which refers to the ``networkx`` repository
21
      - ``origin``, which refers to your personal fork
22

    
23
2. Develop your contribution:
24

    
25
   * Pull the latest changes from upstream::
26

    
27
      git checkout master
28
      git pull upstream master
29

    
30
   * Create a branch for the feature you want to work on. Since the
31
     branch name will appear in the merge message, use a sensible name
32
     such as 'bugfix-for-issue-1480'::
33

    
34
      git checkout -b bugfix-for-issue-1480
35

    
36
   * Commit locally as you progress (``git add`` and ``git commit``)
37

    
38
3. To submit your contribution:
39

    
40
   * Push your changes back to your fork on GitHub::
41

    
42
      git push origin bugfix-for-issue-1480
43

    
44
   * Go to GitHub. The new branch will show up with a green Pull Request
45
     button---click it.
46

    
47
   * If you want, post on the `mailing list
48
     <http://groups.google.com/group/networkx-discuss>`_ to explain your changes or
49
     to ask for review.
50

    
51
For a more detailed discussion, read these :doc:`detailed documents
52
<gitwash/index>` on how to use Git with ``networkx``
53
(`<https://networkx.github.io/documentation/latest/developer/gitwash/index.html>`_).
54

    
55
4. Review process:
56

    
57
    * Reviewers (the other developers and interested community members) will
58
      write inline and/or general comments on your Pull Request (PR) to help
59
      you improve its implementation, documentation, and style.  Every single
60
      developer working on the project has their code reviewed, and we've come
61
      to see it as friendly conversation from which we all learn and the
62
      overall code quality benefits.  Therefore, please don't let the review
63
      discourage you from contributing: its only aim is to improve the quality
64
      of project, not to criticize (we are, after all, very grateful for the
65
      time you're donating!).
66

    
67
    * To update your pull request, make your changes on your local repository
68
      and commit. As soon as those changes are pushed up (to the same branch as
69
      before) the pull request will update automatically.
70

    
71
    * `Travis-CI <https://travis-ci.org/>`_, a continuous integration service,
72
      is triggered after each Pull Request update to build the code and run unit
73
      tests of your branch. The Travis tests must pass before your PR can be merged.
74
      If Travis fails, you can find out why by clicking on the "failed" icon (red
75
      cross) and inspecting the build and test log.
76

    
77
    * `AppVeyor <http://ci.appveyor.com>`_, is another continuous integration
78
      service, which we use.  You will also need to make sure that the AppVeyor
79
      tests pass.
80

    
81
.. note::
82

    
83
   If closing a bug, also add "Fixes #1480" where 1480 is the issue number.
84

    
85
Divergence between ``upstream master`` and your feature branch
86
--------------------------------------------------------------
87

    
88
Never merge the main branch into yours. If GitHub indicates that the
89
branch of your Pull Request can no longer be merged automatically, rebase
90
onto master::
91

    
92
   git checkout master
93
   git pull upstream master
94
   git checkout bugfix-for-issue-1480
95
   git rebase master
96

    
97
If any conflicts occur, fix the according files and continue::
98

    
99
   git add conflict-file1 conflict-file2
100
   git rebase --continue
101

    
102
However, you should only rebase your own branches and must generally not
103
rebase any branch which you collaborate on with someone else.
104

    
105
Finally, you must push your rebased branch::
106

    
107
   git push --force origin bugfix-for-issue-1480
108

    
109
(If you are curious, here's a further discussion on the
110
`dangers of rebasing <http://tinyurl.com/lll385>`_.
111
Also see this `LWN article <http://tinyurl.com/nqcbkj>`_.)
112

    
113
Guidelines
114
----------
115

    
116
* All code should have tests.
117
* All code should be documented, to the same
118
  `standard <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#docstring-standard>`_
119
  as NumPy and SciPy.
120
* All changes are reviewed.  Ask on the
121
  `mailing list <http://groups.google.com/group/networkx-discuss>`_ if
122
  you get no response to your pull request.
123

    
124
Stylistic Guidelines
125
--------------------
126

    
127
* Set up your editor to remove trailing whitespace.
128
  Follow `PEP08 <www.python.org/dev/peps/pep-0008/>`_.
129
  Check code with `pyflakes` / `flake8`.
130

    
131
* Use the following import conventions::
132

    
133
   import numpy as np
134
   import scipy as sp
135
   import matplotlib as mpl
136
   import matplotlib.pyplot as plt
137
   import networkx as nx
138

    
139
   cimport numpy as cnp # in Cython code
140

    
141
Pull request codes
142
------------------
143

    
144
When you submit a pull request to GitHub, GitHub will ask you for a summary.  If
145
your code is not ready to merge, but you want to get feedback, please consider
146
using ``WIP: experimental optimization`` or similar for the title of your pull
147
request. That way we will all know that it's not yet ready to merge and that
148
you may be interested in more fundamental comments about design.
149

    
150
When you think the pull request is ready to merge, change the title (using the
151
*Edit* button) to remove the ``WIP:``.
152

    
153
Developer Notes
154
---------------
155

    
156
For additional information about contributing to NetworkX, please see
157
the `Developer Notes <https://github.com/networkx/networkx/wiki>`_.
158

    
159
Bugs
160
----
161

    
162
Please `report bugs on GitHub <https://github.com/networkx/networkx/issues>`_.