asepharyana
e513cddd68
Transform hub-guide from a single-skill Hub monorepo guide into a comprehensive programming best-practice plugin covering all situations. Skills (26): - Core: engineering-principles, clean-code, clean-architecture, design-patterns, testing, error-handling, security, api-design, git-workflow, documentation, logging-observability, performance - Languages: typescript, python, rust, go - Frameworks: react-frontend, elysiajs, hono-backend, drizzle-database, nextjs - Infrastructure: docker, ci-cd, monitoring - Monorepo: monorepo, hub-guide (existing) Hooks: - SessionStart: auto-detect project type and activate relevant skills - PreToolUse (Write|Edit): inject language-specific rules per file type Reference files for deep dives: - clean-architecture/references/solid.md (SOLID + component principles) - design-patterns/references/catalog.md (full GoF catalog with examples) - testing/references/mocks.md (test double taxonomy) Restructure plugin to modern skills/ directory format.
133 lines
4.3 KiB
Markdown
133 lines
4.3 KiB
Markdown
---
|
|
name: git-workflow
|
|
description: Git workflow best practices — commit conventions, branching strategies, PR conventions, rebase vs merge, and code review. Use when writing commit messages, reviewing PRs, planning branching strategy, or whenever the user mentions "commit," "branch," "pull request," "PR," "merge," "rebase," "squash," "git flow," "trunk-based," "conventional commit," or "code review."
|
|
---
|
|
|
|
# Git Workflow
|
|
|
|
## Commit Message Convention
|
|
|
|
Format: `<type>(<scope>): <description>`
|
|
|
|
```
|
|
feat(auth): add google oauth sign-in
|
|
fix(billing): handle null currency in invoice
|
|
chore(deps): update typescript to 5.5
|
|
docs(api): document rate-limit headers
|
|
refactor(orders): extract payment validation
|
|
test(users): add unit tests for CreateUser
|
|
ci(deploy): split build and push steps
|
|
perf(db): add index on orders.created_at
|
|
style(ui): fix button alignment
|
|
```
|
|
|
|
**Rules:**
|
|
- Type is lowercase. No period at the end.
|
|
- Scope is required — the affected module/context.
|
|
- Imperative mood ("add" not "added" or "adds").
|
|
- Subject under 72 chars.
|
|
- Body wraps at 72 chars. Explains *why* (not *what*).
|
|
- Footer for breaking changes: `BREAKING CHANGE: ...`
|
|
- Footer for co-authors: `Co-Authored-By: Name <email>`
|
|
|
|
## Branching Strategy
|
|
|
|
### Trunk-Based (preferred for CI/CD)
|
|
```
|
|
main ← feature branches
|
|
```
|
|
- Short-lived feature branches (1-2 days max).
|
|
- PR → auto-merge to main after CI passes.
|
|
- Deploy from main. Hotfix = branch from main → merge back.
|
|
|
|
### GitHub Flow
|
|
```
|
|
main → feature/xyz → PR → main
|
|
main → fix/xyz → PR → main
|
|
main → chore/xyz → PR → main
|
|
```
|
|
|
|
### Git Flow (for release-based projects)
|
|
```
|
|
main → develop → feature/xyz → PR → develop
|
|
→ release/v1.2 → main + develop
|
|
→ hotfix/v1.2.1 → main + develop
|
|
```
|
|
|
|
**Choose:**
|
|
- **Trunk-based** — if you deploy multiple times a day (SaaS, web apps).
|
|
- **Git Flow** — if you version releases (libraries, mobile apps, on-prem).
|
|
|
|
## PR Conventions
|
|
|
|
### Title
|
|
Same as commit convention: `feat(scope): description`
|
|
|
|
### Description Template
|
|
```
|
|
## What
|
|
Brief description of the change.
|
|
|
|
## Why
|
|
Problem being solved. Link to issue/ticket.
|
|
|
|
## How
|
|
High-level approach — architecture decisions, trade-offs.
|
|
|
|
## Testing
|
|
- [ ] Unit tests added/passed
|
|
- [ ] Integration tests added/passed
|
|
- [ ] Manual test steps
|
|
|
|
## Screenshots (if UI change)
|
|
...
|
|
|
|
## Checklist
|
|
- [ ] Lint passes
|
|
- [ ] Tests pass
|
|
- [ ] Docs updated
|
|
- [ ] Breaking changes documented
|
|
```
|
|
|
|
### PR Size
|
|
- **Target: <200 lines changed.** Large PRs get less thorough reviews.
|
|
- If >500 lines, split into logical chunks or mark as "stacked PR."
|
|
- One logical change per PR. Don't mix refactors with features.
|
|
|
|
## Code Review
|
|
|
|
### Reviewer Checklist
|
|
1. [ ] Does the solution match the PR description?
|
|
2. [ ] Any edge cases unhandled? (empty state, errors, concurrency)
|
|
3. [ ] Tests cover happy path + error paths + edge cases?
|
|
4. [ ] No dead code, commented-out code, magic numbers?
|
|
5. [ ] Dependencies are necessary (no scope creep)?
|
|
6. [ ] Error handling appropriate (not silent, not leaky)?
|
|
7. [ ] Security: input validated? Auth checked? No secrets?
|
|
|
|
### Review Etiquette
|
|
- **Be specific** — "Line 42: this query is N+1, use `JOIN`" not "this is slow"
|
|
- **Ask, don't demand** — "Should this be a named constant?" not "Make this a constant"
|
|
- **Approve quickly for trivial changes** — don't block for style nits
|
|
- **Distinguish blocking vs nit** — explicitly label `nit:` or `blocking:`
|
|
- **Respond to reviews** — every comment gets a reply or action
|
|
|
|
## Merging Strategy
|
|
|
|
| Strategy | When |
|
|
|----------|------|
|
|
| **Squash merge** | One feature = one commit on main. Clean history. |
|
|
| **Rebase merge** | Preserve individual commits. For stacked PRs. |
|
|
| **Merge commit** | Preserves full history of feature branch. Noisy. |
|
|
|
|
**Default: squash merge.** Keeps main clean and bisectable.
|
|
|
|
## Anti-patterns
|
|
|
|
- ❌ **Committing to main directly** — always use PRs (except hotfix emergencies)
|
|
- ❌ **Large, unfocused commits** — `"WIP"`, `"fixes"`, `"misc changes"`
|
|
- ❌ **Rebasing shared branches** — never rebase a branch others have pulled
|
|
- ❌ **Merge commits in main** — unless you use merge-commit strategy deliberately
|
|
- ❌ **Stale branches** — clean up after merge. Name indicates age/staleness
|
|
- ❌ **No issue/PR reference** — every commit should answer "why?"
|