soroban-abacus-flashcards/CONTRIBUTING.md

Contributing to Soroban Abacus Flashcards

Commit Message Guidelines

This project uses Conventional Commits for automated versioning and changelog generation.

Commit Message Format

<type>: <description>

[optional body]

[optional footer(s)]

Types

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, etc)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to our CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit

Examples

feat: add fullscreen support to Memory Quiz game
fix: resolve TypeScript errors across the codebase
docs: update deployment documentation
style: format code with prettier
refactor: extract reusable GameSelector component
perf: optimize abacus rendering performance
test: add unit tests for GameModeContext
build: update dependencies to latest versions
ci: add semantic release workflow
chore: update gitignore for Panda CSS

Breaking Changes

For breaking changes, add BREAKING CHANGE: in the footer or append ! after the type:

feat!: redesign GameMode API with new interface

BREAKING CHANGE: GameMode context now requires explicit player configuration

Automated Releases

This project uses semantic-release for automated versioning:

• feat: Triggers a minor version bump (1.0.0 → 1.1.0)
• 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

# 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 publishing
2. Dual publishing: Package is published to both npm and GitHub Packages simultaneously
3. Manual testing: From packages/abacus-react/, run pnpm release:dry-run
4. Version tags: Package releases are tagged as abacus-react-v1.2.3 (separate from monorepo versions)
5. Authentication: Requires NPM_TOKEN secret for npm and uses GITHUB_TOKEN for GitHub Packages

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
2. Make your changes following conventional commit format
3. Push to GitHub - this triggers deployment to staging
4. Create a PR to main
5. Merge to main triggers:
   • Automated release (if applicable)
   • Production deployment to https://abaci.one
   • Changelog generation

Getting Started

# Install dependencies
pnpm install

# Setup development environment
pnpm setup

# Start development server
pnpm dev

# Run tests
pnpm test

# Build for production
pnpm build