<h1>Getting Involved<aclass="headerlink"href="#getting-involved"title="Permalink to this headline">¶</a></h1>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>The development of palace is carried out on <aclass="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 <aclass="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,
<li><p>The version of palace and how you installed it.
The earlier is usually provided by <codeclass="docutils literal notranslate"><spanclass="pre">pip</span><spanclass="pre">show</span><spanclass="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>
<divclass="section"id="requesting-a-feature">
<h2>Requesting a Feature<aclass="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 <aclass="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>
<divclass="section"id="submitting-a-patch">
<h2>Submitting a Patch<aclass="headerlink"href="#submitting-a-patch"title="Permalink to this headline">¶</a></h2>
a pull request on GitHub against the <codeclass="docutils literal notranslate"><spanclass="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 <aclass="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>
<li><p>Start working on your patch and make sure your code complies with
the <aclass="reference internal"href="#style-guidelines">Style Guidelines</a> and passes the test suit run by <aclass="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
<codeclass="docutils literal notranslate"><spanclass="pre">CYTHON_TRACE=1</span><spanclass="pre">pip</span><spanclass="pre">install</span><spanclass="pre">.</span></code> then run <aclass="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 <aclass="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><aclass="reference external"href="https://git-scm.com/docs/git-add">Add</a>, <aclass="reference external"href="https://git-scm.com/docs/git-commit">commit</a> with <aclass="reference external"href="https://chris.beams.io/posts/git-commit/#seven-rules">a great message</a> then <aclass="reference external"href="https://git-scm.com/docs/git-push">push</a> the result.</p></li>
<li><p>Finally, <aclass="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>
<p>It is recommended to create a new branch in your fork
(<codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">checkout</span><spanclass="pre">-c</span><spanclass="pre">what-you-are-working-on</span></code>) instead of working directly
on <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code>. This way one can still sync per fork with our <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code> branch
and <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span><spanclass="pre">--rebase</span><spanclass="pre">upstream</span><spanclass="pre">master</span></code> to avoid integration issues.</p>
<h2>Making a Release<aclass="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>
<olclass="arabic simple">
<li><p>Under the local repository, checkout the <codeclass="docutils literal notranslate"><spanclass="pre">master</span></code> branch
and sync with the one on GitHub using <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">pull</span></code>.</p></li>
<li><p>Bump the version in <codeclass="docutils literal notranslate"><spanclass="pre">setup.cfg</span></code> and push to GitHub.</p></li>
<li><p>Create a source distribution by running <codeclass="docutils literal notranslate"><spanclass="pre">setup.py</span><spanclass="pre">sdist</span></code>.
The distribution generated by this command is now referred to as <codeclass="docutils literal notranslate"><spanclass="pre">sdist</span></code>.</p></li>
<li><p>Using <aclass="reference external"href="https://twine.readthedocs.io/en/latest/">twine</a>, upload the <codeclass="docutils literal notranslate"><spanclass="pre">sdist</span></code> to PyPI via <codeclass="docutils literal notranslate"><spanclass="pre">twine</span><spanclass="pre">upload</span><spanclass="pre">$sdist</span></code>.</p></li>
<li><p>On GitHub, tag a new release with the <codeclass="docutils literal notranslate"><spanclass="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>
with the following preferences and exceptions:</p>
<ulclass="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 <aclass="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 <aclass="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>
<divclass="section"id="c">
<h3>C++<aclass="headerlink"href="#c"title="Permalink to this headline">¶</a></h3>
<p>C++ codes should follow GNU style, which is best documented at <aclass="reference external"href="https://wiki.octave.org/C%2B%2B_style_guide">Octave</a>.</p>
</div>
<divclass="section"id="restructuredtext">
<h3>reStructuredText<aclass="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.)