contributing.html 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  2. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml">
  4. <head>
  5. <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  6. <title>7. Contributing to Py4J &mdash; Py4J</title>
  7. <link rel="stylesheet" href="_static/py4jdoc.css" type="text/css" />
  8. <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  9. <script type="text/javascript">
  10. var DOCUMENTATION_OPTIONS = {
  11. URL_ROOT: './',
  12. VERSION: '0.8.1',
  13. COLLAPSE_MODINDEX: false,
  14. FILE_SUFFIX: '.html',
  15. HAS_SOURCE: 'true'
  16. };
  17. </script>
  18. <script type="text/javascript" src="_static/jquery.js"></script>
  19. <script type="text/javascript" src="_static/underscore.js"></script>
  20. <script type="text/javascript" src="_static/doctools.js"></script>
  21. <link rel="author" title="About these documents" href="about.html" />
  22. <link rel="top" title="Py4J" href="index.html" />
  23. <link rel="next" title="8. Changelog" href="changelog.html" />
  24. <link rel="prev" title="6. Frequently Asked Questions" href="faq.html" />
  25. <script type="text/javascript">
  26. var _gaq = _gaq || [];
  27. _gaq.push(['_setAccount', 'UA-18626179-1']);
  28. _gaq.push(['_trackPageview']);
  29. (function() {
  30. var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  31. ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
  32. var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  33. })();
  34. </script>
  35. </head>
  36. <body>
  37. <div class="page">
  38. <div class="banner">Py4J - A Bridge between Python and Java</div>
  39. <div class="related">
  40. <h3>Navigation</h3>
  41. <ul>
  42. <li class="right" style="margin-right: 5px">
  43. <a href="genindex.html" title="General Index"
  44. accesskey="I">index</a></li>
  45. <li class="right" >
  46. <a href="py-modindex.html" title="Python Module Index"
  47. >modules</a> |</li>
  48. <li class="right" >
  49. <a href="changelog.html" title="8. Changelog"
  50. accesskey="N">next</a> |</li>
  51. <li class="right" >
  52. <a href="faq.html" title="6. Frequently Asked Questions"
  53. accesskey="P">previous</a> |</li>
  54. <li><a href="index.html">Home</a> |</li>
  55. <li><a href="download.html">Download</a> |</li>
  56. <li><a href="contents.html">Doc</a> |</li>
  57. <li><a href="https://blog.py4j.org">Blog</a> |</li>
  58. <li><a href="https://github.com/bartdag/py4j">github</a> |</li>
  59. <li><a href="about.html">About</a> &raquo;</li>
  60. </ul>
  61. </div>
  62. <div class="sphinxsidebar">
  63. <div class="sphinxsidebarwrapper">
  64. <h3><a href="contents.html">On This Page</a></h3>
  65. <ul>
  66. <li><a class="reference internal" href="#">7. Contributing to Py4J</a><ul>
  67. <li><a class="reference internal" href="#python-coding-conventions">7.1. Python Coding Conventions</a></li>
  68. <li><a class="reference internal" href="#java-coding-conventions">7.2. Java Coding Conventions</a></li>
  69. <li><a class="reference internal" href="#testing-python-code">7.3. Testing Python Code</a></li>
  70. <li><a class="reference internal" href="#testing-java-code">7.4. Testing Java Code</a></li>
  71. <li><a class="reference internal" href="#license-and-copyrights">7.5. License and Copyrights</a></li>
  72. </ul>
  73. </li>
  74. </ul>
  75. <h4>Previous topic</h4>
  76. <p class="topless"><a href="faq.html"
  77. title="previous chapter">6. Frequently Asked Questions</a></p>
  78. <h4>Next topic</h4>
  79. <p class="topless"><a href="changelog.html"
  80. title="next chapter">8. Changelog</a></p>
  81. <h3>This Page</h3>
  82. <ul class="this-page-menu">
  83. <li><a href="_sources/contributing.txt"
  84. rel="nofollow">Show Source</a></li>
  85. </ul>
  86. <div id="searchbox" style="display: none">
  87. <h3>Quick search</h3>
  88. <form class="search" action="search.html" method="get">
  89. <input type="text" name="q" size="18" />
  90. <input type="submit" value="Go" />
  91. <input type="hidden" name="check_keywords" value="yes" />
  92. <input type="hidden" name="area" value="default" />
  93. </form>
  94. <p class="searchtip" style="font-size: 90%">
  95. Enter search terms or a module, class or function name.
  96. </p>
  97. </div>
  98. <script type="text/javascript">$('#searchbox').show(0);</script>
  99. </div>
  100. </div>
  101. <div class="document">
  102. <div class="documentwrapper">
  103. <div class="bodywrapper">
  104. <div class="body">
  105. <div class="section" id="contributing-to-py4j">
  106. <h1>7. Contributing to Py4J<a class="headerlink" href="#contributing-to-py4j" title="Permalink to this headline">¶</a></h1>
  107. <div class="contents local topic" id="summary">
  108. <p class="topic-title first">Summary</p>
  109. <ul class="simple">
  110. <li><a class="reference internal" href="#python-coding-conventions" id="id1">Python Coding Conventions</a></li>
  111. <li><a class="reference internal" href="#java-coding-conventions" id="id2">Java Coding Conventions</a></li>
  112. <li><a class="reference internal" href="#testing-python-code" id="id3">Testing Python Code</a></li>
  113. <li><a class="reference internal" href="#testing-java-code" id="id4">Testing Java Code</a></li>
  114. <li><a class="reference internal" href="#license-and-copyrights" id="id5">License and Copyrights</a></li>
  115. </ul>
  116. </div>
  117. <div class="section" id="python-coding-conventions">
  118. <h2><a class="toc-backref" href="#id1">7.1. Python Coding Conventions</a><a class="headerlink" href="#python-coding-conventions" title="Permalink to this headline">¶</a></h2>
  119. <p>We follow pep8 rather stricly:</p>
  120. <ol class="arabic simple">
  121. <li>We use spaces instead of tab.</li>
  122. <li>We use four-space indents.</li>
  123. <li>Line length is 80</li>
  124. <li>Code must pass the default flake8 tests (pep8 + pyflakes)</li>
  125. </ol>
  126. <p>Code must be compatible with from Python 2.6 to the newest released version of
  127. Python.</p>
  128. <p>If external libraries must be used, they should be wrapped in a mechanism that
  129. by default does not require them (e.g., conditional imports, graceful
  130. degradation, etc.).</p>
  131. <p>Libraries used for testing and contributing (flake8, nose, tox) can be
  132. installed with pip:</p>
  133. <div class="highlight-bash"><div class="highlight"><pre>pip install -r py4j-python/requirements-test.txt
  134. <span class="c"># Run flake8</span>
  135. flake8
  136. </pre></div>
  137. </div>
  138. </div>
  139. <div class="section" id="java-coding-conventions">
  140. <h2><a class="toc-backref" href="#id2">7.2. Java Coding Conventions</a><a class="headerlink" href="#java-coding-conventions" title="Permalink to this headline">¶</a></h2>
  141. <p>We are still looking for a portable/universal code formatter, but in the
  142. meantime, try to adhere to these conventions:</p>
  143. <ol class="arabic simple">
  144. <li>We use tabs rather than spaces to indent the Java code.</li>
  145. <li>Most expressions (conditionals, loops, try/catch) are always wrapped with
  146. curly brackets.</li>
  147. </ol>
  148. </div>
  149. <div class="section" id="testing-python-code">
  150. <h2><a class="toc-backref" href="#id3">7.3. Testing Python Code</a><a class="headerlink" href="#testing-python-code" title="Permalink to this headline">¶</a></h2>
  151. <p>On the Python side, we use nose and tox:</p>
  152. <div class="highlight-bash"><div class="highlight"><pre>pip install -r py4j-python/requirements-test.txt
  153. <span class="c"># Run the full test suite</span>
  154. nosetests
  155. <span class="c"># Run only one particular test</span>
  156. nosetests py4j.tests.java_gateway_test:GatewayLauncherTest.testRedirectToDeque
  157. <span class="c"># Run all tests on all supported pythons:</span>
  158. tox
  159. </pre></div>
  160. </div>
  161. <p>New code or bug fix should ideally be accompanied by a test case.</p>
  162. <p>Because we start a JVM for most test cases, it may happen that some test fails
  163. because the process was not ready to receive a request. This is a problem we
  164. have been working on for some time now and it has been a few months since the
  165. test suite failed because of synchronization issues. If your tests constantly
  166. fail, then something is wrong with your test!</p>
  167. </div>
  168. <div class="section" id="testing-java-code">
  169. <h2><a class="toc-backref" href="#id4">7.4. Testing Java Code</a><a class="headerlink" href="#testing-java-code" title="Permalink to this headline">¶</a></h2>
  170. <p>We use JUnit to write test cases.</p>
  171. </div>
  172. <div class="section" id="license-and-copyrights">
  173. <h2><a class="toc-backref" href="#id5">7.5. License and Copyrights</a><a class="headerlink" href="#license-and-copyrights" title="Permalink to this headline">¶</a></h2>
  174. <p>Py4J does not have an official Contributor License Agreement (CLA), but it is
  175. assumed that as soon as you make a contribution (patch, code suggestion through
  176. any medium, pull requests) to Py4J, you accept that your code will be
  177. redistributed under the current license used by Py4J, i.e., the new BSD
  178. license. This is an irrevocable right to ensure that developers can use Py4J
  179. without the fear of seeing parts removed in the future.</p>
  180. <p>You maintain the full copyrights for your contributions: you are only providing
  181. a license to distribute your code without further restrictions.</p>
  182. <p>The copyright statement in the License has been standardized to:</p>
  183. <p><code class="docutils literal"><span class="pre">Copyright</span> <span class="pre">(c)</span> <span class="pre">2009-2015,</span> <span class="pre">Barthelemy</span> <span class="pre">Dagenais</span> <span class="pre">and</span> <span class="pre">individual</span> <span class="pre">contributors.</span> <span class="pre">All</span>
  184. <span class="pre">rights</span> <span class="pre">reserved.`</span></code></p>
  185. <p>Individual contributors are identified in the AUTHORS file. If you have
  186. contributed to Py4J and your name is not in AUTHORS, please open a pull
  187. request!</p>
  188. <p>If you are working for a company while contributing to Py4J, make sure that the
  189. code is yours or that your company agrees with this implied CLA.</p>
  190. <p>This approach is heavily inspired from the <a class="reference external" href="https://www.djangoproject.com/foundation/cla/faq/">Django Contributor License
  191. Agreement.</a>.</p>
  192. <p>If you have any question, do not hesitate to contact the founder of the
  193. project, <a class="reference external" href="mailto:barthelemy&#37;&#52;&#48;infobart&#46;com">Barthelemy</a>.</p>
  194. </div>
  195. </div>
  196. </div>
  197. <div class="helpbar">
  198. <h3>Questions/Feedback?</h3>
  199. <ul>
  200. <li>Try the <a href="faq.html">FAQ</a> -- It answers many questions.</li>
  201. <li>Search for information in the <a href="https://groups.google.com/a/py4j.org/forum/#!forum/py4j">archives of the py4j-users mailing list</a>, or <a href="https://groups.google.com/a/py4j.org/forum/#!forum/py4j/join">post a question</a>.</li>
  202. <li>If you notice errors with this documentation, <a href="https://github.com/bartdag/py4j/issues">open a ticket</a> and let us know. Please, only open a ticket for feedback or improvements on the docs. To get help, use the links above!</li>
  203. </ul>
  204. </div>
  205. </div>
  206. </div>
  207. <div class="clearer"></div>
  208. </div>
  209. <div class="related">
  210. <h3>Navigation</h3>
  211. <ul>
  212. <li class="right" style="margin-right: 5px">
  213. <a href="genindex.html" title="General Index"
  214. >index</a></li>
  215. <li class="right" >
  216. <a href="py-modindex.html" title="Python Module Index"
  217. >modules</a> |</li>
  218. <li class="right" >
  219. <a href="changelog.html" title="8. Changelog"
  220. >next</a> |</li>
  221. <li class="right" >
  222. <a href="faq.html" title="6. Frequently Asked Questions"
  223. >previous</a> |</li>
  224. <li><a href="index.html">Home</a> |</li>
  225. <li><a href="download.html">Download</a> |</li>
  226. <li><a href="contents.html">Doc</a> |</li>
  227. <li><a href="https://blog.py4j.org">Blog</a> |</li>
  228. <li><a href="https://github.com/bartdag/py4j">github</a> |</li>
  229. <li><a href="about.html">About</a> &raquo;</li>
  230. </ul>
  231. </div>
  232. <div class="footer">
  233. &copy; Copyright 2009-2013, Barthélémy Dagenais.
  234. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.1.
  235. </div>
  236. </div>
  237. </body>
  238. </html>