> 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/contributing.md). # Contributing This page is the public summary of how to contribute to the Pulsar Stellar toolkit. The enforceable rules live in each repository's `CONTRIBUTING.md`, and where this page and a repository differ, the repository wins. * [pulsar-core CONTRIBUTING](https://github.com/pulsar-stellar/pulsar-core/blob/main/CONTRIBUTING.md) * [pulsar-app CONTRIBUTING](https://github.com/pulsar-stellar/pulsar-app/blob/main/CONTRIBUTING.md) * [pulsar-docs CONTRIBUTING](https://github.com/pulsar-stellar/pulsar-docs/blob/main/CONTRIBUTING.md) ## How this project is built The initial scaffolding and much of the ongoing implementation is written with AI assistance under human review. Every commit is authored, reviewed, and merged by a human maintainer. Design decisions, architecture choices, and merge judgments are human. You do not have to disclose whether AI tools helped you write a contribution. You do have to pass review, tests, and the discipline rules below. ## Work starts from an issue Substantive work is tracked with a GitHub issue opened before the work starts. The issue carries the scope, the acceptance criteria, and references to any ADR or specification section that governs it. The pull request closes it with `Closes #NN` in the body. This applies to maintainer work as much as to outside contributions. An issue written after the fact records what was done. One written before it is a chance to disagree about scope while disagreeing is still cheap. ## Commit rules These are enforced, not stylistic preferences. * **One commit per logical unit.** One SDK method, one HTTP handler, one contract function, one component, one type file, one test block. A change that must compile together is one commit. * **Never `git add .`** Stage exact paths, so build output, environment files, and key material never enter history by accident. * **Push after every commit.** Do not batch local commits. If a push fails, stop and resolve it. * **Never rewrite pushed history.** Fix forward with a follow-up commit. * **Conventional commit format:** `type(scope): description`. Types are `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`. The description is imperative, lowercase, with no trailing period, under 72 characters. ## Test discipline * Every behavior-carrying change is paired with tests. A function that encodes a decision the framework, SDK, or contract does not already make is behavior-carrying. * Every SDK public method has a happy path, one network-failure path, and one validation-failure path. * Every indexer handler has a success case, a malformed-input case, and a not-found case. * Every public contract function has a happy path and at least one failure path, and every error variant has a test that triggers it. * Assert exact shapes, never partial matches. Name a test for the single claim it makes. * No test theater. Tests that assert only "did not throw", tests that mock the code under test, and trivially true assertions are rejected in review. * Line coverage stays above 80 percent in `pulsar-app` and above 85 percent in `pulsar-core`. ## Code rules in brief The full rules are per sub-stack in each repository. The shape of them: * **TypeScript (SDK and web).** `strict` on, no `any`, no `@ts-ignore` without an ADR. Every value crossing a boundary is validated with a Zod schema before use. Errors are `PulsarError` or a subclass. No floating promises, no non-null assertions in shipped code. * **Go (indexer).** Every error is wrapped with `%w` and carries context. No `panic` in request handling. Every blocking function takes `ctx context.Context` first. Every SQL query is parameterized. Contract event data is untrusted input, validated before insert. * **Rust (contract and decoder).** No `unwrap`, `expect`, or `panic!` in production code. No floats; amounts are `i128`. Every state-changing function calls `require_auth` before any caller-dependent read or write. The decoder returns an error variant on malformed input rather than panicking. * **React and Next.js (web).** App Router only. No inline styles; Tailwind and shadcn/ui only. No secret in a `NEXT_PUBLIC_` variable. * **Everywhere.** No stubs or `TODO` placeholders in shipped commits. Every env var referenced in code appears in `.env.example`. Secrets never enter the repository. ## Writing rules No em dashes anywhere. Avoid "seamlessly", "robust", "powerful", "leverage", "unlock", "cutting-edge", "revolutionize", "delve into", "elevate", and "empower" used figuratively. Prefer concrete verbs and specific nouns. Numbers come from measured data, and a number that is a target is labeled a target. ## Verify an external API before writing against it When the behavior of an external API is uncertain, check its current documentation or its types before writing code. This applies to `@stellar/stellar-sdk`, `github.com/stellar/go`, `soroban-sdk`, and Soroban RPC in particular, where method names and response shapes have moved between versions. ## Next Read the [Pull Request Standards](/pulsar-stellar-sdk/governance/pull-requests.md) before you open a pull request, and the [Security Policy](/pulsar-stellar-sdk/governance/security.md) before you report anything security-sensitive. --- # 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/contributing.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.