WSL/SLF GitLab Repository

CONTRIBUTING.rst 9.6 KB
Newer Older
Aschauer's avatar
Aschauer committed
1
2
3
4
============
Contributing
============

Aschauer's avatar
Aschauer committed
5
6
7
Welcome to the ``swe2hs`` contributing guide. This document focuses on getting any 
potential contributor familiarized with the development processes, 
but `other kinds of contributions`_ are also appreciated.
Aschauer's avatar
Aschauer committed
8
9

If you are new to using git_ or have never collaborated in a project previously,
10
11
please have a look at `contribution-guide.org`_. Other resources are
listed in the `guide created by FreeCodeCamp`_.
Aschauer's avatar
Aschauer committed
12

Aschauer's avatar
Aschauer committed
13
14
All users and contributors are expected to be open,
considerate, reasonable, and respectful. 
Aschauer's avatar
Aschauer committed
15
16
17
18
19


Issue Reports
=============

Aschauer's avatar
Aschauer committed
20
21
If you experience bugs or general issues, please have a look
on the `issue tracker`_. If you do not see any relevant issue for your problem 
22
there, please create a new issue report. If you are new and not a member of 
23
WSL/SLF, you first have to `register <https://gitlabext.wsl.ch/users/sign_up>`_ 
24
to the WLS GitLab to create an issue.
Aschauer's avatar
Aschauer committed
25
26
27
28

.. tip::
   Please don't forget to include the closed issues in your search.
   Sometimes a solution was already reported, and the problem is considered
Aschauer's avatar
Aschauer committed
29
   solved.
Aschauer's avatar
Aschauer committed
30
31
32
33
34

New issue reports should include information about your programming environment
(e.g., operating system, Python version) and steps to reproduce the problem.
Please try also to simplify the reproduction steps to a very minimal example
that still illustrates the problem you are facing. By removing other factors,
Aschauer's avatar
Aschauer committed
35
you help to identify the root cause of the issue.
Aschauer's avatar
Aschauer committed
36
37
38
39
40


Documentation Improvements
==========================

Aschauer's avatar
Aschauer committed
41
You can help improve the documentation by making it more readable and coherent, or
Aschauer's avatar
Aschauer committed
42
43
by adding missing information and correcting mistakes.

Aschauer's avatar
Aschauer committed
44
The documentation uses Sphinx_ as its main documentation compiler.
Aschauer's avatar
Aschauer committed
45
46
This means that the docs are kept in the same repository as the project code, and
that any documentation update is done in the same way was a code contribution.
Aschauer's avatar
Aschauer committed
47
Documentation is formatted using reStructuredText_, the examples are Jupyter 
48
Notebooks formatted with MyST-NB_. The API is documented in the docstrings of
Aschauer's avatar
Aschauer committed
49
functions and classes, please use the `numpy docstring style`_.
Aschauer's avatar
Aschauer committed
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68

When working on documentation changes in your local machine, you can
compile them using |tox|_::

    tox -e docs

