~cnx/palace

ref: 9a1dbf5d9469cf175c48cb4da558f3c9b8e0fdc5 palace/docs/source/contributing.rst -rw-r--r-- 8.7 KiB
9a1dbf5dNguyễn Gia Phong Move documentation to docs/ 1 year, 8 months ago
                                                                                
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
Getting Involved
================

.. note:: The development of palace is carried out on GitHub_.
   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.

First of all, thank you for using and contributing to palace!  We welcome
all forms of contribution, and `the mo the merier`_.  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.

Reporting a Bug
---------------

Before filing a bug report, please make sure that the bug has not been
already reported by searching our GitHub Issues_ tracker.

To facilitate the debugging process, a bug report should at least contain
the following information:

#. The platform, the CPython version and the compiler used to build it.
   These can be obtained from :py:func:`platform.platform`,
   :py:func:`platform.python_version` and :py:func:`platform.python_compiler`,
   respectively.
#. The version of palace and how you installed it.
   The earlier is usually provided by ``pip show palace``.
#. Detailed instructions on how to reproduce the bug,
   for example a short Python script would be appreciated.

Requesting a Feature
--------------------

Prior to filing a feature request, please make sure that the feature
has not been already reported by searching our GitHub Issues_ tracker.

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.

Submitting a Patch
------------------

We accept all kinds of patches, from documentation and CI/CD setup
to bug fixes, feature implementations and tests.  Except for documentation
located in the ``gh-pages`` branch, others should be filed against
the development branch ``master``.  These are hosted on GitHub and
one may create a local repository by running::

   git clone https://github.com/McSinyx/palace

While the patch can be submitted via email, it is preferable to file
a pull request on GitHub 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 `LGPLv3+`_.  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::

   Copyright (C) 2038  Foo Bar

Using GitHub
^^^^^^^^^^^^

#. Create a fork_ of our repository on GitHub.
#. Checkout the source code and (optionally) add the ``upstream`` remote::

      git clone https://github.com/YOUR_GITHUB_USERNAME/palace
      cd palace
      git remote add upstream https://github.com/McSinyx/palace

#. Start working on your patch and make sure your code complies with
   the `Style Guidelines`_ and passes the test suit run by tox_.
#. 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
   ``CYTHON_TRACE=1 pip install .`` then run pytest_ directly to avoid
   having to build the extension module multiple times.
#. Update the copyright notices of the files you modified.
   Palace is collectively licensed under `LGPLv3+`_,
   and to protect the freedom of the users,
   copyright holders need to be properly documented.
#. Add_, commit_ with `a great message`_ then push_ the result.
#. Finally, `create a pull request`_.  We will then review and merge it.

It is recommended to create a new branch in your fork
(``git checkout -c what-you-are-working-on``) instead of working directly
on ``master``.  This way one can still sync per fork with our ``master`` branch
and ``git pull --rebase upstream master`` to avoid integration issues.

Via Email
^^^^^^^^^

#. Checkout the source code::

      git clone https://github.com/McSinyx/palace
      cd palace

#. Work on your patch with tests and copyright notice included
   as described above.
#. `git-format-patch`_ and send it to one of the maintainers
   (our emails addresses are available under ``git log``).
   We will then review and merge it.

In any case, thank you very much for your contributions!

Making a Release
----------------

While this is meant for developers doing a palace release, contributors wishing
to improve the CI/CD may find it helpful.

#. Under the local repository, checkout the ``master`` branch
   and sync with the one on GitHub using ``git pull``.
#. Bump the version in ``setup.cfg`` and push to GitHub.
#. Create a source distribution by running ``setup.py sdist``.
   The distribution generated by this command is now referred to as ``sdist``.
#. Using twine_, upload the ``sdist`` to PyPI via ``twine upload $sdist``.
#. On GitHub, tag a new release with the ``sdist`` 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.
#. 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.
#. Under the local repository, checkout the ``gh-pages`` branch.
   Often, is it necessary to update the credits under the :doc:`copying`
   section and review if the :doc:`reference/index` section needs any change
   before running ``make html`` to rebuild to documentation.
#. View the documentation locally then push it to GitHub.

Style Guidelines
----------------

Python and Cython
^^^^^^^^^^^^^^^^^

Generally, palace follows :pep:`8` and :pep:`257`,
with the following preferences and exceptions:

* Hanging indentation is *always* preferred,
  where continuation lines are indented by 4 spaces.
* Comments and one-line docstrings are limited to column 79
  instead of 72 like for multi-line docstrings.
* Cython extern declarations need not follow the 79-character limit.
* Break long lines before a binary operator.
* Use form feeds sparingly to break long modules
  into pages of relating functions and classes.
* Prefer single-quoted strings over double-quoted strings,
  unless the string contains single quote characters.
* Avoid trailing commas at all costs.
* Line breaks within comments and docstrings should not cut a phrase in half.
* Everything deserves a docstring.  Palace follows numpydoc_ 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.
* Use numpydoc_ markups moderately to keep docstrings readable as plain text.

C++
^^^

C++ codes should follow GNU style, which is best documented at Octave_.

reStructuredText
^^^^^^^^^^^^^^^^

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.

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.

.. _GitHub: https://github.com/McSinyx/palace
.. _the mo the merier:
   https://www.phrases.org.uk/meanings/the-more-the-merrier.html
.. _Issues: https://github.com/McSinyx/palace/issues
.. _LGPLv3+: https://www.gnu.org/licenses/lgpl-3.0.en.html
.. _fork: https://github.com/McSinyx/palace/fork
.. _tox: https://tox.readthedocs.io/en/latest/
.. _pytest: https://docs.pytest.org/en/latest/
.. _Add: https://git-scm.com/docs/git-add
.. _commit: https://git-scm.com/docs/git-commit
.. _a great message: https://chris.beams.io/posts/git-commit/#seven-rules
.. _push: https://git-scm.com/docs/git-push
.. _create a pull request:
   https://help.github.com/articles/creating-a-pull-request
.. _git-format-patch: https://git-scm.com/docs/git-format-patch
.. _twine: https://twine.readthedocs.io/en/latest/
.. _numpydoc: https://numpydoc.readthedocs.io/en/latest/format.html
.. _Octave: https://wiki.octave.org/C%2B%2B_style_guide