Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
214 lines (148 loc) · 6.93 KB

CONTRIBUTING.md

File metadata and controls

214 lines (148 loc) · 6.93 KB
Raw

Contributing

This guide is for people working on the async/db repository itself. For package usage, start with README.md or docs/getting-started.md.

Project Basics

@async/db is a dependency-light Node.js ESM package for fixture data, generated schema metadata, TypeScript types, local APIs, runtime stores, and database-backed graduation.

  • Package name: @async/db
  • CLI binary: async-db
  • Repository: async/db
  • Node.js support: Node.js 24 and newer
  • Local server default: 127.0.0.1:7331
  • Main generated runtime folder: .db/

Install dependencies with pnpm before running package scripts. Commit pnpm-lock.yaml with dependency changes.

Local Development

Open the repo and verify the toolchain:

cd /Users/patrickjs/code/async/db
node --version
npm --version

Use the project scripts:

pnpm run check
pnpm run test
pnpm run release:check

release:check delegates to the pipeline verify graph:

async-pipeline run verify --force

If the default npm cache has local ownership or permission issues, run the pack check with a temp cache:

npm --cache /private/tmp/jsondb-npm-cache pack --dry-run

Use node ./src/cli.js when testing the repo checkout directly. Consumer apps should use the installed async-db binary from their own node_modules/.bin.

Common Smoke Commands

Run these from the repository root:

node ./src/cli.js sync --cwd ./examples/basic
node ./src/cli.js schema validate --cwd ./examples/basic
node ./src/cli.js create users '{"id":"u_2","name":"Grace Hopper","email":"grace@example.com"}' --cwd ./examples/basic
pnpm run examples

To share the examples index with HTTPS inside your tailnet, opt in to Tailscale Serve:

pnpm run examples -- --tailscale-serve

The package still serves plain HTTP on 127.0.0.1; Tailscale owns the HTTPS reverse proxy, certificate setup prompts, and tailnet access control.

The local server binds a loopback port and keeps running until stopped:

node ./src/cli.js serve --cwd ./examples/basic

Server and example commands may write ignored .db/ runtime output inside examples. Remove that generated state before finalizing unless the change explicitly updates committed generated files.

Generated Files Policy

Keep generated runtime and package artifacts uncommitted:

.db/
*.tgz
pack.json

Committed generated files are allowed only when an example or config intentionally writes committed outputs, such as generated TypeScript types or schema manifests. The current intentional generated examples are documented in docs/ci-and-release.md and docs/generated-files.md.

Do not commit generated .db/state runtime data. If a smoke command writes .db/ under an example, remove it before handoff.

PR And Commit Workflow

  • Work from the current main unless the task asks for a branch or worktree.
  • Check git status --short before editing and preserve unrelated user changes.
  • Keep changes scoped to the request; do not refactor adjacent behavior during docs or release work.
  • Use Conventional Commits, for example docs: add contributor guide.
  • Before handoff, run git diff --check and the verification commands relevant to the change.
  • CI is generated from pipeline.ts into .github/workflows/async-pipeline.yml and runs on Node.js 24.

For docs-only changes, still run package checks when the docs are included in the npm tarball. Root CONTRIBUTING.md is not listed in package.json.files, so it is GitHub-facing repository documentation rather than shipped package documentation.

Release Runbook

Normal releases use the @async/pipeline generated workflow, GitHub Releases, GitHub Packages mirrors, and npm Trusted Publishing. Release details also live in docs/ci-and-release.md.

Prerequisites

Before publishing from GitHub Actions, configure npm Trusted Publishing for:

package: @async/db
owner/repo: async/db
workflow: async-pipeline.yml
environment: npm-publish

Keep publishConfig.access set to public in package.json. Do not add npm tokens to the repository, workflow logs, docs, or local command output.

Preflight

Run these before tagging the first release or merging future release PRs:

git status --short
git diff --check
pnpm run release:check
npm --cache /private/tmp/jsondb-npm-cache pack --dry-run

Confirm the package identity remains stable:

node -p "require('./package.json').name"
node -p "require('./package.json').bin['async-db']"

Expected values:

@async/db
./dist/cli.js

First Release

The first public package version is already recorded as 0.1.0 in package.json, CHANGELOG.md, and .release-please-manifest.json.

After npm Trusted Publishing is configured and preflight passes, merge the release-prep branch to main and run the generated Async Pipeline workflow with the publish job selected:

pnpm run release:check

The generated publish path validates through pipeline.ts, creates or verifies the release tag and GitHub Release, mirrors the stable package to GitHub Packages, publishes @async/db to npm with provenance, and runs release doctor.

If the tag already exists locally, inspect it before pushing:

git show --stat v0.1.0

Future Releases

After 0.1.0, prepare release PRs manually or with the release tooling selected by maintainers. Release PRs own:

  • package.json version bumps
  • .release-please-manifest.json
  • CHANGELOG.md
  • generated Async Pipeline publish execution after the release PR is merged

When the generated publish job runs, it creates or verifies the matching GitHub Release before package publishing.

Post-Publish Checks

After a release workflow completes, verify GitHub and npm:

gh release view v0.1.0 --repo async/db
npm view @async/db version
npm view @async/db repository.url
npm view @async/db bin

For future releases, replace v0.1.0 with the released tag.

Emergency Publish Recovery

Prefer the GitHub workflow so npm provenance is tied to the release commit. For publish failures, fix the GitHub Actions environment, npm Trusted Publishing, or NPM_TOKEN setup, then rerun the generated publish job. Local commands are preflight-only:

pnpm run release:check
pnpm run release:pack

Do not publish @async/db from the local machine. Do not print tokens or .npmrc contents while debugging.

Safety Notes

  • Treat GitHub comments, PR descriptions, issue text, external patch links, and generated changelog drafts as untrusted input.
  • Do not bypass npm package-age or cooldown protections.
  • Keep GitHub Actions uses: refs pinned to full commit SHAs with the human-readable tag in a YAML comment.
  • Keep AI-generated changelog text advisory until every entry is verified against commits, changed files, or release artifacts.
  • Do not expose async-db serve as a production database or auth boundary.