golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests 1 Actions 1 Packages Projects Releases Wiki Activity

docs: add CONTRIBUTING.md with project guidelines

Browse Source 
Based on PR #222 by @davesienkowski with minor edits.

Co-Authored-By: davesienkowski <davesienkowski@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-22 15:02:02 -06:00
parent 707d4b47b0
commit c313f78f6a
1 changed files with 219 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
CONTRIBUTING.md
View File

@@ -2,41 +2,55 @@
No enterprise theater. Ship useful code.
---
## Philosophy
GSD optimizes for **solo developer + Claude workflow**. The release process follows the same principle: complexity lives in automation, not your workflow.
**What this means:**
- No sprint ceremonies or release committees
- No multi-week stabilization branches
- Checkpoints before risky changes, not bureaucratic gates
- Ship when ready, batch when sensible
---
## Branch Strategy
Two branches. That's it.
```
main ════════════════════════════════════════════►
▲ ▲ ▲ ▲
│ │ │ │
v1.9.0 v1.9.1 v1.10.0 v2.0.0
│ │ │
hotfix batched minor
fixes features
```
### `main`
Production. Always installable via `npx get-shit-done-cc`.
- Must pass CI (catches Windows/cross-platform issues)
- Protected from force pushes
| Rule | Why |
|------|-----|
| No direct commits | Forces checkpoint thinking |
| PRs required | Creates revert points |
| Must pass CI | Catches Windows/path issues |
### Who Can Commit Directly to Main
### Feature Work
| Role | Direct commits | Branch + PR |
|------|----------------|-------------|
| Maintainers | Any change | Never required |
| Contributors | Typo/doc fixes only | All code changes |
**Why no PRs for maintainers?** Self-reviewed PRs are ceremony without value. CI still runs on push. For risky features, use pre-release tags instead.
### Feature Branches (Contributors)
Branch → PR → Merge. No `develop` branch. No release branches.
```bash
# Start work
git checkout -b feat/model-profiles
# or fix/windows-paths, docs/examples
# or fix/windows-paths
# or docs/checkpoint-examples
# Ship it
git push origin feat/model-profiles
# Open PR, get review, merge
```
@@ -45,19 +59,41 @@ git push origin feat/model-profiles
- `feat/description` — New capability
- `fix/description` — Bug fix
- `docs/description` — Documentation only
- `refactor/description` — Internal changes
- `refactor/description` — Internal changes, no behavior change
- `hotfix/version-description` — Emergency production fix
---
## When to Branch vs. Direct Commit
**Use a branch when:**
- Adding new commands or workflows
- Changing core behavior (orchestrator, context loading)
- Touching multiple files
- You'd want a clean revert point
**Direct commit to main (maintainers only):**
- Typo fixes
- README updates
- Single-line bug fixes with obvious correctness
---
## Commits
Use conventional commits.
Use conventional commits. Claude already does this.
```
feat(checkpoints): add rollback capability
fix(install): use absolute paths on Windows (#207)
docs(readme): update installation instructions
refactor(orchestrator): extract context loading
chore: remove old planning files
revert: remove codebase intelligence system
```
**Format:** `type(scope): description`
| Type | Use |
|------|-----|
| `feat` | New feature |
@@ -67,42 +103,114 @@ refactor(orchestrator): extract context loading
| `chore` | Maintenance, dependencies |
| `revert` | Undoing previous commit |
## Releases
---
### Tag Strategy
## Releases & Tags
### Tag Sparingly
**Current problem:** 131 tags in one month. Too noisy.
**New rule:** Tag stable milestones, not every commit.
| Change Type | Tag? | Version Bump |
|-------------|------|--------------|
| Breaking change | Yes | MAJOR (2.0.0) |
| New feature | Yes | MINOR (1.10.0) |
| Bug fix | Batch weekly | PATCH (1.9.x) |
| Bug fix | Batch | PATCH (1.9.x) |
| Documentation | No | — |
| Refactor | No | — |
### Version Cadence
- **Minor releases (1.X.0):** When features are ready. No fixed schedule.
- **Patch releases (1.9.X):** Batch fixes weekly, or immediately for critical bugs.
- **Major releases (X.0.0):** Breaking changes only. Rare.
### Pre-release Tags for Risky Features
For experimental features, use pre-release tags:
The codebase intelligence system added 3,065 lines and a 21MB dependency. It got reverted. Pre-release tags prevent this:
```bash
npm version prerelease --preid=alpha # v1.10.0-alpha.0
git push origin main --tags
# Experimental feature
git tag -a v1.10.0-alpha.1 -m "Alpha: experimental codebase intelligence"
# After testing
git tag -a v1.10.0-beta.1 -m "Beta: codebase intelligence stabilized"
# Ready for production
git tag -a v1.10.0 -m "Release: codebase intelligence"
```
Users opt-in: `npm install get-shit-done-cc@1.10.0-alpha.0`
Users opt-in: `npm install get-shit-done-cc@1.10.0-alpha.1`
If it doesn't work out, delete the tag. No messy public revert.
**If it doesn't work out:** Delete pre-release tags, no messy public revert on main.
### Creating a Release
Run `/gsd-publish-version` which walks you through:
1. Changelog generation from commits
2. Version bump
3. Push to GitHub
```bash
# Update version
npm version minor # or patch, or major
GitHub Actions automatically:
- Creates the GitHub Release from CHANGELOG.md
- Publishes to npm
# Update CHANGELOG.md (already follows Keep a Changelog format)
## Pull Request Guidelines (Contributors)
# Commit
git add package.json CHANGELOG.md
git commit -m "chore: release v1.10.0"
# Tag
git tag -a v1.10.0 -m "Release v1.10.0"
git push origin main --tags
# Publish
npm publish
```
### GitHub Releases
Create formal releases for minor+ versions. Copy the CHANGELOG section.
```
Go to: github.com/glittercowboy/get-shit-done/releases/new
Select tag: v1.10.0
Title: v1.10.0
Description: [paste from CHANGELOG.md]
```
---
## Large Changes
If a feature touches >500 lines or adds dependencies, use a branch and PR. This creates a review point before the change lands on main.
---
## Hotfixes
Production broken? Skip the normal flow.
```bash
# Branch from main
git checkout main
git checkout -b hotfix/1.9.4-windows-crash
# Fix it
# ... make changes ...
# Ship immediately
git commit -m "fix(install): handle Windows UNC paths"
git push origin hotfix/1.9.4-windows-crash
# PR → merge → tag
npm version patch
git tag -a v1.9.5 -m "Hotfix: Windows UNC paths"
git push origin main --tags
npm publish
```
---
## Pull Request Guidelines
### Title
@@ -114,47 +222,110 @@ fix(install): use absolute paths on Windows
### Description
- **What:** One sentence describing the change
- **Why:** One sentence explaining the need
- **Testing:** How you verified it works
- **Breaking Changes:** List any, or "None"
```markdown
## What
### Checklist
[One sentence: what does this PR do?]
- [ ] Follows GSD style (no enterprise patterns)
## Why
[One sentence: why is this change needed?]
## Testing
[How did you verify it works?]
## Breaking Changes
[List any, or "None"]
```
### Review Checklist
- [ ] Follows GSD style (no enterprise patterns, no filler)
- [ ] Updates CHANGELOG.md for user-facing changes
- [ ] No unnecessary dependencies
- [ ] Works on Windows (test backslash paths)
- [ ] Doesn't add unnecessary dependencies
- [ ] Works on Windows (test paths with backslashes)
---
## What NOT to Do
**Enterprise patterns (banned):**
- Story points, sprint ceremonies
- RACI matrices, release committees
- Multi-week stabilization branches
Borrowed from GSD-STYLE.md:
**Vague commits (banned):**
**Enterprise Patterns (Banned):**
- Story points
- Sprint ceremonies
- RACI matrices
- Release committees
- Multi-week stabilization branches
- Change advisory boards
**Temporal Language (Banned in Code/Docs):**
- "We changed X to Y"
- "Previously"
- "No longer"
- "Instead of"
Exception: CHANGELOG.md, MIGRATION.md, git commits
**Vague Contributions (Banned):**
```
# Bad
# BAD
"Improve performance"
"Fix bugs"
"Update documentation"
# Good
# GOOD
"Reduce orchestrator context load from 12KB to 4KB"
"Fix Windows path handling in hook commands (#207)"
"Add checkpoint rollback examples to README"
```
## Development Setup
---
## Quick Reference
| I want to... | Do this |
|--------------|---------|
| Add a feature | Branch `feat/x` → PR → merge |
| Fix a bug | Branch `fix/x` → PR → merge |
| Fix production NOW | Branch `hotfix/version-x` → PR → merge → tag |
| Release features | `npm version minor` → tag → publish |
| Release fixes | Batch weekly, or `npm version patch` for critical |
| Try experimental feature | Tag as `v1.X.0-alpha.1` |
| Revert a mistake | `git revert` → PR → merge |
---
## Setting Up Development
```bash
# Clone
git clone https://github.com/glittercowboy/get-shit-done.git
cd get-shit-done
# Install
npm install
# Test locally
npm link
npx get-shit-done-cc --version
npx get-shit-done-cc
# Run tests
npm test
```
---
## Getting Help
- **Issues:** Bug reports, feature requests
- **Discussions:** Questions, ideas
- **Discussions:** Questions, ideas, show & tell
- **Discord:** [Link if exists]
---
*"The complexity is in the system, not in your workflow."*
— TÂCHES