Skip to content

Contributing

Jump to bottom
Wouter Meetsma edited this page Jun 20, 2026 · 2 revisions

Contributing

Thank you for wanting to improve Rubric Maker. This page covers the workflow for contributing code, translations, and bug reports.

Getting started

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone git@github.com:<your-username>/RubricMaker.git
cd RubricMaker
  3. Install dependencies: 
    npm install
  4. Create a feature branch from main: 
    git checkout -b feat/my-feature
  5. Make your changes.
  6. Verify everything passes: 
    npm run typecheck
npm run lint
npm run test
  7. Push your branch and open a pull request against main.

Branch naming

Use a short prefix that describes the type of change:

Prefix Use for
feat/ New features
fix/ Bug fixes
docs/ Documentation changes
refactor/ Code changes with no behaviour change
test/ Adding or fixing tests
chore/ Build, CI, dependency updates

Example: feat/voice-grading-nl or fix/export-pdf-unicode.

Pull request guidelines

  • One pull request per feature or fix. Keep PRs focused — reviewers can't give useful feedback on large, mixed changesets.
  • Write a clear description explaining what changed and why.
  • All CI checks must pass before a PR can be merged:
    • Type-check (npm run typecheck)
    • Lint (npm run lint)
    • Tests with coverage (npm run coverage)
  • If your change affects the UI, include a screenshot or short screen recording in the PR description.
  • If your change adds a user-facing string, add the translation key to all five locale files: en.json, nl.json, fr.json, de.json, es.json.

Writing tests

  • Co-locate tests with their source file in a __tests__/ subdirectory.
  • Use src/test-utils/renderWithProviders.tsx for components that need React Context.
  • Test behaviour, not implementation. Check what the user sees and does, not internal state.
  • Mock only what you must (browser APIs, external services). Prefer testing against real implementations where possible.

Coding conventions

  • All code is TypeScript. Avoid any — use proper types or generics.
  • No default export default for utilities — named exports only so IDE auto-import works reliably.
  • Keep components under ~300 lines. If a component grows beyond that, consider splitting out sub-components.
  • No CSS-in-JS library. Use inline style props referencing the existing global CSS custom properties (--accent, --text, --bg-elevated, etc.) so theming and dark/light mode keep working.
  • No comments explaining what the code does — only comments explaining why something non-obvious is done.

Adding translations

See Internationalisation for a step-by-step guide to adding a new language or editing existing translations.

If you spot a missing or incorrect translation in any of the five locales, you can fix it directly in the corresponding src/locales/*.json file and open a PR — no code changes needed.

Reporting bugs

Open an issue on GitHub with:

  1. A clear title describing the problem.
  2. Steps to reproduce.
  3. What you expected to happen.
  4. What actually happened (screenshots help).
  5. Browser and OS version.

Suggesting features

Open an issue with the enhancement label. Describe the use case first (the why), then the proposed solution. Feature requests with a clear educator use case are more likely to be accepted.

Clone this wiki locally