mirror of https://github.com/McSinyx/palace
414 lines
21 KiB
HTML
414 lines
21 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<html class="writer-html5" lang="en" >
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>Getting Involved — palace 0.2.1 documentation</title>
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!--[if lt IE 9]>
|
|
<script src="_static/js/html5shiv.min.js"></script>
|
|
<![endif]-->
|
|
|
|
|
|
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
|
<script src="_static/jquery.js"></script>
|
|
<script src="_static/underscore.js"></script>
|
|
<script src="_static/doctools.js"></script>
|
|
<script src="_static/language_data.js"></script>
|
|
|
|
<script type="text/javascript" src="_static/js/theme.js"></script>
|
|
|
|
|
|
<link rel="index" title="Index" href="genindex.html" />
|
|
<link rel="search" title="Search" href="search.html" />
|
|
<link rel="next" title="Copying" href="copying.html" />
|
|
<link rel="prev" title="Design Principles" href="design.html" />
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav">
|
|
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-scroll">
|
|
<div class="wy-side-nav-search" >
|
|
|
|
|
|
|
|
<a href="index.html" class="icon icon-home" alt="Documentation Home"> palace
|
|
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div role="search">
|
|
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p class="caption"><span class="caption-text">Table of Contents</span></p>
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorial</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="reference/index.html">Reference</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Principles</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="#">Getting Involved</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#reporting-a-bug">Reporting a Bug</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#requesting-a-feature">Requesting a Feature</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#submitting-a-patch">Submitting a Patch</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#using-github">Using GitHub</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#via-email">Via Email</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#making-a-release">Making a Release</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#style-guidelines">Style Guidelines</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#python-and-cython">Python and Cython</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#c">C++</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#restructuredtext">reStructuredText</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="copying.html">Copying</a></li>
|
|
</ul>
|
|
<p class="caption"><span class="caption-text">Quick Navigation</span></p>
|
|
<ul>
|
|
<li class="toctree-l1"><a class="reference external" href="https://pypi.org/project/palace/">Python Package Index</a></li>
|
|
<li class="toctree-l1"><a class="reference external" href="https://travis-ci.com/github/McSinyx/palace">Travis CI Build</a></li>
|
|
<li class="toctree-l1"><a class="reference external" href="https://ci.appveyor.com/project/McSinyx/palace">AppVeyor Build</a></li>
|
|
<li class="toctree-l1"><a class="reference external" href="https://github.com/McSinyx/palace">GitHub Repository</a></li>
|
|
<li class="toctree-l1"><a class="reference external" href="https://matrix.to/#/#palace-dev:matrix.org">Matrix Chat Room</a></li>
|
|
</ul>
|
|
|
|
|
|
|
|
</div>
|
|
|
|
</div>
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" aria-label="top navigation">
|
|
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="index.html">palace</a>
|
|
|
|
</nav>
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
|
|
<div class="rst-content">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
|
|
<ul class="wy-breadcrumbs">
|
|
|
|
<li><a href="index.html" class="icon icon-home"></a> »</li>
|
|
|
|
<li>Getting Involved</li>
|
|
|
|
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
<a href="_sources/contributing.rst.txt" rel="nofollow"> View page source</a>
|
|
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
<hr/>
|
|
</div>
|
|
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
|
<div itemprop="articleBody">
|
|
|
|
<div class="section" id="getting-involved">
|
|
<h1>Getting Involved<a class="headerlink" href="#getting-involved" title="Permalink to this headline">¶</a></h1>
|
|
<div class="admonition note">
|
|
<p class="admonition-title">Note</p>
|
|
<p>The development of palace is carried out on <a class="reference external" href="https://github.com/McSinyx/palace">GitHub</a>.
|
|
Since GitHub is not free software, we fully understand
|
|
if one does not want to register an account just to participate
|
|
in our development. Therefore, we also welcome patches
|
|
and bug reports sent via email.</p>
|
|
</div>
|
|
<p>First of all, thank you for using and contributing to palace! We welcome
|
|
all forms of contribution, and <a class="reference external" href="https://www.phrases.org.uk/meanings/the-more-the-merrier.html">the mo the merier</a>. By saying this, we also
|
|
mean that we much prefer receiving many small and self-contained bug reports,
|
|
feature requests and patches than a giant one. There is no limit for
|
|
the number of contributions one may or should make. While it may seem
|
|
appealing to be able to dump all thoughts and feelings into one ticket,
|
|
it would be more difficult for us to keep track of the progress.</p>
|
|
<div class="section" id="reporting-a-bug">
|
|
<h2>Reporting a Bug<a class="headerlink" href="#reporting-a-bug" title="Permalink to this headline">¶</a></h2>
|
|
<p>Before filing a bug report, please make sure that the bug has not been
|
|
already reported by searching our GitHub <a class="reference external" href="https://github.com/McSinyx/palace/issues">Issues</a> tracker.</p>
|
|
<p>To facilitate the debugging process, a bug report should at least contain
|
|
the following information:</p>
|
|
<ol class="arabic simple">
|
|
<li><p>The platform, the CPython version and the compiler used to build it.
|
|
These can be obtained from <code class="xref py py-func docutils literal notranslate"><span class="pre">platform.platform()</span></code>,
|
|
<code class="xref py py-func docutils literal notranslate"><span class="pre">platform.python_version()</span></code> and <code class="xref py py-func docutils literal notranslate"><span class="pre">platform.python_compiler()</span></code>,
|
|
respectively.</p></li>
|
|
<li><p>The version of palace and how you installed it.
|
|
The earlier is usually provided by <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">show</span> <span class="pre">palace</span></code>.</p></li>
|
|
<li><p>Detailed instructions on how to reproduce the bug,
|
|
for example a short Python script would be appreciated.</p></li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="requesting-a-feature">
|
|
<h2>Requesting a Feature<a class="headerlink" href="#requesting-a-feature" title="Permalink to this headline">¶</a></h2>
|
|
<p>Prior to filing a feature request, please make sure that the feature
|
|
has not been already reported by searching our GitHub <a class="reference external" href="https://github.com/McSinyx/palace/issues">Issues</a> tracker.</p>
|
|
<p>Please only ask for features that you (or an incapacitated friend
|
|
you can personally talk to) require. Do not request features because
|
|
they seem like a good idea. If they are really useful, they will be
|
|
requested by someone who requires them.</p>
|
|
</div>
|
|
<div class="section" id="submitting-a-patch">
|
|
<h2>Submitting a Patch<a class="headerlink" href="#submitting-a-patch" title="Permalink to this headline">¶</a></h2>
|
|
<p>We accept all kinds of patches, from documentation and CI/CD setup
|
|
to bug fixes, feature implementations and tests. These are hosted on GitHub
|
|
and one may create a local repository by running:</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">https</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">McSinyx</span><span class="o">/</span><span class="n">palace</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>While the patch can be submitted via email, it is preferable to file
|
|
a pull request on GitHub against the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch to allow more people
|
|
to review it, since we do not have any mail list. Either way, contributors
|
|
must have legal permission to distribute the code and it must be available
|
|
under <a class="reference external" href="https://www.gnu.org/licenses/lgpl-3.0.en.html">LGPLv3+</a>. Furthermore, each contributor retains the copyrights
|
|
of their patch, to ensure that the licence can never be revoked even if
|
|
others wants to. It is advisable that the author list per legal name
|
|
under the copyright header of each source file they modify, like so:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Copyright</span> <span class="p">(</span><span class="n">C</span><span class="p">)</span> <span class="mi">2038</span> <span class="n">Foo</span> <span class="n">Bar</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="section" id="using-github">
|
|
<h3>Using GitHub<a class="headerlink" href="#using-github" title="Permalink to this headline">¶</a></h3>
|
|
<ol class="arabic">
|
|
<li><p>Create a <a class="reference external" href="https://github.com/McSinyx/palace/fork">fork</a> of our repository on GitHub.</p></li>
|
|
<li><p>Checkout the source code and (optionally) add the <code class="docutils literal notranslate"><span class="pre">upstream</span></code> remote:</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">https</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">YOUR_GITHUB_USERNAME</span><span class="o">/</span><span class="n">palace</span>
|
|
<span class="n">cd</span> <span class="n">palace</span>
|
|
<span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">https</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">McSinyx</span><span class="o">/</span><span class="n">palace</span>
|
|
</pre></div>
|
|
</div>
|
|
</li>
|
|
<li><p>Start working on your patch and make sure your code complies with
|
|
the <a class="reference internal" href="#style-guidelines">Style Guidelines</a> and passes the test suit run by <a class="reference external" href="https://tox.readthedocs.io/en/latest/">tox</a>.</p></li>
|
|
<li><p>Add relevant tests to the patch and work on it until they all pass.
|
|
In case one is only modifying tests, perse may install palace using
|
|
<code class="docutils literal notranslate"><span class="pre">CYTHON_TRACE=1</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre">.</span></code> then run <a class="reference external" href="https://docs.pytest.org/en/latest/">pytest</a> directly to avoid
|
|
having to build the extension module multiple times.</p></li>
|
|
<li><p>Update the copyright notices of the files you modified.
|
|
Palace is collectively licensed under <a class="reference external" href="https://www.gnu.org/licenses/lgpl-3.0.en.html">LGPLv3+</a>,
|
|
and to protect the freedom of the users,
|
|
copyright holders need to be properly documented.</p></li>
|
|
<li><p><a class="reference external" href="https://git-scm.com/docs/git-add">Add</a>, <a class="reference external" href="https://git-scm.com/docs/git-commit">commit</a> with <a class="reference external" href="https://chris.beams.io/posts/git-commit/#seven-rules">a great message</a> then <a class="reference external" href="https://git-scm.com/docs/git-push">push</a> the result.</p></li>
|
|
<li><p>Finally, <a class="reference external" href="https://help.github.com/articles/creating-a-pull-request">create a pull request</a>. We will then review and merge it.</p></li>
|
|
</ol>
|
|
<p>It is recommended to create a new branch in your fork
|
|
(<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">-c</span> <span class="pre">what-you-are-working-on</span></code>) instead of working directly
|
|
on <code class="docutils literal notranslate"><span class="pre">master</span></code>. This way one can still sync per fork with our <code class="docutils literal notranslate"><span class="pre">master</span></code> branch
|
|
and <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span> <span class="pre">--rebase</span> <span class="pre">upstream</span> <span class="pre">master</span></code> to avoid integration issues.</p>
|
|
</div>
|
|
<div class="section" id="via-email">
|
|
<h3>Via Email<a class="headerlink" href="#via-email" title="Permalink to this headline">¶</a></h3>
|
|
<ol class="arabic">
|
|
<li><p>Checkout the source code:</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">https</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">McSinyx</span><span class="o">/</span><span class="n">palace</span>
|
|
<span class="n">cd</span> <span class="n">palace</span>
|
|
</pre></div>
|
|
</div>
|
|
</li>
|
|
<li><p>Work on your patch with tests and copyright notice included
|
|
as described above.</p></li>
|
|
<li><p><a class="reference external" href="https://git-scm.com/docs/git-format-patch">git-format-patch</a> and send it to one of the maintainers
|
|
(our emails addresses are available under <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">log</span></code>).
|
|
We will then review and merge it.</p></li>
|
|
</ol>
|
|
<p>In any case, thank you very much for your contributions!</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="making-a-release">
|
|
<h2>Making a Release<a class="headerlink" href="#making-a-release" title="Permalink to this headline">¶</a></h2>
|
|
<p>While this is meant for developers doing a palace release, contributors wishing
|
|
to improve the CI/CD may find it helpful.</p>
|
|
<ol class="arabic simple">
|
|
<li><p>Under the local repository, checkout the <code class="docutils literal notranslate"><span class="pre">master</span></code> branch
|
|
and sync with the one on GitHub using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">pull</span></code>.</p></li>
|
|
<li><p>Bump the version in <code class="docutils literal notranslate"><span class="pre">setup.cfg</span></code> and push to GitHub.</p></li>
|
|
<li><p>Create a source distribution by running <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">sdist</span></code>.
|
|
The distribution generated by this command is now referred to as <code class="docutils literal notranslate"><span class="pre">sdist</span></code>.</p></li>
|
|
<li><p>Using <a class="reference external" href="https://twine.readthedocs.io/en/latest/">twine</a>, upload the <code class="docutils literal notranslate"><span class="pre">sdist</span></code> to PyPI via <code class="docutils literal notranslate"><span class="pre">twine</span> <span class="pre">upload</span> <span class="pre">$sdist</span></code>.</p></li>
|
|
<li><p>On GitHub, tag a new release with the <code class="docutils literal notranslate"><span class="pre">sdist</span></code> attached.
|
|
In the release note, make sure to include all user-facing changes
|
|
since the previous release. This will trigger the CD services
|
|
to build the wheels and publish them to PyPI.</p></li>
|
|
<li><p>Wait for the wheel for your platform to arrive to PyPI and install it.
|
|
Play around with it for a little to make sure that everything is OK.</p></li>
|
|
</ol>
|
|
</div>
|
|
<div class="section" id="style-guidelines">
|
|
<h2>Style Guidelines<a class="headerlink" href="#style-guidelines" title="Permalink to this headline">¶</a></h2>
|
|
<div class="section" id="python-and-cython">
|
|
<h3>Python and Cython<a class="headerlink" href="#python-and-cython" title="Permalink to this headline">¶</a></h3>
|
|
<p>Generally, palace follows <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0008"><strong>PEP 8</strong></a> and <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0257"><strong>PEP 257</strong></a>,
|
|
with the following preferences and exceptions:</p>
|
|
<ul class="simple">
|
|
<li><p>Hanging indentation is <em>always</em> preferred,
|
|
where continuation lines are indented by 4 spaces.</p></li>
|
|
<li><p>Comments and one-line docstrings are limited to column 79
|
|
instead of 72 like for multi-line docstrings.</p></li>
|
|
<li><p>Cython extern declarations need not follow the 79-character limit.</p></li>
|
|
<li><p>Break long lines before a binary operator.</p></li>
|
|
<li><p>Use form feeds sparingly to break long modules
|
|
into pages of relating functions and classes.</p></li>
|
|
<li><p>Prefer single-quoted strings over double-quoted strings,
|
|
unless the string contains single quote characters.</p></li>
|
|
<li><p>Avoid trailing commas at all costs.</p></li>
|
|
<li><p>Line breaks within comments and docstrings should not cut a phrase in half.</p></li>
|
|
<li><p>Everything deserves a docstring. Palace follows <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc</a> which support
|
|
documenting attributes as well as constants and module-level variables.
|
|
In additional to docstrings, type annotations should be employed
|
|
for all public names.</p></li>
|
|
<li><p>Use <a class="reference external" href="https://numpydoc.readthedocs.io/en/latest/format.html">numpydoc</a> markups moderately to keep docstrings readable as plain text.</p></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="c">
|
|
<h3>C++<a class="headerlink" href="#c" title="Permalink to this headline">¶</a></h3>
|
|
<p>C++ codes should follow GNU style, which is best documented at <a class="reference external" href="https://wiki.octave.org/C%2B%2B_style_guide">Octave</a>.</p>
|
|
</div>
|
|
<div class="section" id="restructuredtext">
|
|
<h3>reStructuredText<a class="headerlink" href="#restructuredtext" title="Permalink to this headline">¶</a></h3>
|
|
<p>In order for reStructuredText to be rendered correctly, the body of
|
|
constructs beginning with a marker (lists, hyperlink targets, comments, etc.)
|
|
must be aligned relative to the marker. For this reason, it is convenient
|
|
to set your editor indentation level to 3 spaces, since most constructs
|
|
starts with two dots and a space. However, be aware of that bullet items
|
|
require 2-space alignment and other exceptions.</p>
|
|
<p>Limit all lines to a maximum of 79 characters. Similar to comments
|
|
and docstrings, phrases should not be broken in the middle.
|
|
The source code of this guide itself is a good example on how line breaks
|
|
should be handled. Additionally, two spaces should also be used
|
|
after a sentence-ending period in multi-sentence paragraph,
|
|
except after the final sentence.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="copying.html" class="btn btn-neutral float-right" title="Copying" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="design.html" class="btn btn-neutral float-left" title="Design Principles" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
|
|
© Copyright 2019, 2020 Nguyễn Gia Phong et al
|
|
|
|
</p>
|
|
</div>
|
|
|
|
|
|
|
|
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a
|
|
|
|
<a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a>
|
|
|
|
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
|
|
<script type="text/javascript">
|
|
jQuery(function () {
|
|
SphinxRtdTheme.Navigation.enable(true);
|
|
});
|
|
</script>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</body>
|
|
</html> |