Altair

Contributing

Altair is an AGPL v3+ project, which means the code is yours to read, modify, and improve — on the condition that your improvements are shared forward under the same license. This page is for people who want to contribute code, docs, or architectural input back to the project.

Before you open a PR

A few things that will save everyone time:

  • Read CLAUDE.md and DESIGN.md in the repo root. They document development conventions and the design system. Most PR feedback traces back to one of them.
  • Check existing issues and the backlog. The thing you’re thinking about might already be planned, or already decided against.
  • For larger changes, propose first. Open an issue describing the problem and the approach before writing the code. It’s easier to redirect a sketch than a finished PR.

Dev setup

Altair is a monorepo. Get the toolchains installed once, and every sub-project works:

# mise manages bun, rust, and java for the whole repo
mise install

# sqlx CLI for database migrations
cargo install sqlx-cli --no-default-features --features postgres

# Start the backing infrastructure (postgres + rustfs + server)
cd infra/compose && docker compose up -d
cd ../..

# Apply migrations
DATABASE_URL=postgres://altair_user:yourpassword@localhost:5432/altair_db 
  sqlx migrate run --source infra/migrations

From there, each client has its own run command — see the self-hosting guide for the specifics.

The planning workflow

Altair uses a four-phase, spec-driven planning workflow. For anything non-trivial, the expectation is that work goes through it:

  1. Spec — define what and why. Produces a Spec.md with testable assertions about the feature.
  2. Tech research — decide how to build it. Produces a Tech.md with architecture decisions.
  3. Steps — break the work into tasks with tests and docs. Produces a Steps.md with milestones.
  4. Implementation — build, verify at milestones, commit.

Trivial changes skip the full flow and use a single-file quick plan. What counts as trivial is a judgement call; a good heuristic is “one file, no architectural implications.”

The planning commands (e.g. /blueprint, /quick, /impl) are set up to be used with Claude Code. They are scaffolding, not law — but the documents they produce are part of the project’s long-term record.

Architecture decisions

Anything that deviates from a spec, or that the team will need to remember the reasoning for in six months, gets an Architecture Decision Record in Context/Decisions/. There are ~35 ADRs so far. Read a few before writing one — they’re short, and they’ll tell you the house style.

ADRs don’t have to be right forever. Supersession is a normal outcome: ADR-006 (OAuth/OIDC) was later replaced by ADR-012 (built-in auth with Argon2id + JWT), and that history is part of the record.

Conventions

  • Conventional commits. feat:, fix:, docs:, chore:, etc. Include a task or ADR reference in the body when relevant.
  • Stack-specific rules live in .claude/rules/. If you’re working in Svelte, Rust, or Kotlin, skim the matching rules file first.
  • Tests and docs are planned alongside implementation. Milestone checkpoints are designed around “build this, verify it works, write down what it does.”
  • Surgical changes. Don’t “improve” adjacent code in an unrelated PR. Notice it, mention it, open a separate PR.

What makes a good PR

Small. Focused on one thing. Describes the problem before the solution. Matches existing style. Tests where tests are meaningful. References the spec or ADR that motivated it.

The reviewer’s job is to protect the long-term health of the codebase. The contributor’s job is to make that easy.

Reporting bugs

Open an issue on GitHub. Include:

  • What you did.
  • What you expected.
  • What actually happened.
  • Your environment (OS, client version, server version, browser if relevant).

If the bug is security-sensitive, don’t open a public issue. Email the maintainers directly — the contact address is in the repository’s security policy.

Reporting design or accessibility regressions

Altair targets WCAG AA and has specific ADHD-friendly design requirements documented in DESIGN.md. If you notice something that feels off — motion that doesn’t respect prefers-reduced-motion, focus states that don’t show up, navigation that moved between screens — open an issue with the a11y label. These are taken seriously.

License

By contributing, you agree that your contribution is licensed under AGPL v3 or later, the same license as the project itself. This is how the project stays free for the next person.

Thanks for being here.