Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

44 add contributing guidelines #71

Merged
merged 5 commits into from
Jun 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 0 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
60 changes: 60 additions & 0 deletions docs/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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
3 changes: 2 additions & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,6 @@
:titlesonly:
:hidden:

modules
whats-new.md
modules
CONTRIBUTING.md
Loading