Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
200 lines (145 loc) · 5.55 KB

CONTRIBUTING.md

File metadata and controls

200 lines (145 loc) · 5.55 KB

Contributing

Setup

pnpm install        # installs deps + sets up husky hooks via "prepare" script
pnpm build          # build the library (tsup → ESM + CJS + .d.ts)
pnpm test           # run unit tests (vitest)

Development Workflow

1. Create a branch

git checkout -b feat/my-feature

2. Make your changes

Edit code in packages/playstacks/src/. Run tests locally:

pnpm test           # unit tests
pnpm lint           # eslint
pnpm typecheck      # tsc --noEmit

3. Add a changeset

Every PR that changes the library must include a changeset. This is how we track what changed and auto-generate changelogs.

pnpm changeset

This prompts you to:

  1. Select the package — pick @satoshai/playstacks
  2. Choose the bump type:
    • patch — bug fixes, docs, internal changes
    • minor — new features, non-breaking additions
    • major — breaking API changes
  3. Write a summary — one-line description of what changed (this goes into the changelog)

It creates a markdown file in .changeset/ like:

.changeset/cool-dogs-fly.md

---
"@satoshai/playstacks": minor
---

Add stx_signMessage wallet method

Commit this file alongside your code changes. One changeset per logical change — if your PR does two unrelated things, add two changesets.

When to skip: Changes that don't affect the published package (CI config, repo docs, test-only changes) don't need a changeset.

4. Commit

Commits must follow Conventional Commits:

type(scope): description
Type When to use
feat New feature
fix Bug fix
docs Documentation only
refactor Code change that neither fixes a bug nor adds a feature
test Adding or updating tests
chore Tooling, deps, CI, build changes

Examples:

git commit -m "feat: add stx_signMessage wallet method"
git commit -m "fix: handle empty post-conditions array"
git commit -m "docs: update fee management section"
git commit -m "chore: bump @stacks/transactions to 7.4.0"

Scope is optional. The commit-msg hook validates this via commitlint — the commit will be rejected if the format is wrong.

5. Push and open a PR

git push -u origin feat/my-feature

Git Hooks

Husky runs these automatically:

Hook Runs What it does
pre-commit Before every commit pnpm lint && pnpm typecheck
pre-push Before every push pnpm test (42 unit tests)
commit-msg On commit Validates conventional commit format via commitlint

If a hook fails, the git operation is blocked. Fix the issue and retry.

Releasing a New Version

Releases are done from main using changesets.

1. Version bump

pnpm changeset version

This consumes all pending .changeset/*.md files and:

  • Bumps version in packages/playstacks/package.json
  • Updates packages/playstacks/CHANGELOG.md with the changeset summaries
  • Deletes the consumed changeset files

Review the changes, then commit:

git add .
git commit -m "chore: version packages"

2. Update root CHANGELOG

The root CHANGELOG.md follows Keep a Changelog format and is maintained manually. Add a new entry with the version, date, and categorized changes:

## [0.2.0] - 2026-03-01

### Added
- `stx_signMessage` wallet method

### Fixed
- Handle empty post-conditions array

Categories: Added, Changed, Fixed, Removed, Deprecated.

3. Build and publish

pnpm build
pnpm changeset publish      # publishes to npm with public access

4. Tag and push

git push && git push --tags

Scripts Reference

Run from the monorepo root:

Script What it does
pnpm build Build the library (tsup → dist/)
pnpm test Run unit tests (vitest)
pnpm test:unit Same as pnpm test
pnpm test:e2e:example-zest Run Zest E2E tests (examples/zest/)
pnpm test:e2e:example-satoshai Run SatoshAI E2E tests (examples/satoshai/)
pnpm test:e2e:test-dapp Run test dApp E2E tests (apps/test-dapp/)
pnpm lint ESLint across all packages and examples
pnpm typecheck TypeScript type checking across all packages
pnpm clean Remove dist/ directories
pnpm changeset Create a new changeset
pnpm changeset version Consume changesets and bump versions
pnpm changeset publish Publish to npm

Project Structure

playstacks/
├── packages/playstacks/     # The published npm package (@satoshai/playstacks)
│   ├── src/                 # Library source code
│   ├── tests/unit/          # Vitest unit tests (42 tests)
│   ├── CHANGELOG.md         # Auto-generated by changesets
│   └── package.json         # version: "0.2.0"
├── apps/test-dapp/          # Test dApp — exercises every wallet method
├── examples/zest/           # Real-world E2E: Zest Protocol (mainnet)
├── examples/satoshai/       # Real-world E2E: SatoshAI login (mainnet)
├── docs/                    # Architecture docs and plans
├── .changeset/              # Pending changesets live here
├── .husky/                  # Git hook scripts
├── CHANGELOG.md             # Root changelog (manual, Keep a Changelog format)
├── eslint.config.js         # ESLint flat config (TS recommended)
├── commitlint.config.js     # Conventional commits enforcement
└── pnpm-workspace.yaml      # Monorepo workspace config