title: Contributing component: flagon permalink: /docs/contributing/ priority: 2

First, thank you for contributing to Apache Flagon!

All Apache Flagon components (UserALE.js, UserALE Browser Extension, Distill, Protobuf schemas, and the Project Website) are maintained in the unified apache/flagon monorepo.

1. Open or Claim an Issue on GitHub

All changes to Apache Flagon should correspond to a GitHub Issue so work can be discussed and tracked transparently.

2. Set Up Your Local Development Environment

Clone the repository and create a topic branch from master:

git clone https://github.com/apache/flagon.git
cd flagon
git checkout -b feat/your-feature-name

Option A: Nix Flake (Recommended)

If you use Nix with flakes enabled, run:

nix develop

This provides Node.js, pnpm, TypeScript, Python 3, uv, buf, and lefthook git hooks automatically.

Option B: Manual Toolchain Setup

  • UserALE (products/userale): Node.js >= 20.x and pnpm >= 10.x
  • Distill (products/distill): Python >= 3.10,< 4.0 and uv
  • Protobuf (proto/): buf CLI

3. Build & Test Your Changes

UserALE.js & Browser Extension (products/userale)

cd products/userale
pnpm install
pnpm build
pnpm --dir packages/flagon-userale test
pnpm format:check
pnpm lint:check

Distill (products/distill)

cd products/distill
uv sync --all-groups
uv run pytest
uv run --group lint ruff check .

Protobuf Schemas (proto/)

buf lint
buf generate

4. Submit a Pull Request on GitHub

  1. Ensure every new source file includes the standard Apache-2.0 license header.
  2. Commit your changes in logical units with pre-commit hooks enabled (do not pass --no-verify).
  3. Open a Pull Request against apache/flagon referencing the issue number (e.g. Closes #123).