-
Notifications
You must be signed in to change notification settings - Fork 189
/
Copy pathcontributing.html
162 lines (149 loc) · 11.4 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
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Contributing Code to FireWorks — FireWorks 2.0.4 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="_static/nature.css?v=b0beeceb" />
<script src="_static/documentation_options.js?v=adc66a14"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link href='https://fonts.googleapis.com/css?family=Lato:400,700' rel='stylesheet' type='text/css'>
</head><body>
<div class="related" role="navigation" aria-label="Related">
<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">FireWorks 2.0.4 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Contributing Code to FireWorks</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="contributing-code-to-fireworks">
<h1>Contributing Code to FireWorks<a class="headerlink" href="#contributing-code-to-fireworks" title="Link to this heading">¶</a></h1>
<p>FireWorks is an open-source codebase, and one if its advantages is the possibility for community contribution and improvement. If you are interested in contributing code to FireWorks, we’d be very happy to have you join the team! As a contributor, your code will be made available to the entire FireWorks community, and your name will be added to our <a class="reference internal" href="contributors.html"><span class="doc">list of contributors</span></a>.</p>
<p>We ask that all potential collaborators review our contribution criteria. You might also contact us directly at <img alt="developer contact" class="align-bottom" src="_images/mail.png" /> to let us know what you’re planning to contribute; we can discuss your plans and how to integrate your code for public release.</p>
<section id="criteria-for-inclusion">
<h2>Criteria for Inclusion<a class="headerlink" href="#criteria-for-inclusion" title="Link to this heading">¶</a></h2>
<p>Our criteria for inclusion of your code depends on the type of contribution you plan to submit.</p>
<section id="adding-new-queue-adapters-firetasks-etc">
<h3>Adding new Queue Adapters, Firetasks, etc.<a class="headerlink" href="#adding-new-queue-adapters-firetasks-etc" title="Link to this heading">¶</a></h3>
<p>If you’ve written Queue Adapters, Firetasks, Duplicate Finders, or other “plug-in” type objects that do not modify existing code, we would be very happy to include them in the main repo. The main condition for inclusion is that they be useful to a broad section of the FireWorks community.</p>
</section>
<section id="adding-new-features-or-performance-enhancements">
<h3>Adding new features or performance enhancements<a class="headerlink" href="#adding-new-features-or-performance-enhancements" title="Link to this heading">¶</a></h3>
<p>We encourage you to submit new features and enhancements to the FireWorks code. That said, please be mindful that there exists a delicate balance between adding features and maintaining simplicity and usability.</p>
<p>We request that contributors begin by submitting the simplest version of their new feature or enhancement (hopefully about 500 lines of code or less). Simple codes are easy to use, flexible to adapt later, more durable against unforeseen errors, and easier to maintain and debug. More complex features should be built on top of the simplest version in a modular way. If your feature requires thousands of lines of code to be useful at all, you might re-evaluate your implementation.</p>
</section>
<section id="modifying-core-modules">
<h3>Modifying core modules<a class="headerlink" href="#modifying-core-modules" title="Link to this heading">¶</a></h3>
<p>The core FireWorks modules are the most important of all, as they affect all users. One of our major goals is to keep the core of FireWorks lightweight, simple to use and understand, and difficult to “break”. Proposed extensions or modifications to the core modules will therefore be evaluated quite strictly; they will be accepted only if they can be implemented very cleanly (i.e., generally in under 40 lines of code) and if they are of great interest to the majority of users.</p>
</section>
<section id="documentation-coding-style-and-tests">
<h3>Documentation, coding style, and tests<a class="headerlink" href="#documentation-coding-style-and-tests" title="Link to this heading">¶</a></h3>
<p>We ask for reasonably clear documentation of modules, classes, methods, and tricky code sections (hopefully not too many of the last item!) Where possible, code within a method or class should be easy to understand without the need for additional documentation. In some cases, we may request a tutorial to clarify usage of your code to the community. In terms of programming style, some guidelines are given in <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP 8</a>, but we mainly ask that you try to follow the style of the FireWorks core modules. Depending on the complexity of the contribution, tests might need to be included along with your code.</p>
<p>However, when starting you should not be as concerned with these issues as with writing clear, succinct, and functional code. If we feel that issues such as documentation or style are preventing merging of your code with the main repo, a core developer may request your permission to re-document and/or re-style your code, and add his/her name to either the <code class="docutils literal notranslate"><span class="pre">__credits__</span></code> or <code class="docutils literal notranslate"><span class="pre">__authors__</span></code> field of your code header (your name will still be retained in the <code class="docutils literal notranslate"><span class="pre">__authors__</span></code> field).</p>
</section>
<section id="os-compatibility">
<h3>OS Compatibility<a class="headerlink" href="#os-compatibility" title="Link to this heading">¶</a></h3>
<p>FireWorks is intended to work on a range of computing platforms, all the way from local computers (e.g., automating tasks on your laptop) up to large supercomputing facilities. The core features of FireWorks should work on Linux, Macintosh, and Windows. Please be mindful of this when writing code as well as when designing unit tests.</p>
</section>
<section id="licensing">
<h3>Licensing<a class="headerlink" href="#licensing" title="Link to this heading">¶</a></h3>
<p>If you haven’t already, please read the FireWorks <a class="reference internal" href="license.html"><span class="doc">license</span></a>. Your contributions will also be distributed under this license.</p>
</section>
</section>
<section id="how-to-contribute">
<h2>How to contribute<a class="headerlink" href="#how-to-contribute" title="Link to this heading">¶</a></h2>
<p>If you’re ready to contribute, awesome! The best way is to fork the FireWorks repo on Github and develop your feature independently in your own repository. Then, when you are ready to merge back, you can submit a merge request through Github.</p>
<p>Two great tutorials for how to do this are:</p>
<ul class="simple">
<li><p>The <a class="reference external" href="http://pymatgen.org/contributing.html">Pymatgen Collaborative Workflow Guide</a>.</p></li>
<li><p>(more detailed) The <a class="reference external" href="http://www.eqqon.com/index.php/Collaborative_Github_Workflow">Eqqon Collaborative Github Workflow</a>.</p></li>
</ul>
<p>If you encounter trouble, please let us know. We look forward to your merge request!</p>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Contributing Code to FireWorks</a><ul>
<li><a class="reference internal" href="#criteria-for-inclusion">Criteria for Inclusion</a><ul>
<li><a class="reference internal" href="#adding-new-queue-adapters-firetasks-etc">Adding new Queue Adapters, Firetasks, etc.</a></li>
<li><a class="reference internal" href="#adding-new-features-or-performance-enhancements">Adding new features or performance enhancements</a></li>
<li><a class="reference internal" href="#modifying-core-modules">Modifying core modules</a></li>
<li><a class="reference internal" href="#documentation-coding-style-and-tests">Documentation, coding style, and tests</a></li>
<li><a class="reference internal" href="#os-compatibility">OS Compatibility</a></li>
<li><a class="reference internal" href="#licensing">Licensing</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-to-contribute">How to contribute</a></li>
</ul>
</li>
</ul>
</div>
<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>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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">FireWorks 2.0.4 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Contributing Code to FireWorks</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2013, Anubhav Jain.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
</div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-53488807-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>