Contributing

Omicron is AGPL-3.0-or-later free software. Contributions are welcome, and the bar is mostly about fitting the existing shape rather than about volume.

Before you write code

• Open an issue first for anything beyond a small fix. A short discussion about approach saves rewriting.
• Read Architecture. Most review feedback is a layering rule the contributor had not seen yet.
• Check the roadmap in the repository — a feature may already be planned with a particular design in mind.

The workflow

git clone https://github.com/the-jk-labs/omicron.git
cd omicron
git checkout -b your-change
# … work …
cd apps/backend  && deno task check && deno lint && deno fmt --check && deno task test
cd apps/frontend && pnpm check

Each of these is a CI gate, so anything failing here fails the pull request too. CI runs more besides — dependency audits and a Docker image build.

Then open a pull request describing what changes for the user and why.

The integration suite

One CI gate is not in the list above, because it needs a database:

cd apps/backend
DATABASE_URL=postgres://… deno task test:integration

It asserts on who can see what — drafts, private accounts, suspended authors — across feeds, tag pages, reading lists and the sitemap. Run it if you touched a query, a visibility predicate, or anything in db/repositories/. CI runs it against its own throwaway Postgres either way.

What review looks for

Area	Expectation
Layering	Routes stay thin; no SQL outside db/; no HTTP inside services/
Repositories	Every query is a repository function
Visibility	A listing that reaches another user’s posts applies isPublished, notSuspended, notHidden(viewer) and visibleToViewer(viewer)
Pagination	Cursor-based on (created_at, id), never OFFSET
UI	Bits UI primitives and theme tokens only — no ad-hoc colours
Migrations	Additive within a version; generated SQL committed
Federation	Nothing imported from federation/ when the flag is off
Privacy	No new reader-identifying data. See Writer dashboard
Comments	Explain why, at the density of the surrounding code

Migrations in a pull request

Include the generated SQL from deno task db:generate, and state in the description whether the change is additive. A migration that drops or renames a column needs to be split across releases — see Database and migrations.

UI changes

Screenshots in the PR, light and dark. The theme tokens are ported from the Bits UI docs and both themes are first-class; a change that only looks right in one is not finished.

Documentation

This documentation site lives in a separate repository: the-jk-labs/omicron-docs. A feature that changes operator-visible behaviour should come with a docs PR — or at least an issue there, so the pages do not drift from the software.

Every page here has an Edit this page on GitHub link at the bottom.

Reporting bugs

Include:

• curl localhost:8000/version output,
• your container engine and version,
• whether federation is enabled,
• the relevant logs (docker compose logs --since 30m backend).

Security issues

Report privately through GitHub security advisories, not as a public issue, so a fix can ship before the details are public.

Licensing

By contributing you agree your work is licensed under AGPL-3.0-or-later, the project’s licence. Every source file carries an SPDX header:

// SPDX-License-Identifier: AGPL-3.0-or-later

Keep it on new files. See License and AGPL for what the licence requires of people who deploy modified versions.