Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (97 loc) · 5.47 KB

CONTRIBUTING.md

File metadata and controls

138 lines (97 loc) · 5.47 KB
Raw

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.

There is one exception, for repairing releases whose notes semantic-release failed to render — as happened for 2026.7.0-next.1 … 2026.7.0, when the conventionalcommits preset resolved to a version incompatible with the notes generator's writer. guard-changelog-history in ci-validate.yml lets through a commit whose subject is exactly:

chore(release): backfill changelog notes

and only when that commit changes nothing but CHANGELOG.md and only adds lines to it — a backfill that removes or rewrites an existing line fails the guard. Every other CHANGELOG.md edit stays blocked.

Such a repair must be generated rather than hand-written: re-render the notes for each empty section using the commit range from the compare link already in its heading, and splice in only the body so the heading's original version, date and compare link survive untouched — which is also what keeps the diff additions-only, as the guard requires. GitHub Release bodies are damaged the same way and cannot be fixed by a committed file; a maintainer patches those separately with gh api.

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.