Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
248 lines (181 loc) · 7.69 KB

CONTRIBUTING.md

File metadata and controls

248 lines (181 loc) · 7.69 KB
Raw

Contributing to ghst

This guide is the complete contributor workflow for cloning, installing, running, testing, and developing the project.

Contents

Before You Start

  • For small fixes (typos, docs, focused bug fixes), open a PR directly.
  • For non-trivial features or CLI behavior changes, open or discuss an issue first.
  • Keep changes scoped to a single concern per PR.

Development TL;DR

nvm use
corepack enable
pnpm install
pnpm dev --help
pnpm lint
pnpm run format:check
pnpm typecheck
pnpm test
pnpm build

Environment Requirements

  • Node.js 22.13+, 24.x, or 26.x (.nvmrc defaults to 24; CI validates all three)
  • corepack enabled
  • pnpm 11.x
  • A Ghost development or staging site - don’t run a local development build of ghst against a production Ghost instance with data you care about

Install Dependencies

nvm use
corepack enable
pnpm install

If this is your first time in the repo, verify local tooling:

pnpm lint
pnpm run format:check
pnpm typecheck
pnpm test
pnpm build

Run the CLI Locally

Run directly from TypeScript source:

pnpm dev --help
pnpm dev auth status
pnpm dev post list

Run built output:

pnpm build
node dist/index.js --help

Optional global link:

pnpm link --global
ghst --help

Authentication for Local Development

Interactive:

pnpm dev auth login

Non-interactive:

pnpm dev auth login \
  --non-interactive \
  --url https://your-site.ghost.io \
  --staff-token "{id}:{secret}" \
  --json

Config and site linkage:

  • User config: ~/.config/ghst/config.json
  • Project config: .ghst/config.json
  • Example env: .env.example

Connection resolution order:

  1. --site
  2. --url + --staff-token
  3. GHOST_URL + GHOST_STAFF_ACCESS_TOKEN
  4. .ghst/config.json
  5. active site in user config

Project Layout

  • Entrypoint: src/index.ts
  • Commands: src/commands/*
  • Core libraries: src/lib/*
  • Validation schemas: src/schemas/*
  • MCP server/tools: src/mcp/*
  • Tests: tests/*
  • Ghost fixture scripts: scripts/check-ghost-fixtures.ts, scripts/capture-ghost-fixtures.ts
  • CI workflows: .github/workflows/*

Development Workflow

  1. Create a branch from updated main:
git switch -c <your-branch-name>
  1. Make the smallest change that solves one problem.
  2. Add or update tests with code changes.
  3. Run full validation locally.
  4. Push and open a PR.

Tests and Validation

Run the same checks as CI:

pnpm lint
pnpm run format:check
pnpm typecheck
pnpm test
pnpm build

Useful variants:

pnpm test:watch
pnpm lint:fix
pnpm format
pnpm format:check

CI reference:

  • Workflow: .github/workflows/ci.yml
  • Node: 22, 24, 26
  • Package manager: pnpm 11.x

Ghost Fixture Workflow

When changing behavior that depends on Ghost Admin API fixture mocks:

  1. Run the offline fixture contract check:
pnpm fixtures:ghost:check

Important notes:

  • Fixture-backed tests use committed static JSON only.
  • pnpm fixtures:ghost:check is fully offline and should be deterministic.
  • pnpm fixtures:ghost:capture is an optional lightweight local snapshot tool for manual inspection only; it is not part of the normal validation workflow.
  • Fixture details are documented in tests/fixtures/ghost-admin/README.md.

Coding Guidelines

  • Keep command handlers thin; move behavior to src/lib.
  • Validate command input with Zod before network calls.
  • Map API/validation failures to ExitCode in src/lib/errors.ts.
  • Preserve CLI contract shape: ghst <resource> <action>.
  • Do not introduce breaking CLI/interface changes without updating docs and tests.
  • Keep changes focused and avoid unrelated refactors in the same PR.

Documentation Updates

  • Update docs whenever command behavior, flags, output, or config behavior changes.
  • At minimum, keep README.md and this file in sync with the code.

Submitting a Pull Request

  1. Ensure your branch is current with main.
  2. Ensure all local checks pass:
pnpm lint && pnpm run format:check && pnpm typecheck && pnpm test && pnpm build
  1. Push your branch and open a PR against main.
  2. In your PR description, include what changed, why it changed, how you tested it, and any follow-up work.

PR expectations:

  • Include tests for behavior changes.
  • Keep PR scope aligned with the issue/intent.
  • Respond to review feedback with follow-up commits.

Getting Help

  • Open an issue for bugs, regression reports, and feature requests.
  • Include reproduction steps, expected behavior, actual behavior, and environment details.
  • For implementation questions, include the command(s), flags, and sample output/error.

Contributor License Agreement

By contributing your code to Ghost you grant the Ghost Foundation a non-exclusive, irrevocable, worldwide, royalty-free, sublicenseable, transferable license under all of Your relevant intellectual property rights (including copyright, patent, and any other rights), to use, copy, prepare derivative works of, distribute and publicly perform and display the Contributions on any licensing terms, including without limitation: (a) open source licenses like the MIT license; and (b) binary, proprietary, or commercial licenses. Except for the licenses granted herein, You reserve all right, title, and interest in and to the Contribution.

You confirm that you are able to grant us these rights. You represent that You are legally entitled to grant the above license. If Your employer has rights to intellectual property that You create, You represent that You have received permission to make the Contributions on behalf of that employer, or that Your employer has waived such rights for the Contributions.

You represent that the Contributions are Your original works of authorship, and to Your knowledge, no other person claims, or has the right to claim, any right in any invention or patent related to the Contributions. You also represent that You are not legally obligated, whether by entering into an agreement or otherwise, in any way that conflicts with the terms of this license.

The Ghost Foundation acknowledges that, except as explicitly described in this Agreement, any Contribution which you provide is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

Releases

  • Package: @tryghost/ghst
  • Automatic: .github/workflows/release.yml runs every Monday at 15:00 UTC and publishes only when there are commits since the last release tag (vX.Y.Z).
  • Manual: run the Release GitHub Actions workflow with workflow_dispatch; set force=true to publish even with no new commits.
  • Versioning: if all commits since the last release tag are by Renovate (renovate[bot]), the workflow uses patch; otherwise it uses minor.
  • Prerequisites: npm trusted publishing must be configured for this repository/workflow.