> For the complete documentation index, see [llms.txt](https://emeditweb.gitbook.io/pulsar-stellar-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://emeditweb.gitbook.io/pulsar-stellar-sdk/governance/pull-requests.md). # Pull Request Standards Every change lands through a pull request. This page describes what a Pulsar pull request looks like and the checks it passes. The enforceable version is the pull request template in each code repository, which opens automatically when you start a pull request. * [pulsar-core PR template](https://github.com/pulsar-stellar/pulsar-core/blob/main/.github/pull_request_template.md) * [pulsar-app PR template](https://github.com/pulsar-stellar/pulsar-app/blob/main/.github/pull_request_template.md) ## One logical change per pull request A pull request carries one logical change. It branches from `main`, closes an issue with `Closes #NN`, and names any ADR that governs it. A change that mixes unrelated work is split before review. Direct pushes to `main` are rejected; a change reaches `main` only through a pull request. Squash merge keeps one commit per change on `main`, so the pull request title uses the conventional commit format and becomes the squash commit subject. ## The template is a standard, not a form The template asks for the reasoning a reviewer needs, not a checkbox ritual. Leaving a section as unedited placeholder text, or changing behavior without changing tests, sends the pull request back before review. A section that does not apply keeps its heading and says "N/A" with a one-line reason, so a reviewer can tell the difference between "considered and not applicable" and "forgotten". The template walks through: 1. **Summary and core invariant.** What changed, and the single property a reviewer should hold the whole diff against. 2. **Scope and workstream audit.** What is in scope, what is deliberately out, and a map from each requirement to where the diff satisfies it. 3. **Background and boundary context.** The behavior before the change, and which trust or correctness boundary it touches: the indexer HTTP surface, the decode-then-store path, and the SDK validation boundary in `pulsar-app`; the contract state machine and the decoder correctness boundary in `pulsar-core`. 4. **Design and approach.** How the change works, the decisions behind it, and any effect on the response envelope and error catalog, or on an event shape, error variant, or authorization check. 5. **Detailed changes, file by file.** Grouped by sub-stack, one note per file that carries a decision. 6. **Failure-mode analysis.** For each failure path: what triggers it, what the caller sees, and what the operator sees. The indexer logs the cause server-side and returns a generic message, so this section shows that pairing. 7. **Verification and test evidence.** The commands run and their output, the new tests and the single claim each makes, and measured coverage. 8. **Configuration and toolchain reference.** Any env var, pin, or parameter added or changed, checked against `.env.example` or the toolchain pins. 9. **Security, invariants, and data-integrity checklist.** Boxes that a reviewer reads as readiness signals, covering secrets, boundary validation, parameterized SQL, no panic from a request, no error leakage, auth and rate limiting on state-changing endpoints, and scope against `SECURITY.md`. 10. **Files changed.** A short table, with a totals line that reconciles against the diff stat. 11. **Rollout and operations.** What has to happen to ship, any database migration or contract redeploy, backward compatibility, and what an operator watches. ## Checks that must pass CI must be green before review. Run the checks locally first; the pull request's verification section is the evidence that CI will pass. **pulsar-app**, for the sub-stacks the change touches: ```bash # TypeScript (packages/sdk, apps/web) pnpm typecheck pnpm lint pnpm test # Go indexer (indexer/) cd indexer go vet ./... go test -race ./... staticcheck ./... ``` **pulsar-core**: ```bash cargo test cargo fmt --check cargo clippy -- -D warnings cargo llvm-cov --workspace --locked --summary-only scripts/verify-no-panic-apis.sh stellar contract build # when contracts/showcase changed ``` Line coverage stays above 80 percent in `pulsar-app` and above 85 percent in `pulsar-core`. A behavior-carrying change lands with its tests in the same commit. ## The maintainer merge gate A reviewer confirms, independent of what the author wrote, that the pull request branches from `main` and is one logical change, that CI is green, that commits follow the conventional format and pushed history was not rewritten, and that a behavior change is paired with tests. Changes to the indexer HTTP surface, the database layer, and migrations in `pulsar-app`, and to the decoder crate in `pulsar-core`, are reviewed at a higher bar. ## Next See [Contributing](/pulsar-stellar-sdk/governance/contributing.md) for the commit and test rules a pull request is measured against, and the [Security Policy](/pulsar-stellar-sdk/governance/security.md) before you send anything security-sensitive through a pull request. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://emeditweb.gitbook.io/pulsar-stellar-sdk/governance/pull-requests.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.