Pull Request Process

Submit high-quality pull requests that get merged quickly.

This guide walks you through the entire pull request process, from preparation to merge.

Before you open the PR

• The change is scoped to one logical unit (one fix, one feature, one docs page set).
• Tests pass locally: mix test (backend) or npm run test && npm run lint (frontend) or npm run astro -- check (docs).
• Formatting is clean: mix format, or npx prettier . --write.
• Commit messages follow the <type>: summary convention; fixups are squashed.
• Docs are updated if behavior changed.

Opening the PR

Target the repository’s default branch (main) unless a maintainer tells you otherwise. Use a descriptive title in the same conventional format:

fix: correct token holder pagination cursor

PR description template

## What

Corrects the next_page_params cursor returned by /api/v2/tokens/{hash}/holders.

Closes #123.

## How to test

1. Start the stack with docker compose up
2. curl "localhost:4000/api/v2/tokens/{hash}/holders" twice, appending
   next_page_params the second time
3. Confirm page 2 has no overlap with page 1

## Screenshots

(UI changes only)

Fill in every section. “How to test” is the single biggest predictor of review speed — reviewers verify, they don’t just read.

During review

• Respond to every comment, even with “done in abc1234”. Silent pushes make reviewers re-read the whole diff.
• Push fixup commits during review; squash only when the PR is approved.
• Don’t force-push mid-review unless asked — it breaks comment threads.
• Disagree respectfully. If you think a suggestion is wrong, say so with reasoning. Reviewers are fallible too.
• Re-request review after addressing feedback so the PR doesn’t stall.

CI requirements

All checks must be green before merge:

A red CI run is your job to fix — if a failure looks unrelated to your change, rebase on the latest default branch; if it persists, flag it in the PR.

Merge policy

• At least one maintainer approval.
• Squash-merge is the default; keep the final commit message clean and conventional.
• The PR author deletes the branch after merge.

After merge

• Verify the change on xdcscan.io (or the relevant staging environment) once deployed.
• Close any issues the PR resolved if Closes #... didn’t do it automatically.
• Update the docs if you punted on it during review — do it now, in a follow-up PR.

Common reasons PRs stall

1. Too big. Split it. Reviewers triage by size.
2. No test plan. Add the “How to test” section.
3. Unrelated changes mixed in. Move them to a separate PR.
4. Formatting noise. Revert files where your editor reflowed untouched code.
5. Silent author. If you’re blocked, say so in a comment — someone will unstick you.