Contributor guide

Thank you for your interest in contributing to the ServiceNow SDK for Go! Whether you're fixing a typo or adding an entire API module, there's a path here sized to what you're trying to do — you don't need to read everything before you ship something.

Pick your path

🚀 I'm new here

Ship your first PR in under an hour — a doc fix, a test, a small bug. No architecture reading required; the dev container gives you a working environment in one click.

Your first PR →

🔧 I'm ready to build

Adding features or fixing real bugs? Follow one request through the codebase, learn the testing rings, and — for a whole new API surface — use the module playbook.

Architecture →

🧭 I want the why

The conventions reference is the seasoned contributor's field guide, and the design decisions explain — in plain language, with ADRs one click deeper — why the SDK is shaped the way it is.

Conventions →

One thing to know up front: this SDK is hand-written but convention-bound. There's no code generator enforcing uniformity — the conventions do that job instead. A change that follows the conventions usually merges quickly; most review friction is structural, and it's all learnable in advance.

What we optimize for

• Consistency over cleverness. Modules are structurally identical on purpose; a reader who learns one has learned them all. Novelty in structure is a cost, even when it's elegant.
• The compiler is our reviewer of first resort. Typed per-verb configurations, sentinel errors, compiled doc samples — wherever possible, wrongness is made uncompilable rather than caught in review.
• Reliability is a feature. Every change carries tests; every API error is typed; nil never propagates silently.
• Docs are part of the change. If a PR alters what users see, it updates what users read — in the same PR.

Ways to contribute

Code is only one lane. Reporting a reproducible bug, improving a doc page, adding an integration test case, or triaging issues all move the project. Look for good first issue or help wanted labels to find a starting point.

Submitting your changes

This section is the source of truth for the contribution workflow (the repository's CONTRIBUTING.md points here). If it's your first time through, Your first PR walks these same steps with a timer running.

1. Branch from main using the type/kebab-description convention that matches your change's commit type, for example fix/tableapi-nil-pointer or docs/error-sentinel-notes.
2. Write Conventional Commits: feat(scope): description, fix: ..., docs: ..., with a BREAKING CHANGE: footer for breaking changes. This isn't just style — release-please parses commit messages to generate the version number and changelog. For the same reason, never edit VERSION or CHANGELOG.md by hand.
3. Verify locally: run gofmt -s -w ., golangci-lint run ./..., and go test ./.... All three must pass before review.
4. Update the documentation: a PR that adds or changes exported API surface must also update the docs site (website/) — or say in the PR description why no docs change is needed. Code samples belong in website/snippets/*.go region markers, never inline, so CI can compile them.
5. Push to your fork and open a Pull Request against main. The PR title must itself be a valid Conventional Commit line (CI lints it, and it becomes the squash commit). Link related issues in the body.

When you change the design itself

Significant design changes follow a lightweight norm: write an ADR under docs/adr/ in the repository, then add (or update) a short design-decision page here that links to it. Why it's built this way explains the norm and indexes the existing decisions.

The project looks forward to your contributions!