tomevault-io Git Workflow
Manages branching strategy and semantic versioning with Changesets.
Branch Strategy
main ← stable releases (triggers npm publish)
↑
develop ← integration branch (PRs go here)
↑
feature/* ← feature branches
fix/* ← bugfix branches
Workflow Steps
1. Starting New Work
# Always start from develop
git checkout develop
git pull origin develop
# Create feature branch
git checkout -b feature/<name>
# or
git checkout -b fix/<name>
2. Recording Changes
After completing work, record the change for versioning:
pnpm changeset
Select change type:
patch: Bug fixes, minor changes (0.0.X)minor: New features, backwards compatible (0.X.0)major: Breaking changes (X.0.0)
Write a clear description of what changed.
3. Creating PR to develop
git add -A
git commit -m "<type>: <description>"
git push -u origin <branch-name>
# Create PR (IMPORTANT: unset GITHUB_TOKEN to use gh CLI's keyring token)
unset GITHUB_TOKEN && gh pr create --base develop --title "<type>: <description>" --body "..."
CRITICAL: If GITHUB_TOKEN env var is set (e.g., by claudetree), it may lack PR creation permissions. Always use unset GITHUB_TOKEN && gh pr create ... to ensure gh CLI uses the keyring token with proper scopes.
4. Release to main
When develop is stable:
- Create PR from
developtomain - Merge triggers GitHub Action
- Action creates "Release PR" with:
- Updated CHANGELOG.md
- Bumped versions
- Merge Release PR to publish to npm
Commit Message Format
<type>(<scope>): <subject>
<body>
Types:
feat: New featurefix: Bug fixdocs: Documentationrefactor: Code refactoringtest: Testschore: Maintenance
Commands Reference
# Check current branch
git branch --show-current
# View changeset status
pnpm changeset status
# Preview version changes
pnpm changeset version --dry-run
# Build and publish (CI does this)
pnpm release
Rules
- Never commit directly to
main - Always create changeset for user-facing changes
- Keep PRs focused and small
- Ensure tests pass before merging
Converted and distributed by TomeVault — claim your Tome and manage your conversions.