44 add contributing guidelines (#71)

* added contributing.md

* merged contributing from readme to contributing.md

* updated contributing guidelines with issue contents

README.md

@@ -13,13 +13,3 @@ De metodieken in deze repository hebben nog geen definitieve status en zijn daar
 - `conda create --name kw_env python=3.11 git -y`
 - `conda activate kw_env`
 - `pip install git+https://github.com/Deltares-research/kenmerkendewaarden`
-
-## contributing
-- open git bash window
-- `git clone https://github.com/deltares-research/kenmerkendewaarden`
-- `cd kenmerkendewaarden`
-- open anaconda prompt
-- `conda create --name kw_env python=3.11 git spyder -c conda-forge -y`
-- `conda activate kw_env`
-- `pip install -e .[dev,examples]`
-- more contributing guidelines available on dfm_tools repos: https://deltares.github.io/dfm_tools/CONTRIBUTING.html

docs/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing
+
+## Checkout github repository
+
+- this is just a suggestion, feel free to work with VScode or any other git-compatible workflow
+- download git from [git-scm.com](https://git-scm.com/download/win), install with default settings
+- open git bash window where you want to clone the github repository (e.g. ``C:\DATA\``)
+- ``git clone https://github.com/deltares-research/kenmerkendewaarden`` (creates a local clone of the repository in a folder called kenmerkendewaarden)
+- ``cd kenmerkendewaarden``
+- optional: ``git config --global user.email [emailaddress]``
+- optional: ``git config --global user.name [username]``
+
+## Setup local developer environment
+
+- download and install Anaconda 64 bit from [anaconda.com](https://www.anaconda.com/download/success)
+- open anaconda prompt and navigate to the local checkout folder of the repository
+- ``conda create --name kw_env python=3.11 git spyder -y`` (``git`` and ``spyder`` are optional)
+- ``conda activate kw_env``
+- ``python -m pip install -e .[dev,docs,examples]`` (pip developer mode, any updates to the local folder are immediately available in your python. It also installs all requirements via pip, square brackets are to install optional dependency groups)
+- ``conda deactivate``
+- to remove the environment when necessary: ``conda remove -n kw_env --all``
+
+## Add your contributions
+
+- open an existing issue or create a new issue at https://github.com/Deltares/kenmerkendewaarden/issues
+- create a branch via ``Development`` on the right. This branch is now linked to the issue and the issue will be closed once the branch is merged with main again via a PR.
+- open git bash window in the local checkout folder of the repository
+- ``git fetch origin`` followed by ``git checkout [branchname]``
+- make your local changes to the code (including docstrings and unittests for functions), after each subtask do ``git commit -am 'description of what you did'`` (``-am`` adds all changed files to the commit)
+- check if all edits were committed with ``git status``, if there are new files created also do ``git add [path-to-file]`` and commit again
+- ``git push`` to push your committed changes your branch on github
+- open a pull request at the branch on github, there you can see what you just pushed and the automated checks will show up (testbank and code quality analysis).
+- optionally make additional local changes (+commit+push) untill you are done with the issue and the automated checks have passed
+- update/add the docstring if you work on public functions, it will end up in the html documentation
+- add tests to make sure your code does what you expect, this is automatically tested on github for several python/package versions.
+- check if there are no conflics, this can often be avoided by working in not too many files at the same time, so by making issues+PRs of each significant subtask.
+- update ``docs/whats-new.md`` if there are any changes that are relevant to users (added features or bug fixes)
+- request a review on the pull request
+- after review, squash+merge the branch into main (with cleaned up commit messages)
+
+## Running the testbank
+
+- open anaconda prompt and navigate to the local checkout folder of the repository
+- ``conda activate kw_env``
+- ``pytest`` (runs all tests)
+- the pytest testbank also runs automatically on Github for every PR (for different python versions and package versions)
+
+## Generate html documentation
+- open anaconda prompt and navigate to the local checkout folder of the repository
+- ``conda activate kw_env``
+- ``sphinx-build docs docs/_build``
+- the documentation is also automatically updated upon every push/merge to the main branch
+
+## Increase the version number
+
+- commit all changes via git
+- open anaconda prompt and navigate to the local checkout folder of the repository
+- ``conda activate kw_env``
+- ``bumpversion major`` or ``bumpversion minor`` or ``bumpversion patch``
+- the version number of all relevant files will be updated, as stated in setup.cfg

docs/index.rst

@@ -4,5 +4,6 @@
    :titlesonly:
    :hidden:
 
-   modules
    whats-new.md
+   modules
+   CONTRIBUTING.md