and use Python's built-in web server for a preview in your web browser
(``http://localhost:8000``)::

    python3 -m http.server --directory 'docs/_build/html'


Code Contributions
==================


Submit an issue
---------------

Aschauer's avatar
Aschauer committed
69
Before you work on any non-trivial code contribution it is best to first create
Aschauer's avatar
Aschauer committed
70
71
72
73
74
75
a report in the `issue tracker`_ to start a discussion on the subject.
This often provides additional considerations and avoids unnecessary work.

Create an environment
---------------------

Aschauer's avatar
Aschauer committed
76
Before starting to code, create an isolated `virtual
Aschauer's avatar
Aschauer committed
77
78
79
80
81
82
environment`_ to avoid any problems with your installed Python packages.
This can easily be done via either |virtualenv|_::

    virtualenv <PATH TO VENV>
    source <PATH TO VENV>/bin/activate

Aschauer's avatar
Aschauer committed
83
or if you use Miniconda_ or Anaconda::
Aschauer's avatar
Aschauer committed
84
85
86
87
88
89
90
91
92
93

    conda create -n swe2hs python=3 six virtualenv pytest pytest-cov
    conda activate swe2hs

Clone the repository
--------------------

#. Create an user account on |the repository service| if you do not already have one.
#. Fork the project repository_: click on the *Fork* button near the top of the
   page. This creates a copy of the code under your account on |the repository service|.
Aschauer's avatar
Aschauer committed
94
#. Clone this copy to your local disk with::
Aschauer's avatar
Aschauer committed
95

Aschauer's avatar
Aschauer committed
96
    git clone git@gitlabext.wsl.ch:<YOUR_LOGIN>/swe2hs.git
Aschauer's avatar
Aschauer committed
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
    cd swe2hs

#. You should run::

    pip install -U pip setuptools -e .

   to be able to import the package under development in the Python REPL.


Implement your changes
----------------------

#. Create a branch to hold your changes::

    git checkout -b my-feature

Aschauer's avatar
Aschauer committed
113
   and start making changes. Never work on the main branch.
Aschauer's avatar
Aschauer committed
114

Aschauer's avatar
Aschauer committed
115
#. Start your work on this branch. Please add docstrings_ to new
Aschauer's avatar
Aschauer committed
116
117
   functions, modules and classes, especially if they are part of public APIs.

Aschauer's avatar
Aschauer committed
118
119
#. Add you changes to the changelog and add yourself to the list of contributors
   in ``AUTHORS.rst``.
Aschauer's avatar
Aschauer committed
120

Aschauer's avatar
Aschauer committed
121
#. When you are done editing, do::
Aschauer's avatar
Aschauer committed
122
123
124
125

    git add <MODIFIED FILES>
    git commit

126
127
   to record your changes in git_. Try to write `descriptive commit message`_ to make 
   clear what changes you made with the commit.
Aschauer's avatar
Aschauer committed
128

129
   .. note:: Don't forget to add unit tests and documentation in case your
Aschauer's avatar
Aschauer committed
130
131
      contribution adds an additional feature and is not just a bugfix.

Aschauer's avatar
Aschauer committed
132
#. Please check that your changes do not break any unit tests with::
Aschauer's avatar
Aschauer committed
133
134
135

    tox

Aschauer's avatar
Aschauer committed
136
   (after having installed |tox|_ with ``pip install tox``).
Aschauer's avatar
Aschauer committed
137
138
139
140
141
142
143
144
145
146
147
148

   You can also use |tox|_ to run several other pre-configured tasks in the
   repository. Try ``tox -av`` to see a list of the available checks.

Submit your contribution
------------------------

#. If everything works fine, push your local branch to |the repository service| with::

    git push -u origin my-feature

#. Go to the web page of your fork and click |contribute button|
Aschauer's avatar
Aschauer committed
149
   to send your changes for review. The tests will then autmatically run in the CI
Aschauer's avatar
Aschauer committed
150
   of GitLab and you can see if all tests also pass on the CI. 
Aschauer's avatar
Aschauer committed
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


Troubleshooting
---------------

The following tips can be used when facing problems to build or test the
package:

#. Make sure to fetch all the tags from the upstream repository_.
   The command ``git describe --abbrev=0 --tags`` should return the version you
   are expecting. If you are trying to run CI scripts in a fork repository,
   make sure to push all the tags.
   You can also try to remove all the egg files or the complete egg folder, i.e.,
   ``.eggs``, as well as the ``*.egg-info`` folders in the ``src`` folder or
   potentially in the root of your project.

#. Sometimes |tox|_ misses out when new dependencies are added, especially to
   ``setup.cfg`` and ``docs/requirements.txt``. If you find any problems with
   missing dependencies when running a command with |tox|_, try to recreate the
   ``tox`` environment using the ``-r`` flag. For example, instead of::

    tox -e docs

   Try running::

    tox -r -e docs

#. Make sure to have a reliable |tox|_ installation that uses the correct
   Python version (e.g., 3.7+). When in doubt you can run::

    tox --version
    # OR
    which tox

   If you have trouble and are seeing weird errors upon running |tox|_, you can
   also try to create a dedicated `virtual environment`_ with a |tox|_ binary
   freshly installed. For example::

    virtualenv .venv
    source .venv/bin/activate
    .venv/bin/pip install tox
    .venv/bin/tox -e all

Aschauer's avatar
Aschauer committed
194
#. Pytest can drop you in an interactive session in the case an error occurs.
Aschauer's avatar
Aschauer committed
195
196
197
198
199
200
201
202
203
204
205
206
207
   In order to do that you need to pass a ``--pdb`` option (for example by
   running ``tox -- -k <NAME OF THE FALLING TEST> --pdb``).
   You can also setup breakpoints manually instead of using the ``--pdb`` option.


Maintainer tasks
================

Releases
--------


If you are part of the group of maintainers and have correct user permissions
Aschauer's avatar
Aschauer committed
208
209
210
211
on GitLab to push protected tags starting with ``v*``, the following steps can be 
used to release a new version for ``swe2hs``:

#. make sure all changes are listed in the changelog
212
213
#. Run the following command to check if the package gets builded correctly::

214
    tox -e clean,build
215

216
#. tag your commit with the version name. The version tag needs to be of the 
217
218
219
220
   format ``v.X.X.X``::

    git tag vX.X.X

221
222
#. push the tag to GitLab, if the tag has the correct format, the Gitlab CI will 
   automatically build the package and upload it to PyPI. 
Aschauer's avatar
Aschauer committed
223
224

.. |the repository service| replace:: GitLab
Aschauer's avatar
Aschauer committed
225
226
.. |contribute button| replace:: "Create pull request"

Aschauer's avatar
Aschauer committed
227
228
229
.. _repository: https://code.wsl.ch/aschauer/swe2hs
.. _issue tracker: https://code.wsl.ch/aschauer/swe2hs/-/issues

Aschauer's avatar
Aschauer committed
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249


.. |virtualenv| replace:: ``virtualenv``
.. |pre-commit| replace:: ``pre-commit``
.. |tox| replace:: ``tox``


.. _black: https://pypi.org/project/black/
.. _CommonMark: https://commonmark.org/
.. _contribution-guide.org: https://www.contribution-guide.org/
.. _creating a PR: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
.. _descriptive commit message: https://chris.beams.io/posts/git-commit
.. _docstrings: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
.. _first-contributions tutorial: https://github.com/firstcontributions/first-contributions
.. _flake8: https://flake8.pycqa.org/en/stable/
.. _git: https://git-scm.com
.. _GitHub's fork and pull request workflow: https://guides.github.com/activities/forking/
.. _guide created by FreeCodeCamp: https://github.com/FreeCodeCamp/how-to-contribute-to-open-source
.. _Miniconda: https://docs.conda.io/en/latest/miniconda.html
.. _MyST: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html
Aschauer's avatar
Aschauer committed
250
.. _MyST-NB: https://myst-nb.readthedocs.io/en/latest/
Aschauer's avatar
Aschauer committed
251
.. _numpy docstring style: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
Aschauer's avatar
Aschauer committed
252
253
254
255
256
257
258
259
260
261
262
263
264
.. _other kinds of contributions: https://opensource.guide/how-to-contribute
.. _pre-commit: https://pre-commit.com/
.. _PyPI: https://pypi.org/
.. _PyScaffold's contributor's guide: https://pyscaffold.org/en/stable/contributing.html
.. _Python Software Foundation's Code of Conduct: https://www.python.org/psf/conduct/
.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _tox: https://tox.wiki/en/stable/
.. _virtual environment: https://realpython.com/python-virtual-environments-a-primer/
.. _virtualenv: https://virtualenv.pypa.io/en/stable/

.. _GitHub web interface: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files
.. _GitHub's code editor: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files