Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
191 lines (121 loc) · 5.07 KB

CONTRIBUTING.md

File metadata and controls

191 lines (121 loc) · 5.07 KB

Contributing to Matorral

We welcome contributions! This guide will help you get up and running.

If you have questions, reach out on GitHub Discussions — we're happy to help.

Found a bug? Please open an issue.

A Note on Feature Contributions

Matorral is intentionally designed to be a simple, focused project management tool. We care deeply about keeping it approachable and avoiding unnecessary complexity — every feature we add is a feature every user has to understand, and every option we introduce is one more thing that can go wrong.

Because of this, we ask that you reach out before investing time in a new feature. Please open a GitHub Discussion or issue to share your idea and get feedback from the maintainers first. This conversation helps us align on whether the feature fits the project's direction — and it saves you from putting effort into a pull request that we may not be able to accept.

We genuinely appreciate every contribution, and we want to make sure yours lands. Talking first is the best way to ensure that happens.

Bug fixes and improvements to existing behavior are always welcome and generally don't need prior discussion.

Getting Started

Requirements

Fork and clone

  1. Fork the repository on GitHub.
  2. Clone your fork locally:
git clone git@github.com:your-username/matorral.git
cd matorral

First-time setup

Copy the example env file and review the values (at minimum, set SECRET_KEY):

cp .env.example .env

Then run the init command, which builds containers, runs migrations, and seeds the database:

just init

Start the app

just start              # start all containers with logs
just start-detached     # start in background
just logs               # tail logs

Open http://localhost:8000. Create an admin account:

just createsuperuser

To stop:

just stop

Note: Any change to pyproject.toml requires just requirements to rebuild the containers.

Running Tests

Tests run inside Docker via just. Use dotted module paths, not file paths:

# Run all tests
just test

# Run tests for a specific app
just test apps.issues

# Run a specific test module
just test apps.issues.tests.test_views

# Run a specific test class or method
just test apps/issues/tests/test_models.py::TestIssueModel::test_method

# Run tests with coverage and print report
just cov

# Run tests with coverage only (no report)
just test-cov

# Print coverage report from a previous run
just cov-report

You can also run tests locally without Docker using uv:

uv run pytest apps/ -v --tb=short
uv run pytest apps/issues/ -v

Note: Running locally requires a reachable PostgreSQL instance. The Docker setup is recommended.

Setting Up pre-commit

We use pre-commit to run linters and code checks before every commit. Please set this up before making any changes — it's what CI will check too.

Install pre-commit (if you don't have it):

pip install pre-commit
# or via brew:
brew install pre-commit

Then install the hooks in your local repo:

pre-commit install

From now on, the following checks will run automatically on git commit:

  • ruff — linter and formatter (line length: 120, double quotes)
  • black — code formatter
  • isort — import sorter (black profile)
  • pyupgrade — upgrades syntax to Python 3.14
  • codespell — spell checker

You can also run all hooks manually at any time:

pre-commit run --all-files

Making Changes

  1. Create a branch for your work:
git checkout -b my-feature-or-fix

  1. Make your changes and write tests. We aim for good test coverage — please include tests for any new behavior or bug fixes.

  2. Ensure all tests pass:

just test
  1. Ensure pre-commit checks pass:
pre-commit run --all-files
  1. Push your branch to your fork and open a pull request against main.

We typically respond to pull requests within a few days. Pull requests are more likely to be accepted when they:

  • Include tests covering the changes
  • Follow the existing code style (enforced by pre-commit)
  • Have a clear description of what the change does and why

Notes for LLM-Assisted Development

If you are using an AI assistant (Claude, Copilot, Cursor, etc.) to help with contributions, point it at CLAUDE.md and AGENTS.md. These files contain architecture notes, patterns, and conventions that help the model understand the codebase correctly.

Tech Stack

Django · PostgreSQL · Redis · Celery · HTMX · Alpine.js · Tailwind CSS · DaisyUI · Vite