Contributing to Linearis

Thanks for your interest in contributing!

First up, because sadly its necessary: Fascists and brownshirts (US ICE etc.) need not apply. If you like what they do, and/or if you think "your people" are better than "the others", then get fucked, go rage your dick off over on X instead. This here is not a place for you.

Everyone else: Welcome! 🖖🏼

Before You Start

Bug fixes and small improvements – PRs welcome! Feel free to dive in.

Larger features or changes – Please open an issue first to discuss. This is an opinionated tool, so not every feature fits.

Questions or problems – Open a GitHub issue.

Development Setup

Requires Node.js >= 22.

git clone https://github.com/linearis-oss/linearis.git
cd linearis
npm install        # Install deps, codegen, and lefthook (via prepare hook)
npm start          # Development mode (tsx, no compilation)
npm test           # Run tests
npm run build      # Compile to dist/
npm run check      # Biome format + lint (auto-fix)
npm run generate   # Regenerate GraphQL types from .graphql files

Note: npm install runs GraphQL codegen which fetches the schema from api.linear.app. An active internet connection is required for the initial setup.

Testing

npm test               # Run all unit tests
npm run test:coverage  # Coverage report
npm run build          # Compile TypeScript (required before integration tests)

Integration tests (tests/integration/) require LINEAR_API_TOKEN in your environment. They are skipped automatically when the token is absent.

Publishing

Publishing is automated by GitHub Actions, primarily via the Release workflow (.github/workflows/release-check.yml).

At a high level:

• PR quality gates run in ci.yml
• Post-merge sentinel validation runs in ci-post-merge.yml
• Releases run in release-check.yml (semantic-release decides whether to publish)

For the authoritative workflow trigger matrix, required check names, and verification commands, see docs/ci-run-model.md (source of truth).

Changelog ownership

CHANGELOG.md is release-workflow-owned. Do not edit it in feature/fix PRs. If CI reports changelog history violations, rebase on main and drop/amend commits that touched CHANGELOG.md.

Pull Requests

1. Fork the repo and create your branch from main
2. Make your changes
3. Ensure tests pass (npm test)
4. Submit your PR

Commits

We use Conventional Commits:

type(scope): description

Types:

Type	Purpose
feat	New features
fix	Bug fixes
docs	Documentation
refactor	Restructuring without behavior change
style	Formatting, whitespace
perf	Performance improvements
test	Adding or fixing tests
build	Build system, dependencies
chore	Maintenance, tooling
ci	CI workflow and automation changes
revert	Revert a previous commit

Examples:

fix: resolve null pointer in auth flow
feat(api): add rate limiting endpoint
docs: update README with new commands

Use imperative mood ("add" not "added"). Scope is optional.

Additional validation rules enforced locally and in CI:

• scopes must be lower-case (feat(api): ..., not feat(API): ...)
• subjects must be at least 10 characters long
• commit bodies and footers must be separated from the subject by a blank line when present
• PR commit ranges are validated in CI with commitlint, not only via the local hook

Linearis is opinionated, because its maintainer is

I wish times were better and I wouldn't have to mention it, but they aren't and unfortunately, I do:

This tool is made by friendly people for friendly people. We aim to treat eachother with respect and tolerance. We have zero tolerance for intolerance. This is not open for discussion.

Architecture & Code Patterns

For architecture details, layer invariants, and code patterns, see AGENTS.md. This is also the file AI coding agents use as context when working on the codebase.