GitHub repository conventions

This document defines how you collaborate on Saturn using GitHub. It covers commit and branch conventions, issue and pull request workflows, labeling taxonomy, automation, and pre-commit enforcement.

These conventions exist to make collaboration predictable, scalable, and low-friction. They reduce ambiguity in intent, simplify review and triage, and allow automation to operate reliably as the project grows.

You should follow these rules when opening issues, creating branches, committing changes, or submitting pull requests.

Conceptual model

GitHub acts as Saturn’s shared communication layer. Every commit message, branch name, label, and pull request description communicates intent, scope, and impact to other contributors.

The workflow follows four guiding principles:

Prefer clarity over cleverness
Prefer consistency over personal preference
Use automation to remove human error
Keep the barrier to entry low for new contributors

If intent can be inferred automatically, the workflow enables tools to infer it. If judgment is required, the workflow makes that judgment explicit and visible.

Commits and branches

Saturn uses two complementary standards:

These standards encode intent directly into commit history and branch structure.

Why this matters

Structured commits and branches allow you to:

Understand what changed and why without inspecting diffs
Generate changelogs automatically
Identify breaking changes reliably
Preserve readable history over time

Commit messages

Every commit message must follow the Conventional Commits format:

type(scope): short description

Use concise, imperative descriptions.

Examples:

feat(renderer): add bindless texture support
fix(ecs): prevent dangling entity handles
docs(engine): clarify renderer initialization order

Explicitly mark breaking changes according to the specification. Do not rely on implication.

Branch names

Branch names follow the same intent-driven structure:

type/scope/short-description

Examples:

feat/graphics/shadow-mapping
fix/core/thread-race
docs/architecture/ecs-overview

This structure communicates purpose before a pull request is opened.

Issues and labels

Labels are structured metadata. They encode classification, ownership, urgency, state, and scope in a machine-readable and human-readable form.

Use labels deliberately. Do not overload a single label with multiple meanings.

📦 Packages

Package labels identify which deliverable or artifact is affected. Saturn is a multi-package repository, so package labeling is required whenever possible.

Package: CodexPackage: docsgenPackage: metagenPackage: EditorPackage: TestbedPackage: Saturn Engine

Assign exactly one package label unless the issue genuinely spans multiple packages. If it does, explain why in the issue description.

🧱 Departments

Department labels identify subsystem ownership. They route issues for review, triage, and long-term accountability.

Department: CI/CDDepartment: Core SystemsDepartment: DocumentationDepartment: ECSDepartment: GraphicsDepartment: TestingDepartment: ToolingDepartment: TranslationsDepartment: Dependencies

Department labels answer the question: Who owns this work?

🖥 Platforms

Platform labels indicate where an issue manifests or applies.

Platform: AndroidPlatform: LinuxPlatform: WebPlatform: Windows

If an issue is platform-agnostic, omit platform labels.

🚦 Priority

Priority expresses urgency and impact, not personal preference.

Priority: Critical

Priority: High

Priority: Medium

Priority: Low

Assign priority during triage. Do not guess by default.

📌 Status

Status labels track lifecycle state. Only one status label should be active at a time.

Status: Abandoned

Status: Accepted

Status: Available

Status: Blocked

Status: Completed

Status: In Progress

Status: On Hold

Status: Pending

Status: Refused

Status: Review Needed

Status: Revision Needed

Status: Triaged

Status labels answer the question: What is happening right now?

🧭 Type

Type labels classify the intent of the work.

Type: Bug

Type: Development

Type: Enhancement

Type: Feature

Type: Maintenance

Type: Question

Type labels answer the question: What kind of change is this?

🌱 Contribution-friendly labels

These labels have special meaning on GitHub and are intentionally preserved.

good first issue

help wanted

good first issue identifies curated, newcomer-friendly tasks
help wanted indicates that maintainers actively welcome external contributions

🤖 Automation labels

The following labels are reserved for automation and dependency tooling:

github_actions

dart

Do not remove, rename, or repurpose these labels.

Labeling guidelines

Not every issue requires every label.

Typical minimum set:

One Type
One Status
One Package
Optional: Department, Platform, Priority

Labels are not decoration. Used consistently, they enable large-scale maintenance without manual coordination.

Issue and pull request templates

Use the provided issue and pull request templates whenever possible.

Templates exist to:

Capture required context early
Reduce clarification cycles
Make issues actionable
Keep reviews focused on substance

Templates act as guardrails for new contributors and time-savers for experienced ones.

Automation and dependency management

Dependabot

Saturn uses Dependabot to manage dependency updates for:

vcpkg (C++ dependencies)
pub.dev (Dart and Flutter tooling)

Automated pull requests are labeled accordingly. Review them like any other change. Verify integration and impact before merging.

Claude Code integration

The repository includes a Claude Code integration for code exploration and refactoring assistance.

This tool augments contributor productivity. Treat generated suggestions as untrusted input and review them with the same care as human-written code.

Pre-commit hooks

Saturn uses pre-commit hooks to enforce code quality before commits are created. Hooks prevent common issues from reaching code review or continuous integration.

Purpose

Pre-commit hooks:

Catch formatting issues early
Enforce consistent standards
Reduce CI failures
Lower review friction
Provide automatic guidance for new contributors

Installation

Install the pre-commit framework:

pip install pre-commit

If you use uv, run uv pip install pre-commit instead.

Activation

Install hooks in your local repository:

pre-commit install

Hooks now run automatically before every commit.

Verification

Run all hooks manually to verify installation:

pre-commit run --all-files

Hook categories

The repository defines hooks for:

General file hygiene
Python linting and formatting using Ruff
Markdown, Astro and TypeScript linting using ESLint
C and C++ formatting using Clang-Format

Hooks automatically modify files when possible. Re-stage modified files before committing.

Skipping hooks

Use --no-verify only when absolutely necessary:

git commit --no-verify

Frequent skipping indicates a workflow or configuration issue. Raise it with the team.

Configuration changes

Hooks are defined in .pre-commit-config.yaml. Do not modify this file without discussion. Propose changes through an issue describing the problem and suggested alternative.

The long view

A GitHub repository is a living system. As contributor count increases, structure becomes essential. These conventions keep Saturn approachable, predictable, and scalable.

The goal is not bureaucracy. The goal is to reduce friction so effort goes into building the engine rather than managing process.