Contributing

This guide explains how to contribute to 3AM in a way that is clear for reviewers and safe for future maintainers.

A strong contribution is easy to review, easy to test, and focused on one concern.

One PR = One Concern

A pull request should solve one thing only.

If you have two concerns, split into two PRs.

Standard workflow

Start from main, create a branch, implement one clear concern, run checks, and open a PR with context.

Project board: 3AM Project Board

Scope rule

Problematic Example (mixed PR, hard review)

feat/navbar-and-hero-and-docs

- fix mobile nav close bug
- redesign hero copy
- rewrite guidelines docs

Recommended Example (split by concern)

PR 1: fix(navbar): close mobile menu after internal navigation
PR 2: docs(guidelines): rewrite lifecycle section with before-after examples
PR 3: feat(hero): update hero copy and CTA labels

Why this works

When each PR has one concern, review is faster, rollback is safer, and regressions are easier to isolate.

Branch naming style

Use lowercase kebab-case with this format:

<type>/<scope>-<short-description>

Problematic Example (weak names)

update
changes
work
fix-stuff

Recommended Example (good names)

feat/hero-add-slide-5
fix/navbar-close-mobile-on-link
docs/rewrite-guidelines-b2
refactor/lazy-media-hydration
test/router-fallback-paths

Commit message style

Use Conventional Commits:

<type>(<scope>): <summary>

Problematic Example (unclear)

update files
fix issue
more changes

Recommended Example (clear)

feat(hero): add fifth hero slide with responsive assets
fix(navbar): close mobile panel after internal navigation
docs(styles): add before-after component styling examples
refactor(lazy-media): extract hydration helper utilities
test(bootloader): cover reduced-motion exit behavior

Pull request style

Use a PR title that matches commit style:

<type>(<scope>): <short summary>

Then use this PR body template:

## What changed

## Why this change was needed

## How it was implemented

## Validation
- bun test
- bun run build
- bun run docs:build

## Screenshots (if UI changed)

Reviewer expectation

A reviewer should understand what changed and why without opening unrelated files.

Required checks before opening PR

bun test
bun run build
bun run docs:build

If bundle size can change:

bun run build:bundle
bun run budget

Related docs

Guidelines

Testing

Performance

Core System

Project links

Repo: 3AM Frontend Repository

Backend: 3AM Backend Repository