Skip to main content

​
Before you start

Make sure you have the repository cloned and your local environment working. See Environment Setup if you haven’t done this yet. All contributions go through a branch → pull request → review → merge workflow. Direct pushes to main are not allowed.

​
Git workflow

1

Pull the latest main

Make sure your local main is up to date before branching:
git checkout main
git pull
2

Create a branch

Branch names should be short and descriptive, using kebab-case. Prefix with the type of change:
git checkout -b feat/add-challenge-filters
# or
git checkout -b fix/completion-duplicate-error
# or
git checkout -b docs/update-contributing-guide
Common prefixes:
PrefixUse for
feat/New features
fix/Bug fixes
docs/Documentation changes
chore/Maintenance, dependency updates, tooling
refactor/Code restructuring without behavior change
3

Make your changes

Write your code, tests, or documentation. Keep commits small and focused — one logical change per commit.
4

Stage and commit

Stage your files and commit using the Conventional Commits format:
git add .
# or stage specific files:
git add backend/src/routes/challenges.routes.ts

git commit -m "feat: add difficulty filter to challenges endpoint"
Commit message format:
<type>: <short description>
TypeWhen to use
featA new feature
fixA bug fix
docsDocumentation only
choreTooling, dependencies, CI
refactorRestructuring without behavior change
testAdding or updating tests
styleFormatting, whitespace (no logic change)
Keep the description in the imperative mood and lowercase: “add filter” not “Added filter” or “Adds filter”.
5

Push your branch

git push -u origin feat/add-challenge-filters
6

Open a pull request

Go to the repository on GitHub and open a pull request against main. Fill out the PR template and:
  • Link to the corresponding issue (e.g., Closes #42)
  • Add a clear description of what changed and why
  • Request a reviewer from the team
7

Address review feedback

Make any requested changes on your branch, then push again. The PR will update automatically:
git add .
git commit -m "fix: handle empty results in challenge filter"
git push
8

Merge

Once your PR has at least one approval and all checks pass, it is ready to merge. A maintainer will merge it into main.

​
Pull request checklist

Before requesting a review, confirm:
  • Your branch is up to date with main (rebase or merge if needed)
  • Your commit messages follow the conventional format
  • The PR is linked to an issue
  • You have assigned a reviewer

​
Commit message examples

# Features
git commit -m "feat: add leaderboard pagination"
git commit -m "feat: show streak badge on profile screen"

# Bug fixes
git commit -m "fix: prevent duplicate flag submission"
git commit -m "fix: refresh token before upload request"

# Docs and chores
git commit -m "docs: add database schema reference"
git commit -m "chore: upgrade prisma to 6.19"

Environment setup

Get your local environment running before contributing.

Architecture

Understand the codebase structure before making changes.

Build docs developers (and LLMs) love

Get started for freeTalk to us