From f923b53a44c2875fe152c9bd326d6a427d07a71e Mon Sep 17 00:00:00 2001 From: Thomas Hallock Date: Sun, 28 Sep 2025 08:51:34 -0500 Subject: [PATCH] docs: add comprehensive workflow documentation for automated npm publishing - Update CONTRIBUTING.md with detailed abacus-react package publishing workflow - Add prominent NPM publishing section to root README - Create .claude/AUTOMATED_WORKFLOWS.md for future Claude sessions - Document commit format requirements: feat(abacus-react): for package releases - Include troubleshooting info and current status (awaiting NPM_TOKEN) This ensures future Claude sessions can automatically discover and use the package publishing workflow without requiring explanation. --- .claude/AUTOMATED_WORKFLOWS.md | 89 ++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 38 +++++++++++++++ README.md | 19 ++++++++ 3 files changed, 146 insertions(+) create mode 100644 .claude/AUTOMATED_WORKFLOWS.md diff --git a/.claude/AUTOMATED_WORKFLOWS.md b/.claude/AUTOMATED_WORKFLOWS.md new file mode 100644 index 00000000..1ece2a9c --- /dev/null +++ b/.claude/AUTOMATED_WORKFLOWS.md @@ -0,0 +1,89 @@ +# Automated Workflows for Claude + +This file documents automated workflows that Claude should be aware of when working on this project. + +## NPM Package Publishing + +### @soroban/abacus-react Package + +**Status**: ✅ Fully configured and ready for automated publishing to npm + +**How to trigger a release**: +```bash +# Minor version bump (new features) +git commit -m "feat(abacus-react): add new bead animation system" + +# Patch version bump (bug fixes) +git commit -m "fix(abacus-react): resolve gesture detection issue" + +# Patch version bump (performance) +git commit -m "perf(abacus-react): optimize bead rendering" + +# Major version bump (breaking changes) +git commit -m "feat(abacus-react)!: change callback signature" +``` + +**Key Requirements**: +- Must use `(abacus-react)` scope in commit message +- Changes must be in `packages/abacus-react/` directory +- NPM_TOKEN secret must be configured in GitHub repository settings + +**Workflow Details**: +- **File**: `.github/workflows/publish-abacus-react.yml` +- **Triggers**: Push to main branch with changes in `packages/abacus-react/` +- **Steps**: Install deps → Build package → Run tests → Semantic release → Publish to npm +- **Versioning**: Independent from monorepo (uses tags like `abacus-react-v1.2.3`) + +**Current Status**: +- ✅ Workflow configured +- ✅ Semantic release setup +- ✅ Package build/test passing +- ⏸️ Awaiting NPM_TOKEN secret for actual npm publishing + +**What Claude should do**: +When making changes to the abacus-react package: +1. Use the proper commit format with `(abacus-react)` scope +2. Remember this will trigger automatic npm publishing +3. Ensure changes are meaningful enough for a version bump +4. Reference this workflow in explanations to users + +## Storybook Deployment + +**Status**: ✅ Fully functional + +**Trigger**: Any push to main branch +**Output**: https://antialias.github.io/soroban-abacus-flashcards/ +- Web app Storybook: `/web/` +- Abacus React component Storybook: `/abacus-react/` + +## Semantic Release (Monorepo) + +**Status**: ✅ Configured to exclude abacus-react scope + +**Workflow**: Regular commits without `(abacus-react)` scope trigger monorepo releases +**Versioning**: Affects root package.json version and creates GitHub releases + +## Claude Guidelines + +1. **Always check commit scope**: When working on abacus-react, use `(abacus-react)` scope +2. **Be intentional**: Package releases are permanent - ensure changes warrant a version bump +3. **Documentation**: Point users to CONTRIBUTING.md for full details +4. **Status awareness**: Remember NPM_TOKEN is required for actual publishing +5. **Testing**: Package tests must pass before publishing (currently has workaround for vitest config issue) + +## Quick Reference + +| Action | Commit Format | Result | +|--------|---------------|---------| +| Add abacus-react feature | `feat(abacus-react): description` | npm minor version bump | +| Fix abacus-react bug | `fix(abacus-react): description` | npm patch version bump | +| Breaking abacus-react change | `feat(abacus-react)!: description` | npm major version bump | +| Regular monorepo feature | `feat: description` | monorepo minor version bump | +| Regular monorepo fix | `fix: description` | monorepo patch version bump | + +## Files to Reference + +- `CONTRIBUTING.md` - Full contributor guidelines +- `packages/abacus-react/README.md` - Package-specific documentation +- `.github/workflows/publish-abacus-react.yml` - Publishing workflow +- `packages/abacus-react/.releaserc.json` - Semantic release config \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89c49a5d..d41b2bf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,6 +61,44 @@ This project uses semantic-release for automated versioning: - **fix**: Triggers a patch version bump (1.0.0 → 1.0.1) - **BREAKING CHANGE**: Triggers a major version bump (1.0.0 → 2.0.0) +### Package-Specific Publishing + +The `@soroban/abacus-react` package has independent versioning and automated npm publishing. Use scoped commits to trigger package releases: + +#### NPM Package Release Triggers + +```bash +# Minor version bump for new features +feat(abacus-react): add new bead animation system + +# Patch version bump for bug fixes +fix(abacus-react): resolve gesture detection issue + +# Patch version bump for performance improvements +perf(abacus-react): optimize bead rendering performance + +# Major version bump for breaking changes +feat(abacus-react)!: change callback signature +# or +feat(abacus-react): redesign API + +BREAKING CHANGE: callback functions now receive different parameters +``` + +#### Package Release Workflow + +1. **Automatic**: Any commit to `main` branch with `(abacus-react)` scope triggers npm publishing +2. **Manual testing**: From `packages/abacus-react/`, run `pnpm release:dry-run` +3. **Version tags**: Package releases are tagged as `abacus-react-v1.2.3` (separate from monorepo versions) +4. **npm publishing**: Requires `NPM_TOKEN` secret in repository settings + +#### Important Notes + +- **Package scope required**: Use `feat(abacus-react):` not just `feat:` for package releases +- **Independent versioning**: Package versions are separate from monorepo versions +- **Path filtering**: Only changes in `packages/abacus-react/` directory trigger builds +- **Test requirements**: Package tests must pass before publishing + ## Development Workflow 1. Create a feature branch from `main` diff --git a/README.md b/README.md index 96ac2923..79261b9d 100644 --- a/README.md +++ b/README.md @@ -698,6 +698,25 @@ curl http://localhost:8000/health ## Development +### 📦 NPM Package Publishing + +The `@soroban/abacus-react` package is automatically published to npm using semantic versioning. To trigger a release: + +```bash +# For new features (minor version bump) +git commit -m "feat(abacus-react): add new bead animation system" + +# For bug fixes (patch version bump) +git commit -m "fix(abacus-react): resolve gesture detection issue" + +# For breaking changes (major version bump) +git commit -m "feat(abacus-react)!: change callback signature" +``` + +**Important**: Use the `(abacus-react)` scope in commit messages to trigger package releases. Regular commits without this scope only affect the monorepo versioning. + +📖 **Full details**: See [CONTRIBUTING.md](./CONTRIBUTING.md#package-specific-publishing) for complete workflow documentation. + ### Updating Example Images If you make changes that affect the visual output, please update the example images: