From 0e319decd5f166c7d44fe22982c87ff7ce12cf17 Mon Sep 17 00:00:00 2001 From: veenstrajelmer Date: Fri, 14 Jun 2024 09:56:38 +0200 Subject: [PATCH 1/5] added contributing.md --- docs/CONTRIBUTING.md | 56 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 3 ++- 2 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 docs/CONTRIBUTING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..1e2e269 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# 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/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 Python 3.9 (or higher) from [anaconda.com](https://www.anaconda.com/distribution/#download-section) (miniconda should also be sufficient, but this is not yet tested). Install it with the recommended settings. +- open anaconda prompt and navigate to the local checkout folder of the repository +- ``conda create --name kw_env python=3.8.13 git spyder -y`` (``git`` and ``spyder``, python version should be the one at HMC) +- ``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`` + +## Contributing + +- 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 +- 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 +- request a review on the pull request +- after review, squash+merge the branch into main + +## 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 diff --git a/docs/index.rst b/docs/index.rst index 2298d48..7446710 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,5 +4,6 @@ :titlesonly: :hidden: - modules whats-new.md + modules + CONTRIBUTING.md From b262ea8d36d39f1981fc443fdfd4021b76034d17 Mon Sep 17 00:00:00 2001 From: veenstrajelmer Date: Fri, 14 Jun 2024 10:02:03 +0200 Subject: [PATCH 2/5] merged contributing from readme to contributing.md --- README.md | 10 ---------- docs/CONTRIBUTING.md | 6 +++--- 2 files changed, 3 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index c90b1e0..45a23f3 100644 --- a/README.md +++ b/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 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1e2e269..8c5ec2b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -5,16 +5,16 @@ - 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/kenmerkendewaarden (creates a local clone of the repository in a folder called kenmerkendewaarden) +- ``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 Python 3.9 (or higher) from [anaconda.com](https://www.anaconda.com/distribution/#download-section) (miniconda should also be sufficient, but this is not yet tested). Install it with the recommended settings. +- 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.8.13 git spyder -y`` (``git`` and ``spyder``, python version should be the one at HMC) +- ``conda create --name kw_env python=3.11 git spyder -y`` (``git`` and ``spyder``) - ``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`` From f3cf778379f7fe5f0ae65da2943320529ce8adda Mon Sep 17 00:00:00 2001 From: veenstrajelmer Date: Fri, 14 Jun 2024 10:09:22 +0200 Subject: [PATCH 3/5] updated contributing guidelines with issue contents --- docs/CONTRIBUTING.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8c5ec2b..58a36b4 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -23,7 +23,7 @@ ## Contributing - 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 +- 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) @@ -31,8 +31,12 @@ - ``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 +- after review, squash+merge the branch into main (with cleaned up commit messages) ## Running the testbank From 941fdd5420d9e45f9e4b65608ae87effd1119999 Mon Sep 17 00:00:00 2001 From: veenstrajelmer Date: Fri, 14 Jun 2024 10:11:46 +0200 Subject: [PATCH 4/5] updated contributing guidelines with issue contents --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 58a36b4..988bdfb 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -14,7 +14,7 @@ - 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``) +- ``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`` From ab82060689dee5223d33fe03f406fd0196f8bf89 Mon Sep 17 00:00:00 2001 From: veenstrajelmer Date: Fri, 14 Jun 2024 10:12:50 +0200 Subject: [PATCH 5/5] updated contributing guidelines with issue contents --- docs/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 988bdfb..433b760 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -20,7 +20,7 @@ - ``conda deactivate`` - to remove the environment when necessary: ``conda remove -n kw_env --all`` -## Contributing +## 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.