Getting Started¶

This guide walks you through everything you need — from creating a GitHub account to running your first test — so you can start contributing to canVODpy even if you have never used Git, GitHub, or Python tooling before.

1. Create a GitHub account¶

GitHub is a website that hosts code and lets teams collaborate on software projects. If you don't already have an account, sign up at github.com/signup.

2. Install Homebrew (macOS only)¶

Homebrew is the standard package manager for macOS — it lets you install developer tools with a single command. Open Terminal (press Cmd+Space, type "Terminal", press Enter) and run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the on-screen instructions. When it finishes, it will tell you to run two commands to add Homebrew to your PATH — copy and run them. Then verify:

brew --version

3. Install Git¶

Git is the version-control system that tracks changes in the codebase. Install it for your operating system:

brew install git

sudo apt update && sudo apt install git

sudo dnf install git

Verify the installation:

git --version

You should see something like git version 2.x.x.

4. Set up an SSH key for GitHub¶

SSH keys let you securely connect to GitHub without typing your password every time.

Generate a key¶

ssh-keygen -t ed25519 -C "your_email@example.com"

ssh-keygen -t ed25519 -C "your_email@example.com"

Add the key to the SSH agent¶

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Copy the public key¶

pbcopy < ~/.ssh/id_ed25519.pub

cat ~/.ssh/id_ed25519.pub

clip < ~/.ssh/id_ed25519.pub

Add the key to GitHub¶

1. Go to github.com/settings/keys.
2. Click New SSH key.
3. Give it a title (e.g. "My Laptop"), paste the key, and click Add SSH key.

Test the connection¶

ssh -T git@github.com

You should see: Hi <username>! You've successfully authenticated...

5. Configure your Git identity¶

Tell Git who you are (this information appears in your commits):

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

Use the same email you registered on GitHub.

6. Install development tools¶

canVODpy uses two command-line tools to manage the project:

• uv — a fast Python package manager that handles dependencies and virtual environments.
• just — a command runner (like a simplified Makefile) that provides shortcuts for common tasks.

Install uv¶

brew install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install just¶

brew install just

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

export PATH="$HOME/.local/bin:$PATH"

sudo apt install just

winget install Casey.Just

Verify both tools¶

uv --version
just --version

7. Fork and clone the repository¶

A fork is your own copy of the project on GitHub. You make changes in your fork and then propose them back to the original project via a "pull request."

Fork on GitHub¶

1. Go to github.com/nfb2021/canvodpy.
2. Click the Fork button in the top-right corner.
3. GitHub will create a copy at github.com/YOUR_USERNAME/canvodpy.

Clone your fork¶

git clone git@github.com:YOUR_USERNAME/canvodpy.git
cd canvodpy

Replace YOUR_USERNAME with your actual GitHub username.

Add the upstream remote¶

This lets you pull in updates from the original repository later:

git remote add upstream git@github.com:nfb2021/canvodpy.git

Verify your remotes:

git remote -v

You should see origin (your fork) and upstream (the original).

8. Initialize submodules¶

The repository uses two Git submodules that contain test data and demo data. Initialize them after cloning:

git submodule update --init --recursive

This pulls:

• packages/canvod-readers/tests/test_data — validation test data (falsified/corrupted RINEX files for testing)
• demo — clean real-world data for demos and documentation

If you skip this step, tests that require these datasets will be automatically skipped.

9. Set up the development environment¶

From inside the canvodpy directory, run:

# Verify required tools are available
just check-dev-tools

# Install all Python dependencies into a virtual environment
uv sync

# Install pre-commit hooks (automatic code checks before each commit)
just hooks

10. Configure the project¶

canVODpy uses three YAML configuration files in the config/ directory:

Each file has a corresponding .example template. To initialize them:

just config-init

After editing, validate your configuration:

just config-validate

To view the resolved configuration:

just config-show

11. Verify everything works¶

Run the test suite:

just test

Run code-quality checks (linting, formatting, type checking):

just check

If both commands complete without errors, your environment is ready.

12. Keeping your fork up to date¶

The upstream repository (nfb2021/canvodpy) receives regular updates. To incorporate these into your fork, you need to fetch from upstream and merge into your local branch. This section explains every step.

Why this is necessary¶

When you forked the repository, GitHub created a snapshot of main at that moment. Any commits pushed to the upstream main after your fork was created are not automatically reflected in your fork. If you work on a feature branch for several days, the upstream main may have moved ahead — your branch will be "behind." Merging upstream changes prevents conflicts from accumulating and ensures you are building on the latest codebase.

One-time setup (already done if you followed step 7)¶

Verify that you have the upstream remote configured:

git remote -v

You should see two remotes:

origin    git@github.com:YOUR_USERNAME/canvodpy.git (fetch)
origin    git@github.com:YOUR_USERNAME/canvodpy.git (push)
upstream  git@github.com:nfb2021/canvodpy.git (fetch)
upstream  git@github.com:nfb2021/canvodpy.git (push)

If upstream is missing, add it:

git remote add upstream git@github.com:nfb2021/canvodpy.git

Update your local main branch¶

Every time you want to sync with the latest upstream changes:

# 1. Switch to your local main branch
git checkout main

# 2. Fetch all new commits from the upstream repository
git fetch upstream

# 3. Merge upstream/main into your local main
#    This is a fast-forward merge (no merge commit) if you have not
#    committed directly to your local main — which you should not do.
git merge upstream/main

# 4. Push the updated main to your fork on GitHub
git push origin main

After these four commands, your fork's main branch on GitHub is identical to the upstream main.

Update your feature branch¶

