Skip to content

contributing.rst

Latest commit

 

History

History
334 lines (229 loc) · 8.18 KB

contributing.rst

File metadata and controls

334 lines (229 loc) · 8.18 KB

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 :doc:`run it locally <before_you_start>`. 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 :doc:`../for_researchers/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: :doc:`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