Contributing to Arcane
Set up the Arcane development environment and submit a pull request.
Run Arcane locally and get your change merged. The dev environment runs the frontend and backend in Docker with hot reload.
Ways to contribute
Section titled “Ways to contribute”- Report bugs using the issue template.
- Suggest features in Discussions. Proposals and voting happen there; maintainers open linked implementation issues when work is ready.
- Ask development questions in Discussions.
- Contribute code (frontend, backend, DevOps), documentation, or testing.
- Translate via Crowdin. See Translating Arcane.
Set up the development environment
Section titled “Set up the development environment”You need Docker and Docker Compose, just, and Vite+ for the Node toolchain, formatting, linting, and pre-commit hooks outside Docker. Go checks also need Go and golangci-lint on your machine.
Install Vite+:
curl -fsSL https://vite.plus | bashRun every command from the project root (arcane/) unless stated otherwise.
- Fork and clone the repository, then enter it:
git clone https://github.com/getarcaneapp/arcane.gitgit clone git@github.com:getarcaneapp/arcane.gitgh repo clone getarcaneapp/arcanecd arcane-
Check Docker and the Compose config:
Terminal window docker infodocker compose versiondocker compose -f docker/compose.dev.yaml -p arcane-dev config -
Start the development environment. This starts both services with hot reload, installs dependencies inside Docker, and creates persistent storage for dev data.
Terminal window ./scripts/development/dev.sh start -
Confirm the stack is up:
Terminal window ./scripts/development/dev.sh statuscurl -f http://localhost:3000curl -f http://localhost:3552/api/health- Frontend: http://localhost:3000 (SvelteKit with HMR)
- Backend: http://localhost:3552 (Go with Air hot reload)
-
Enable the pre-commit hooks once, so format checks run on staged files:
Terminal window vp hooks enable
Use VS Code (optional)
Section titled “Use VS Code (optional)”Open the project root (arcane/) and install the recommended Docker, Go, and Svelte/TypeScript extensions. Use Ctrl/Cmd+Shift+P → Tasks: Run Task for Start, Stop, Restart, Rebuild, Logs, and Open Frontend. Ctrl/Cmd+Shift+B starts the environment. The Clean task removes the development containers and volumes, including their data.
Make a change
Section titled “Make a change”-
Create a branch:
Terminal window git switch -c feat/project-labelsgit switch -c fix/issue-123 -
Edit code. Vite reloads the frontend and Air rebuilds and restarts the backend. Watch logs with
./scripts/development/dev.sh logs, orlogs frontend/logs backendfor one service. -
Format, then lint:
Terminal window just format alljust lint allFix everything
just lint allreports. Frontend formatting and lint rules live in the rootvite.config.ts; Go rules live in.golangci.yml. -
Run the tests for what you changed, such as
just test backendorjust test cli. -
Commit using Conventional Commits. Types are
feat,fix,docs,style,refactor,test, andchore:Terminal window git commit -m "feat: add user authentication"git commit -m "fix: resolve Docker volume mounting issue"
Open a pull request
Section titled “Open a pull request”Keep each PR to one feature or fix, link issues with Closes #123 or Fixes #456, and respond to review feedback. Update the documentation if you change APIs or add features. Before you submit, check that:
- The code builds in the development environment
- Frontend and backend both run, and hot reload works for each
- There are no lint errors
- Commit messages follow the conventional format
- The PR description explains the change and why it’s needed
Dev script reference
Section titled “Dev script reference”./scripts/development/dev.sh start./scripts/development/dev.sh status./scripts/development/dev.sh stop./scripts/development/dev.sh restart./scripts/development/dev.sh rebuild./scripts/development/dev.sh logs [frontend|backend]./scripts/development/dev.sh shell frontend./scripts/development/dev.sh shell backendUse restart after config changes and rebuild after dependency changes.
Go modules
Section titled “Go modules”The repository is a Go workspace (go.work) with three modules:
| Directory | Module path |
|---|---|
backend/ |
getarcane.dev/arcane/v3 |
cli/ |
getarcane.dev/cli/v3 |
types/ |
getarcane.dev/types/v3 |
Shared API types live in types/, imported as getarcane.dev/types/v3.
Database migrations
Section titled “Database migrations”Migrations are Goose Go files in backend/internal/database/migrations, one per schema change.
- Add
NNNNN_name.go, numbered one past the latest file. Goose reads the version from the filename. - Put raw SQL for SQLite and Postgres in top-level constants. Don’t import GORM, domain packages, or
types/. - Register it in
init()withgoose.AddMigrationContext(run(sqliteUp, postgresUp), run(sqliteDown, postgresDown)). Pass the same constant twice when both dialects match. - Add an up/down test in
backend/internal/database/database_test.go.
Version 94 is a baseline equal to Arcane v2.17.1. Older databases upgrade to v2.17.1 first.
Justfile reference
Section titled “Justfile reference”just --list shows every target. Common ones:
| Task | Command |
|---|---|
| Rebuild and start the Docker dev environment | just dev docker |
| Follow Docker dev logs | just dev logs |
| Run frontend and backend without Docker | just dev all |
| Run a local agent against a manager | ARCANE_AGENT_TOKEN=<token> just dev agent |
| Build the frontend or backend | just build single frontend, just build single backend |
| Run tests | just test backend, just test cli, just test e2e |
| Format and lint | just format all, just lint all, just format frontend, just lint backend |
| Install dependencies | just deps install all |
Run checks inside the Docker dev environment
Section titled “Run checks inside the Docker dev environment”docker compose -f docker/compose.dev.yaml -p arcane-dev exec frontend vp -C frontend run checkdocker compose -f docker/compose.dev.yaml -p arcane-dev exec backend go vet ./...