Version Control & Collaboration Guide

This document explains how to use version control for the Resilient Hydro Twin platform. It covers repository structure, branching workflow, contribution guidelines, and best practices for GitHub usage.

0. Repository Overview¶

The project currently uses:

Primary repository: Gitlab: (only accessible internally TU/e)
Collaboration and Backup repo: Github: (accessible with invite)

For the people collaborating on the project outside TU/e, they will only have access to Github repo.

1. Getting Started with Git & Github¶

Install git¶

First step is to install git.
https://git-scm.com/install/windows

After installation, you can check if git is successfully installed by running the following command. In this document, any command that is mentioned can be run in the terminal for MacOS or CMD - command prompt in Windows.

git --version

Create or Access GitHub Account¶

Sign in or create account: https://github.com
Configure username & email in Git:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

By running these commands git will know who is doing the changes, commits etc.

SSH Key Setup (Recommended)¶

There are some alternative ways to access Github. I can recommend accessing by using SSH keys. You can also use Github Desktop. For the SSH key method you need to first generate SSH key:

For detailed description check Github Documentation Link:

ssh-keygen -t ed25519 -C "your.email@example.com"

This command will generate two files id_ed25519 and id_ed25519.pub. The first one is your actual key, dont share it with anyone. The second one is the public part of your key. You need to access this and copy, paste into Github by going GitHub → Settings → SSH and GPG Keys → New SSH key

To test the connection:

ssh -T git@github.com

Cloning the RHT Repository¶

At this point, if you joined the Github Repo of RHT you can clone (copy the files) into your local environment (ie. laptop).

Using SSH:

git clone git@github.com:ISBE-TUe/resilient-hydro-twin.git

After doing this you can go inside the resilient-hydro-twin folder and check the files.

Using HTTPS:

git clone https://github.com/ISBE-TUe/resilient-hydro-twin.git

Now you can access this folder by using any IDE (recommended PyCharm).

2. Branching Model¶

The project follows a feature-branch workflow.

Main rules¶

main branch contains stable production-ready code
All new development happens in feature branches
No direct commits to main
Merge into main only with Pull/Merge Requests

Branch naming conventions¶

Type	Prefix	Example
New feature	`feature/`	`feature/pdok-basemap-selector`
Bug fix	`fix/`	`fix/docker-volume`
Documentation	`docs/`	`docs/api-endpoints`

3. Creating a Feature Branch¶

Steps¶

Ensure main is up to date:

git checkout main
git pull

Create and switch to a new branch:

git checkout -b feature/<short-name>

Commit changes regularly
Push branch to remote:

git push --set-upstream origin feature/<short-name>

4. Merge Request / Pull Request Workflow¶

Steps to merge feature branch into `main`¶

Finish feature work and commit changes
Push to remote
Open Pull Request (GitHub)
Assign reviewers
Resolve comments and pass checks
Reviewer merges into main

Merge rules¶

Always update main before merging

git checkout main
git pull

Merge feature branch:

git merge feature/<name>

5. Best Practices¶

Commit small, frequent changes
Write meaningful commit messages
Push early and often (to avoid conflicts)
Keep feature branches short-lived
Review code before merging