Contributing to GWKokab¶

Everyone can contribute to GWKokab, and we value everyone’s contributions. There are several ways to contribute, including:

Answering questions on GWKokab’s discussions page.
Improving or expanding GWKokab’s documentation.
Contributing to GWKokab’s code base.

Ways to contribute¶

We welcome pull requests, in particular for those issues marked with contributions welcome or good first issue.

For other proposals, we ask that you first open a GitHub Issue or Discussion to seek feedback on your planned contribution.

Contributing code using pull requests¶

We do all of our development using git, so basic knowledge is assumed.

Follow these steps to contribute code:

Install uv package manager if you don’t have it already.
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
See details at uv installation guidelines.
Install make if you don’t have it already. On Ubuntu/Debian, you can install it via:
```
sudo apt-get install make
```
Fork the GWKokab repository by clicking the Fork button on the repository page. This creates a copy of the GWKokab repository in your account.

Clone your forked repository,

git clone https://github.com/YOUR_USERNAME/gwkokab
cd gwkokab

Create a new virtual environment using uv with any python>=3.11,
```
uv venv -p 3.12
source .venv/bin/activate
```
Then install the development dependencies:
```
make install --PIP_FLAGS=--upgrade EXTRA=dev,test,docs
```
This allows you to modify the code and immediately test it out.
Add the GWKokab repo as an upstream remote, so you can use it to sync your changes.
```
git remote add upstream https://www.github.com/kokabsc/gwkokab
```
Create a new branch for your changes:
```
git checkout -b name-of-change
```
Make sure your code passes GWKokab’s lint and type checks, by running the following from the top of the repository:
```
pip install prek
prek run --all-files
```
Make sure the tests pass by running the following command from the top of the repository:
```
pytest -n auto tests/
```
If you know the specific test file that covers your changes, you can limit the tests to that; for example:
```
pytest -n auto tests/test_model_transformations.py
```
You can narrow the tests further by using the pytest -k flag to match particular test names:
```
pytest -n auto tests/test_model_transformations.py -k test_bijective_transforms
```
Once you are satisfied with your change, create a commit as follows (how to write a commit message).
```
git add file1.py file2.py ...
git commit -m "Your commit message"
```
Then sync your code with the main repo:
```
git fetch upstream
git rebase upstream/main
```
Finally, push your commit on your development branch and create a remote branch in your fork that you can use to create a pull request from:
```
git push --set-upstream origin name-of-change
```
Create a pull request from the GWKokab repository and send it for review. When preparing your PR consult GitHub Help if you need more information on using pull requests.

Full GitHub test suite¶

Your PR will automatically be run through a full test suite on GitHub CI, which covers a range of Python versions, dependency versions, and configuration options. It’s normal for these tests to turn up failures that you didn’t catch locally; to fix the issues you can push new commits to your branch.