If you are working on a feature branch, incorporate the freshly updated main:

# Switch to your feature branch
git checkout feature/my-feature

# Rebase your feature branch onto the updated main
git rebase main

Rebasing replays your commits on top of the latest main, producing a linear history. If Git reports a merge conflict during rebase, it will pause and show you which files conflict. Resolve each conflict by editing the file, then:

git add <resolved-file>
git rebase --continue

If you want to abort the rebase and return to the state before:

git rebase --abort

git push --force-with-lease origin feature/my-feature

Quick reference¶

# Full sync sequence (run periodically):
git checkout main
git fetch upstream
git merge upstream/main
git push origin main
git checkout feature/my-feature
git rebase main

12b. Working in teams¶

During collaborative sprints, each team works on its own topic (often aligned with a package such as canvod-grids or canvod-readers). A shared develop branch acts as the integration point — no one commits to it directly. Instead, each team gets its own team branch.

Branch structure¶

main
└── develop/sprint-2026              ← integration branch (shared by all teams)
    ├── team-grids/                  ← Team A
    │   ├── (direct commits)         ← Workflow A
    │   └── team-grids/add-healpix   ← Workflow B feature branches
    ├── team-readers/                ← Team B
    └── team-vod/                    ← Team C

Set up the team branch¶

The team lead creates the branch once:

git checkout develop/sprint-2026
git checkout -b team-grids
git push -u origin team-grids

All other team members fetch and switch to it:

git fetch origin
git checkout team-grids

From here, choose the workflow that fits your team:

# Make your changes, then:
git add <files you changed>
git commit -m "feat(grids): add new grid type"
git push origin team-grids

git pull --rebase origin team-grids
git push origin team-grids

git checkout team-grids
git checkout -b team-grids/add-healpix

git add <files you changed>
git commit -m "feat(grids): add HEALPix support"
git push -u origin team-grids/add-healpix

git checkout team-grids
git pull origin team-grids
git checkout team-grids/add-healpix
git rebase team-grids

Merge the team's work into the develop branch¶

When your team's feature is ready, open one pull request from team-grids into the develop branch on GitHub. This is where the maintainer reviews the team's combined work.

13. Your first contribution¶

Make your changes¶

Edit files with your favorite text editor or IDE.

Run quality checks¶

just test
just check

Stage and commit¶

git add <files you changed>
git commit -m "feat(grids): add new grid type"

Commit messages follow the Conventional Commits format: type(scope): description. Common types: feat, fix, docs, test, refactor.

Push¶

Push to your team branch or feature branch (see Working in teams above).

Open a pull request¶

1. Go to your fork on GitHub — you'll see a banner suggesting to open a pull request.
2. Click Compare & pull request.
3. Set the base branch to your team branch (or the develop branch, depending on your workflow).
4. Add a title and description, then click Create pull request.

14. Pre-commit hooks and why your commit may be rejected¶

When you ran just hooks in step 9, a set of pre-commit hooks was installed into your local .git/hooks/ directory. These hooks run automatically every time you execute git commit. If any hook fails, the commit is aborted — your changes remain staged but no commit is created.

This is intentional: it prevents code that does not meet the project's quality standards from entering the Git history. The hooks are defined in .pre-commit-config.yaml at the repository root.

What runs on every commit¶

The following checks execute automatically in sequence. If any one fails, the commit is rejected.

How to fix a rejected commit¶

When a hook fails, read the error output carefully. The most common scenarios:

# The hook already ran ruff --fix, so files may have been modified.
# Check what changed:
git diff

# If the changes look correct, stage them and commit again:
git add -u
git commit -m "feat(readers): your original message"

commit validation: failed!
please enter a commit message in the commitizen format.

type(scope): subject

git commit -m "feat(readers): add RINEX 4.0 parser"
git commit -m "fix(store): handle empty epoch arrays"
git commit -m "docs: update installation guide"
git commit -m "test(vod): add tau-omega edge cases"

git commit -m "added new feature"           # no type prefix
git commit -m "feat: add stuff"              # too vague (but technically valid)
git commit -m "FEAT(readers): add parser"    # type must be lowercase
git commit -m "feat(readers) add parser"     # missing colon after scope

uv sync          # regenerates uv.lock
git add uv.lock
git commit -m "feat(readers): your original message"

git reset HEAD <large-file>
echo "<large-file>" >> .gitignore
git add .gitignore
git commit -m "chore: update gitignore"

Bypassing hooks (emergency only)¶

In rare situations where you need to commit despite a hook failure (e.g., you are certain the failure is a false positive), you can skip hooks:

git commit --no-verify -m "fix(store): emergency hotfix"

15. Continuous integration and test coverage¶

Every push to a branch and every pull request triggers automated checks on GitHub Actions. These are the same checks that run locally via just check and just test, but they execute in a clean environment to ensure reproducibility.

CI pipelines¶

Test coverage with Coveralls¶

The project uses Coveralls to track test coverage over time. After each test run in CI:

1. pytest generates a coverage report in LCOV format (coverage.lcov)
2. The report is uploaded to coveralls.io/github/nfb2021/canvodpy
3. A coverage summary is posted as a comment on the pull request, showing which lines are covered and which are not

Coverage is not a gate (your PR will not be blocked by low coverage), but it is visible to reviewers. When adding new code, include tests — this is both good scientific practice (every computation should be verifiable) and a courtesy to future contributors who need to understand what the code does.

To measure coverage locally before pushing:

just test-coverage
# Opens an HTML report in your browser showing line-by-line coverage

16. Common commands cheat sheet¶

Next in the trail: Audit Suite · API Levels · Architecture · AI Development