Open-Source Contributor Guide

Who this is for: External developers who want to contribute to CARE, whether you found a bug, want to improve the docs, propose a feature, or simply want to work on a meaningful research platform.

Step 1: Understand the Product First

Before touching any code, use the product. Visit the live demo or run it locally. Try both sides:

Researcher side — log in and explore the dashboard. A good starting path is:
1. Upload a document (Dashboard → Documents → add a new document).
2. Create a study on top of that document (Dashboard → Studies → add a new study, use the Peer Review workflow).
Participant side :
1. Start the study as a participant.
2. Go through the annotator step.
3. Then continue with the editor step.

For more detail, see Basics.

Step 2: What to Work on

Issues

You can create an issue when:

You found a concrete bug you can describe clearly
You have a specific, well-defined feature request
You want to propose a documentation improvement with defined scope

Do not open vague issues. If you do not have a specific well-defined issue in mind, browse open issues available for newcomers under the good first issue label. Moreover, before starting work on an issue, comment on it to signal your intent.

Issue Templates

There are different types of issues you would like to create. Each has a specific template that you need to follow and are pre-defined once you create a new issue. You can read examples of similar issues in the CARE issue tracker, filtered by the available types.

Once you decide what issue you are going to work on, follow the steps below.

Step 3: Fork and Clone the Repository

As an external contributor you cannot push directly to the CARE repository.

Fork

Go to the repository
Click the Fork button
Choose your GitHub account

You now have a copy at https://github.com/YOUR_USERNAME/CARE.

Clone your fork

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

Add the upstream remote

This links your local repository to the official CARE repository so you can pull future updates:

git remote add upstream https://github.com/UKPLab/CARE.git

Verify your remotes:

git remote -v

You should see:

origin    https://github.com/YOUR_USERNAME/CARE.git (fetch)
origin    https://github.com/YOUR_USERNAME/CARE.git (push)
upstream  https://github.com/UKPLab/CARE.git (fetch)
upstream  https://github.com/UKPLab/CARE.git (push)

origin is your fork, you push here.
upstream is the official repo, you pull from here.

Note

A detailed guidance is available on official guideline forking guide for more on contributing through forks.

Step 4: Run CARE Locally

Follow the official guide: Before You Start.

Step 5: Git Workflow for External Contributors

Branch structure

Branch	Purpose
`main`	Stable, production-ready. Protected. Maintainers only.
`dev`	Active development. Protected. All contributions target here.
`feat-*`	Your feature branches, created from `dev`, merged back to `dev` via PR.
`hotfix-*`	Urgent bug fixes, created from `main`, merged back to `main`.

You always work on a branch, never directly on dev.

Starting work on a new contribution

First, make sure your local dev is up to date with upstream:

git fetch upstream
git checkout dev
git merge upstream/dev

Then create your branch:

git checkout -b feat-ISSUENUMBER-short-description dev

Branch naming conventions

Type	Pattern	Example
Feature	`feat-ISSUENUMBER-shortname`	`feat-42-add-csv-export`
Bug fix	`fix-ISSUENUMBER-shortname`	`fix-87-login-redirect`
Documentation	`docs-ISSUENUMBER-shortname`	`docs-12-update-setup-guide`
Hotfix	`hotfix-ISSUENUMBER`	`hotfix-99-session-crash`

Use dashes to separate parts. Keep names short and descriptive. Always include the issue number.

Commit message format

<type>: <short description in present tense>

Type	Use for
`feat`	New feature
`fix`	Bug fix
`refactor`	Code restructuring with no behavior change
`docs`	Documentation only
`test`	Tests only
`style`	Formatting, whitespace
`ci`	CI configuration
`chore`	Build scripts, dependencies, maintenance

Rules:

Present tense: “add” not “added”
Lowercase
No period at the end
One logical change per commit
A commit should represent at most one day of work

Good: fix: resolve null check in document save handler

Bad: fixed stuff / WIP / changes / update

Pushing to your fork

git push
# First push: git push --set-upstream origin feat-ISSUENUMBER-short-description

Push to origin (your fork), never to upstream.

Keeping your branch up to date

If dev has moved forward since you started your branch, sync before opening a PR:

git fetch upstream
git checkout dev
git merge upstream/dev
git checkout feat-ISSUENUMBER-short-description
git merge dev
git push

Warning

Do not squash commits — the team has found that squashed commits cause merge conflicts in downstream branches. Keep individual commits intact.

Step 6: Opening a Pull Request

Before opening

git fetch upstream
git checkout dev
git merge upstream/dev
git checkout your-branch
git merge dev
git push

PR title format

PR title should include the type, followed by the issue number, and then a short description of the issue.

Format: <Type> <ISSUE_NUMBER> <short description>

Example: Feat 54 add active users monitoring

PR description template

For the body, follow this template:

## Summary
Short summary describing what this PR does

## New User Features
- List user-facing features introduced in this PR.

## New Dev Features
- List developer-facing changes (tooling, configs, architecture)

## Improvements
- List non-breaking improvements (refactors, consistency fixes, optimizations)

## Bug Fixes
- List bugs fixed, include rule names / modules if relevant

## Known Limitations
- List any known issues, incomplete work, or trade-offs, if any.

## Future Steps
- List follow-up work, additional PRs, or planned improvements

Step 7: Navigating Code Review

How to respond

git add .
git commit -m "fix: address review comments"
git push

Reply to each thread with:

Resolved in commit <hash>

Step 8: Staying in Sync

As CARE continues to develop, your fork will fall behind upstream. Sync regularly, especially before starting new work:

git fetch upstream
git checkout dev
git merge upstream/dev
git checkout feat-branch
git merge dev
git push