Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
168 lines (112 loc) · 5.16 KB

CONTRIBUTING.md

File metadata and controls

168 lines (112 loc) · 5.16 KB
Raw

Contributing

Thank you for your interest in contributing! This document explains how to get involved, what we expect, and how to get your changes merged.

Table of Contents

Code of Conduct

This project follows the Contributor Code of Conduct. By participating, you agree to follow these standards. Please report unacceptable behavior to the maintainers.

Getting Started

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/your-username/your-repo.git
cd your-repo

  3. Add the upstream remote:

    git remote add upstream https://github.com/your-org/your-repo.git

  4. Run ./bin/mat setup (native Windows without WSL2: .\bin\mat.ps1). This activates the Git hooks (validates commit messages locally before you push), creates .env from .env.example, and sets up the reproducible dev shell (Nix/direnv/devenv). See docs/team-process/how-to/activate-git-hooks for what the hooks do.

  5. Follow the full setup guide: docs/product-code/tutorials/getting-started

How to Contribute

Reporting Bugs

Before opening an issue:

  • Search existing issues to avoid duplicates
  • Make sure you are on the latest version (git pull upstream main)

When opening a bug report, use the Bug Report template and include:

  • Steps to reproduce
  • Expected vs actual behavior
  • Your environment (OS, runtime version, relevant tool versions)
  • Relevant logs or screenshots

Suggesting Features

Open a Feature Request issue with:

  • A clear description of the problem the feature solves
  • Your proposed solution
  • Alternatives you considered

Features that align with the project's scope and architecture are more likely to be accepted.

Submitting Code Changes

  1. Create a branch from main:

    git checkout main
git pull upstream main
git switch -c feat/your-feature-name

  2. Make your changes following the code style guidelines

  3. Write or update tests

  4. Run the validation suite locally (see Getting Started)

  5. Commit following commit conventions

  6. Push and open a Pull Request

Commit Conventions

We follow Conventional Commits. Each commit message should be:

<type>(<scope>): <short description>

[optional body]

[optional footer]

Types:

Type When to use
feat New feature or behavior
fix Bug fix
refactor Code change with no behavior change
test Adding or updating tests
docs Documentation only
chore Tooling, dependencies, config
perf Performance improvement
ci CI/CD changes

Scope (optional): the module or area affected, e.g. auth, api, ui, docker.

Examples:

feat(auth): add refresh token revocation on logout
fix(api): return 409 when resource already exists
refactor(core): extract validation to separate utility
test(auth): add unit tests for login use case
docs(setup): add environment variable reference
chore(deps): upgrade dependencies

Rules:

  • Use the imperative ("add" not "adds" or "added")
  • Keep the first line under 72 characters
  • Reference issues in the footer: Closes #42, Fixes #17

Enforced automatically both locally (if hooks are activated) and in CI. See docs/operations/concept/ci-cd-pipeline for how.

Pull Request Process

  1. One PR per concern. Don't mix unrelated changes.
  2. Fill the PR template. Describe what changed and why.
  3. Keep diffs small. Large PRs are hard to review; split if needed. Aim for something reviewable in under 30 minutes.
  4. All CI checks must pass before merging.
  5. Address review comments. Don't force-merge; iterate on feedback.
  6. Squash or rebase on main before merge if history is messy.

PRs are merged by maintainers once they have one approving review and all checks are green. See docs/organizational/reference/todo_tool-inventory / .github/CODEOWNERS for who that is on this project.

Code Style

See docs/product-code/reference/code-style for detailed conventions.

Testing

Every PR should maintain or improve the existing test coverage.

Questions?

Open a Discussion.