happyview
A lexicon-driven AppView for ATProto. happyview.dev
backfill firehose jetstream atproto appview oauth lexicon
Star
Fork
Watch
happyview CONTRIBUTING.md
5.0 kB · 89 lines
Markdown
at beta

Contributing to HappyView #

Thanks for helping out! This guide covers what a pull request needs to get merged.

Open pull requests against beta #

Work lands on beta first, and main is updated from beta when a release is cut. alpha carries the next major line, so target it only when a change belongs to that line rather than to the current one.

GitHub defaults new PRs to main, so change the base dropdown to beta when you open one. To start from the right place:

git remote add upstream https://github.com/gamesgamesgamesgamesgames/happyview.git
git fetch upstream
git switch -c fix/my-change upstream/beta

If your branch was started from main, rebase it onto beta:

git rebase --onto upstream/beta upstream/main fix/my-change

Sign off your commits #

Every commit needs a Signed-off-by line certifying the Developer Certificate of Origin. The DCO check is required, so a PR can't be merged without it.

Add it with -s:

git commit -s -m "fix: handle empty lexicon lists"

Git has no setting to sign off automatically, but an alias saves typing: git config alias.cs "commit -s".

If the DCO check fails #

Either sign off the existing commits and force-push:

git rebase --signoff upstream/beta
git push --force-with-lease

or, if you'd rather not rewrite history, push one more signed-off commit. Its sign-off covers the earlier commits in the PR:

git commit --allow-empty -s -m "chore: sign off previous commits"
git push

Commit messages #

Releases are generated by semantic-release, so commit messages follow Conventional Commits: fix:, feat:, docs:, test:, ci:, chore:, and so on. Use feat!: or a BREAKING CHANGE: footer for breaking changes.

Local setup #

Point git at the tracked hooks once per clone:

git config core.hooksPath .githooks
  • pre-commit runs cargo fmt --check and cargo clippy over the lib and bins.
  • pre-push runs cargo clippy --all-targets, which also covers test code.

What CI checks #

These checks must pass before merging:

Check Run it locally
lint cargo fmt -- --check and cargo clippy --workspace --all-targets -- -D warnings
unit-tests cargo test --lib and cargo test --workspace --exclude happyview
e2e-tests cargo test --tests with TEST_DATABASE_URL pointing at a Postgres database (docker compose -f docker-compose.test.yml up -d starts one on port 5433)
frontend npm ci && npm run build in web/
test-* (SDK packages) bun install, then bun run --filter '<package>' build, typecheck, and test
DCO See Sign off your commits

The coverage job also runs on server changes. It reruns the Rust suites under cargo-llvm-cov, writes a summary to the job page, reports to Coveralls, and uploads the LCOV and HTML reports as the coverage artifact. It doesn't block merging. To get the same report locally, install the tool once with cargo install cargo-llvm-cov and rustup component add llvm-tools. Then run cargo llvm-cov --workspace --open with TEST_DATABASE_URL set as for e2e-tests.

Jobs only run when the files they cover change, so a docs-only PR skips the Rust and frontend checks.

  • First-time contributors need a maintainer to approve CI before it runs on your PR. Nothing is wrong if checks show as waiting.
  • audit fails when a new RustSec advisory affects a dependency. That usually comes from the base branch rather than your change; a maintainer will handle it.
  • PR builds: when your PR touches the server, CI builds Docker images and binaries, and a bot comments with docker pull ghcr.io/gamesgamesgamesgamesgames/happyview:pr-<number> so reviewers can try it.

Code of conduct #

Participation in this project is covered by the Code of Conduct.