Skip to content

Repository navigation

CONTRIBUTING.md

Latest commit

 

History

History
99 lines (70 loc) · 3.2 KB

CONTRIBUTING.md

File metadata and controls

99 lines (70 loc) · 3.2 KB
Raw

Contributing to Millwright

Before contributing

Open a GitHub issue before starting a contribution. Describe the problem, who it affects, and what you propose to change. Get maintainer approval before writing code or opening a pull request. Unsolicited pull requests will be declined.

Millwright is a personal-first project. Bug fixes, useful features, and measured performance improvements take priority over personal preferences or changes made only to reorganize the code.

Development

Requirements

  • Python 3.14+ and uv.
  • PostgreSQL 18. The setup below uses Docker Compose to run it.
  • FFmpeg and ffprobe. MKVToolNix is optional for subtitle repair and MKV statistics.
  • Bun for frontend packages and commands.
  • A Node.js version supported by Nuxt for Vue type checking.

Setup

Create a branch from dev:

git clone https://github.com/arabcoders/millwright.git
cd millwright
git switch dev
git pull origin dev
git switch -c feature/descriptive-name
uv sync
./.githooks/install

Start the database and reloading server with a local node from the repository root:

docker compose -f compose.dev.yml up -d --no-deps --wait postgres
uv run python run.py --role all --dev

Development uses AIO by default. The database is temporary and loses its data when the container stops. Use --role server only when you don't need the local node.

In another terminal, start the frontend from ui/:

bun install --frozen-lockfile
NUXT_API_URL=http://127.0.0.1:8000/api bun run dev

Open http://localhost:8082 and create your account. Keep /api at the end of NUXT_API_URL.

See the development guide for persistent databases, container builds, local OIDC testing, migrations, and documentation publishing. For deployment and GPU setup, use the installation guide.

Checks

Database tests use their own PostgreSQL service:

docker compose -f compose.dev.yml up -d --no-deps --wait postgres-test

Run Python checks from the repository root:

.githooks/pre-commit --unstaged

The hook runs formatting, linting, type checks, and tests. Without an argument it checks staged files. Use --all to check a clean checkout too.

From ui/, run:

bun run format:check
bun run lint:ci
bun run lint:tsc
bun test
bun run build

Test behavior that could break and assert its outcome. Reuse existing tests where possible. Update user documentation when behavior or setup changes.

Pull requests

Target dev, not master, and reference the approved issue. Explain the change, any breaking interfaces or migration steps, and how you checked it. Use Conventional Commits.

AI-assisted tools are allowed. You remain responsible for understanding and reviewing the code, tests, and documentation you submit. Contributions are licensed under the project's MIT license.

For short questions, use Discord. Millwright is maintained as a solo project, so replies may take time.