Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
233 lines (166 loc) · 8 KB

CONTRIBUTING.md

File metadata and controls

233 lines (166 loc) · 8 KB
Raw

Contributing to GuildPass SDK

Thank you for your interest in contributing to the GuildPass SDK! This is the official TypeScript SDK for the GuildPass protocol.

Table of Contents

Code of Conduct

By participating you agree to our Code of Conduct.

Ways to Contribute

  • Fix bugs in existing service modules
  • Add new service methods with full TypeScript types
  • Write or improve Vitest unit tests
  • Improve TypeDoc documentation comments on public APIs
  • Improve the usage guides in docs/
  • Add new code examples in examples/
  • Fix TypeScript strict mode issues
  • Improve error messages and error types

Finding Issues

  1. Browse issues directly on GitHub:
  2. Comment I'd like to work on this on the GitHub issue you'd like to work on.
  3. Wait for a maintainer to assign it before starting — this avoids duplicate effort.

Development Setup

Prerequisites

  • Node.js 18+
  • pnpm (recommended)

Steps

# 1. Fork and clone
git clone https://github.com/<your-username>/guildpass-sdk.git
cd guildpass-sdk

# 2. Install dependencies
pnpm install

# 3. Build the SDK (tsup)
pnpm build

# 4. Run tests to confirm everything works
pnpm test:run

Project structure

Path Purpose
src/ SDK source code (services, types, client)
src/index.ts Public API entry point
tests/ Vitest unit tests
docs/ Markdown documentation guides
examples/ Usage examples
dist/ Build output (generated, do not edit)

Coding Standards

  • TypeScript only — no plain JavaScript files.
  • No any without a clear comment explaining why.
  • Public APIs must have TypeDoc comments — every exported function, class, and type.
  • Tests required — every new public method must have at least one Vitest unit test.
  • No side effects — the package sets "sideEffects": false. Keep it that way.
  • Minimal dependencies — the SDK has zero runtime dependencies by design. Do not add any without prior discussion with a maintainer.
  • Formatting — run pnpm format (Prettier) before submitting.
  • Linting — run pnpm lint (ESLint) and fix all reported issues.
  • Keep the public API clean — prefer extending existing interfaces over adding new ones.

Test Fixtures

The SDK's test suite uses a set of fixture files to mock API responses. These fixtures are located in the tests/fixtures directory and are organized by service module.

Purpose

The fixtures ensure that the SDK's tests are run against a consistent and predictable set of data that mirrors the real GuildPass backend's API contract. This prevents tests from passing with outdated or incorrect mock data.

Structure

Fixture files are JSON files, with each file representing a specific API endpoint response. The directory structure is as follows:

tests/fixtures/
├───access/
│   ├───check-access-success.json
│   └───...
├───guilds/
│   └───...
├───membership/
│   └───...
└───roles/
    └───...

Each service has its own directory, and within that directory, there are separate files for success and error cases for each endpoint.

Updating Fixtures

When the GuildPass backend API contract changes, the corresponding fixture files must be updated. To do this, follow these steps:

  1. Identify the affected endpoint: Determine which API endpoint has changed and locate the corresponding fixture file in the tests/fixtures directory.
  2. Update the fixture file: Modify the JSON file to reflect the new API response structure.
  3. Run the tests: Run the test suite to ensure that the SDK's response parsing and handling logic is compatible with the new fixture.
  4. Commit the changes: Commit the updated fixture file along with any code changes.

Branching & Commits

  • Branch off main: git checkout -b feat/short-description or fix/short-description
  • Conventional commits:
    • feat: add client.membership.getHistory() method
    • fix: handle 404 response from access.checkAccess()
    • test: add unit tests for roles service
    • docs: add SIWE authentication example
    • chore: upgrade vitest to 2.x
    • refactor: extract HTTP client into shared utility

Submitting a Pull Request

  1. Push your branch to your fork.
  2. Open a PR against Adamantine-Guild/guildpass-sdk on main.
  3. Fill in the PR template completely.
  4. Ensure these pass before submitting:
pnpm typecheck    # Must pass with no errors
pnpm lint         # Fix all reported issues
pnpm test:run     # All tests must pass
pnpm build        # Build must succeed

PR Quality Expectations

  • All new public methods/types have TypeDoc comments.
  • New behaviour is covered by at least one Vitest test.
  • No new runtime dependencies without prior maintainer approval.
  • Public API changes include documentation updates in docs/.
  • Semver impact is noted in the PR description (patch / minor / major).

Review Process

  • A maintainer will review your PR within 5 business days.
  • Address requested changes promptly.
  • Breaking changes (major version) require additional design discussion.
  • Once approved and CI passes, a maintainer merges and releases.

Communication

Public API Changes

We monitor changes to our public API surface closely to prevent accidental breaking changes.

If you modify exported classes, interfaces, or types:

  1. Run pnpm api-report locally to update the API baseline file (api-report/guildpass-sdk.api.md).
  2. Commit the updated guildpass-sdk.api.md file alongside your code changes.
  3. Your pull request will display a diff of the API changes for maintainer review.

Checking semver impact before a release

Maintainers can compare the regenerated API report against the last release tag to decide the correct version bump. This is local tooling only — it is not part of the release GitHub Actions workflow.

# Regenerate api-report/, diff against the latest v*.*.* tag, print semver guidance
pnpm check-api-diff

The script:

  • Runs pnpm build and pnpm api-report:ci to refresh api-report/guildpass-sdk.api.md
  • Loads the baseline from the latest semver release tag (v*.*.*)
  • If no tags exist yet, falls back to the last committed api-report/ on HEAD
  • Classifies each difference:
    • Added export → non-breaking
    • Removed export or changed signature → breaking
  • Recommends a version bump using the project's current stage:
    • Pre-1.0 (0.x.y): breaking → minor, additive → patch
    • Post-1.0: breaking → major, additive → minor
  • Exits with code 1 when breaking changes are detected

Useful flags:

# Skip regeneration when you already ran api-report:ci
pnpm check-api-diff -- --skip-regenerate

# Compare against a specific tag or file (e.g. in tests)
pnpm check-api-diff -- --baseline-tag v0.1.0
pnpm check-api-diff -- --baseline-file /tmp/old.api.md

Before tagging a release, update package.json and add a matching CHANGELOG.md entry so the tag and package version align (see README → Versioning and changelog).