From 4558e73b183731119f7ffffd8049926d32c61b66 Mon Sep 17 00:00:00 2001 From: Hauke Schulz <43613877+observingClouds@users.noreply.github.com> Date: Tue, 17 Sep 2024 17:35:01 +0200 Subject: [PATCH] Create CONTRIBUTING.rst --- CONTRIBUTING.rst | 161 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 0000000..e657e5a --- /dev/null +++ b/CONTRIBUTING.rst @@ -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 `__. + +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 `__ 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 `_ 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 __` + +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 `_. + +Talk to developers to find out how you can fix specific bugs. + + + +Preparing Pull Requests +----------------------- + +#. Fork the `pysonde GitHub repository `__. + It's fine to use ``pysonde`` as your fork repository name because it will + live under your user. + +#. Clone your fork locally using `git `_, 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 `_. + +#. 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 `_ 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 `_ 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 `_ code formatter. + * `black `_ code formatting + .. + + +#. Break your edits up into reasonably sized commits:: + + $ git commit -m "" + $ git push -u + +#. Run all tests + + Once commits are pushed to ``origin``, GitHub Actions runs continuous + integration of all tests with `pytest `__ 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 `_'s testing + recommendations. + +#. Create a new changelog entry in `CHANGELOG.rst `_: + + The entry should be entered as: + + ```` (``:pr:`#```) ````_`` + + where ```` is the description of the PR related to the change + and ```` is the pull request number and + ```` 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 `_ 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.