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.
This commit is contained in:
Thomas Hallock
parent
e3db7f4daf
commit
f923b53a44
|
|
@ -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
|
||||
|
|
@ -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`
|
||||
|
|
|
|||
19
README.md
19
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:
|
||||
|
|
|
|||
Loading…
Reference in New Issue