forked from materialsproject/pymatgen
-
Notifications
You must be signed in to change notification settings - Fork 0
/
contributing.html
247 lines (236 loc) · 13.6 KB
/
contributing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Collaborative Github Workflow — pymatgen 2019.5.1 documentation</title>
<link rel="stylesheet" href="_static/proBlue.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-33990148-1']);
_gaq.push(['_trackPageview']);
</script>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pymatgen 2019.5.1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="collaborative-github-workflow">
<h1>Collaborative Github Workflow<a class="headerlink" href="#collaborative-github-workflow" title="Permalink to this headline">¶</a></h1>
<p>For developers interested in expanding pymatgen for their own purposes, we
recommend forking pymatgen directly from the
<a class="reference external" href="https://github.com/materialsproject/pymatgen">pymatgen GitHub repo</a>. Here’s a typical workflow (adapted from
<a class="reference external" href="http://www.eqqon.com/index.php/Collaborative_Github_Workflow">http://www.eqqon.com/index.php/Collaborative_Github_Workflow</a>):</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Ignore the Github fork queue. Let the maintainer of pymatgen worry about
the fork queue.</p>
</div>
<ol class="arabic">
<li><p>Create a free GitHub account (if you don’t already have one) and perform the
necessary setup (e.g., install SSH keys etc.).</p></li>
<li><p>Fork the pymatgen GitHub repo, i.e., go to the main
<a class="reference external" href="https://github.com/materialsproject/pymatgen">pymatgen GitHub repo</a> and click fork to create a copy of the pymatgen code
base on your own Github account.</p></li>
<li><p>Install git on your local machine (if you don’t already have it).</p></li>
<li><p>Clone <em>your forked repo</em> to your local machine. You will work mostly with
your local repo and only publish changes when they are ready to be merged:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">git</span><span class="nd">@github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">YOURNAME</span><span class="o">/</span><span class="n">pymatgen</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>Note that the entire Github repo is fairly large because of the presence of
test files, but these are absolutely necessary for rigorous testing of the
code.</p>
</li>
<li><p>It is highly recommended you install all the optional dependencies as well.</p></li>
<li><p>Code (see <a class="reference internal" href="#coding-guidelines">Coding Guidelines</a>). Commit early and commit often. Keep your
code up to date. You need to add the main repository to the list of your
remotes. Let’s name the upstream repo as mpmaster (materialsproject master).</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">mpmaster</span> <span class="n">git</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">materialsproject</span><span class="o">/</span><span class="n">pymatgen</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>Make sure your repository is clean (no uncommitted changes) and is currently
on the master branch. If not, commit or stash any changes and switch to the
master.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
</pre></div>
</div>
<p>Then you can pull all the new commits from the main line</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">pull</span> <span class="n">mpmaster</span> <span class="n">master</span>
</pre></div>
</div>
<p>Remember, pull is a combination of the commands fetch and merge, so there may
be merge conflicts to be manually resolved.</p>
</li>
<li><p>Publish your contributions. Assuming that you now have a couple of commits
that you would like to contribute to the main repository. Please follow the
following steps:</p>
<ol class="loweralpha">
<li><p>If your change is based on a relatively old state of the main repository,
then you should probably bring your repository up-to-date first to see if
the change is not creating any merge conflicts.</p></li>
<li><p>Check that everything compiles cleanly and passes all tests.
The pymatgen repo comes with a complete set of tests for all modules. If
you have written new modules or methods, you must write tests for the new
code as well (see <a class="reference internal" href="#coding-guidelines">Coding Guidelines</a>). Install and run nosetest in your
local repo directory and fix all errors before continuing further. There
must be <strong>no errors</strong> for the nosetest.</p></li>
<li><p>If everything is ok, publish the commits to your github repository.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span> <span class="n">origin</span> <span class="n">master</span>
</pre></div>
</div>
</li>
</ol>
</li>
<li><p>Now that your commit is published, it doesn’t mean that it has already been
merged into the main repository. You should issue a merge request to
pymatgen’ maintainers. They will pull your commits and run their own tests
before releasing.</p></li>
</ol>
</div>
<div class="section" id="coding-guidelines">
<h1>Coding Guidelines<a class="headerlink" href="#coding-guidelines" title="Permalink to this headline">¶</a></h1>
<p>Given that pymatgen is intended to be long-term code base, we adopt very strict
quality control and coding guidelines for all contributions to pymatgen. The
following must be satisfied for your contributions to be accepted into pymatgen.</p>
<ol class="arabic simple">
<li><p><strong>Unittests</strong> are required for all new modules and methods. The only way to
minimize code regression is to ensure that all code are well-tested. If the
maintainer cannot test your code, the contribution will be rejected.</p></li>
<li><p><strong>Python PEP 8</strong> <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">code style</a>.
We allow a few exceptions when they are well-justified (e.g., Element’s
atomic number is given a variable name of capital Z, in line with accepted
scientific convention), but generally, PEP 8 must be observed.</p></li>
<li><p><strong>Python 3</strong>. All code should seamless work with Python 2.7 and Python 3.x.
Please read <a class="reference external" href="https://docs.python.org/3/howto/pyporting.html">Python’s official guidelines</a> on how to write Python 3.x
compatible code, including the usage of the “six” package. It is recommended
that you install the “python-modernize” package and run it before submitting
any pull requests.</p></li>
<li><p><strong>Documentation</strong> required for all modules, classes and methods. In
particular, the method docstrings should make clear the arguments expected
and the return values. For complex algorithms (e.g., an Ewald summation), a
summary of the alogirthm should be provided, and preferably with a link to a
publication outlining the method in detail.</p></li>
<li><p><strong>IDE</strong>. We highly recommend the use of Pycharm or Eclipse + PyDev. You
should also set up pylint and pep8 and turn those on within the IDE setup.
This will warn of any issues with coding styles.</p></li>
</ol>
<p>For the above, if in doubt, please refer to the core classes in pymatgen for
examples of what is expected.</p>
<div class="section" id="a-word-on-coding-for-python-3-compatibility">
<h2>A word on coding for Python 3 compatibility<a class="headerlink" href="#a-word-on-coding-for-python-3-compatibility" title="Permalink to this headline">¶</a></h2>
<p>With effect from version 3.0, all pymatgen code must be both Python 2.7+ and 3
compatible. Specifically, we have adopted the following practices throughout
pymatgen.</p>
<ol class="arabic">
<li><p><strong>Unicode-always.</strong> Unless you are absolutely sure you need byte literals
(rare for pymatgen), always use unicode. In particular, the following should
be the first line of all pymatgen modules:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="k">import</span> <span class="n">division</span><span class="p">,</span> <span class="n">print_function</span><span class="p">,</span> <span class="n">unicode_literals</span>
</pre></div>
</div>
<p>Future division means that 1/2 returns a float (0.5),
which is more intuitive scientifically, instead of 0 (default integer
division in Python 2). print_function ensures that print() is used instead
of the print statement. And unicode_literals makes it such that all
strings are treated as unicode by default. If you need to use bytes,
those should be marked up explicitly as b’byte literal’.</p>
</li>
<li><p><strong>Use of the six package</strong>. Where necessary, use the six package to handle
interoperability between Python 2 and 3. Examples include the six.moves
functions (common ones are zip, filter, map), and six.stringtypes (testing
for string types, which should be rarely done).</p></li>
<li><p><strong>Python-modernize</strong>. Use python-modernize to check your code for any
potential changes that need to be made.</p></li>
<li><p><strong>Unit testing</strong>. The entire pymatgen code base is continuously being
tested in both Python 2.7 and >=3.3. If your code fails either of the
tests, you need to fix it.</p></li>
</ol>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Collaborative Github Workflow</a></li>
<li><a class="reference internal" href="#coding-guidelines">Coding Guidelines</a><ul>
<li><a class="reference internal" href="#a-word-on-coding-for-python-3-compatibility">A word on coding for Python 3 compatibility</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/contributing.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">pymatgen 2019.5.1 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011, Pymatgen Development Team.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.0.1.
</div>
<div class="footer">This page uses <a href="http://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script type="text/javascript">
(function() {
var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ?
'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga);
})();
</script>
</div>
</body>
</html>