-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Loading status checks…
Create CONTRIBUTING.rst
1 parent
bd2e631
commit 4558e73
Showing
1 changed file
with
161 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,161 @@ | ||
===================== | ||
Contribution Guide | ||
===================== | ||
|
||
Contributions are highly welcomed and appreciated. Every little help counts, | ||
so do not hesitate! You can make a high impact on ``pysonde`` just by using | ||
it and reporting `issues <https://github.com/observingClouds/pysonde/issues>`__. | ||
|
||
The following sections cover some general guidelines | ||
regarding development in ``pysonde`` for maintainers and contributors. | ||
|
||
|
||
Nothing here is set in stone and can't be changed. | ||
Feel free to suggest improvements or changes in the workflow. | ||
|
||
|
||
.. _submitfeedback: | ||
|
||
Feature requests and feedback | ||
----------------------------- | ||
|
||
We are eager to hear about your requests for new features and any suggestions | ||
about the API, infrastructure, and so on. Feel free to submit these as | ||
`issues <https://github.com/observingClouds/pysonde/issues/new>`__ with the label | ||
``"enhancement"``. | ||
|
||
Please make sure to explain in detail how the feature should work and keep the | ||
scope as narrow as possible. This will make it easier to implement in small | ||
PRs. | ||
|
||
|
||
.. _reportbugs: | ||
|
||
Report bugs | ||
----------- | ||
|
||
Report bugs for ``pysonde`` in the | ||
`issue tracker <https://github.com/observingClouds/pysonde/issues>`_ with the | ||
label "bug". | ||
|
||
If you are reporting a bug, please include: | ||
|
||
* Any details about your local setup that might be helpful in troubleshooting, | ||
specifically the Python interpreter version, installed libraries, and | ||
``pysonde`` version. | ||
* Detailed steps `how to reproduce the bug <https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports>__` | ||
|
||
If you can write a demonstration test that currently fails but should pass, | ||
that is a very useful commit to make as well, even if you cannot fix the bug | ||
itself. | ||
|
||
|
||
.. _fixbugs: | ||
|
||
Bug Fix | ||
------- | ||
|
||
Look through the | ||
`GitHub issues for bugs <https://github.com/observingClouds/pysonde/labels/bug>`_. | ||
|
||
Talk to developers to find out how you can fix specific bugs. | ||
|
||
|
||
|
||
Preparing Pull Requests | ||
----------------------- | ||
|
||
#. Fork the `pysonde GitHub repository <https://github.com/observingClouds/pysonde>`__. | ||
It's fine to use ``pysonde`` as your fork repository name because it will | ||
live under your user. | ||
|
||
#. Clone your fork locally using `git <https://git-scm.com/>`_, connect your | ||
repository to the upstream (main project), and create a branch:: | ||
|
||
$ git clone git@github.com:YOUR_GITHUB_USERNAME/pysonde.git | ||
$ cd pysonde | ||
$ git remote add upstream git@github.com:observingClouds/pysonde.git | ||
|
||
# now, to fix a bug or add feature create your own branch off "main": | ||
|
||
$ git checkout -b your-bugfix-feature-branch-name main | ||
|
||
If you need some help with Git, follow this quick start | ||
`guide <https://git.wiki.kernel.org/index.php/QuickStart>`_. | ||
|
||
#. Make an editable install of ``pysonde`` by running:: | ||
|
||
$ pip install -e . | ||
|
||
The PDM package manager should now also have installed the pre-commit hooks | ||
that ensures that we all adhere to the same coding standard. | ||
``pre-commit`` automatically beautifies the code, makes it more | ||
maintainable and catches syntax errors. | ||
|
||
In case it has not been installed automatically, the next step ensures it. | ||
|
||
#. Install `pre-commit <https://pre-commit.com>`_ and its hook on the | ||
``pysonde`` repo:: | ||
|
||
$ pip install pre-commit | ||
$ pre-commit install | ||
|
||
Afterwards ``pre-commit`` will run whenever you commit and can also be | ||
run independently by ``pre-commit run --all``. | ||
|
||
You can now edit your local working copy and run/add tests as necessary. | ||
Please try to follow | ||
`PEP-8 <https://www.python.org/dev/peps/pep-0008/#naming-conventions>`_ for | ||
naming. When committing, ``pre-commit`` will modify the files as | ||
needed, or will generally be quite clear about what you need to do to pass | ||
the commit test. | ||
|
||
``pre-commit`` also runs:: | ||
|
||
* `ruff <https://docs.astral.sh/ruff/>`_ code formatter. | ||
* `black <https://black.readthedocs.io/en/stable/>`_ code formatting | ||
.. | ||
|
||
#. Break your edits up into reasonably sized commits:: | ||
|
||
$ git commit -m "<commit message>" | ||
$ git push -u | ||
|
||
#. Run all tests | ||
|
||
Once commits are pushed to ``origin``, GitHub Actions runs continuous | ||
integration of all tests with `pytest <https://docs.pytest.org/en/7.1.x/getting-started.html#get-started>`__ on all new commits. | ||
However, you can already run tests locally:: | ||
|
||
$ pytest # all | ||
$ pytest tests/test_mwx_output.py::test_mwx_conversion_to_level1 # specific tests | ||
|
||
Please stick to | ||
`xarray <http://xarray.pydata.org/en/stable/contributing.html>`_'s testing | ||
recommendations. | ||
|
||
#. Create a new changelog entry in `CHANGELOG.rst <CHANGELOG.rst>`_: | ||
|
||
The entry should be entered as: | ||
|
||
``<description>`` (``:pr:`#<pull request number>```) ```<author's names>`_`` | ||
|
||
where ``<description>`` is the description of the PR related to the change | ||
and ``<pull request number>`` is the pull request number and | ||
``<author's names>`` are your first and last names. | ||
|
||
Add yourself to list of authors at the end of `.zenodo.json <.zenodo.json>`_ file if | ||
not there yet, in alphabetical order. | ||
|
||
#. Finally, submit a `Pull Request <https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_ through the GitHub website using this data:: | ||
|
||
head-fork: YOUR_GITHUB_USERNAME/pysonde | ||
compare: your-branch-name | ||
|
||
base-fork: observingClouds/pysonde | ||
base: main | ||
|
||
Note that you can create the ``Pull Request`` while you're working on this. | ||
The PR will update as you add more commits. ``pysonde`` developers and | ||
contributors can then review your code and offer suggestions. |