Skip to content

github-guide.md

Latest commit

 

History

History
121 lines (87 loc) · 2.94 KB

github-guide.md

File metadata and controls

121 lines (87 loc) · 2.94 KB
Raw

GitHub Guide

How to use GitHub Issues, milestones, labels, and PRs effectively.

When to Use What

Scale Tools
Any task GitHub Issue
3+ related issues Milestone
Categorization Labels
30+ issues, need visual overview GitHub Project board

Issues

Writing Good Issues

Title: Imperative mood — "Add X", "Fix Y", "Update Z"

Body structure:

## Problem
What's wrong or what's missing.

## Solution
How to fix it or what to build.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

Issue Tips

  • One concern per issue — split large work into multiple issues
  • Link related issues with Related: #XX
  • Use checklists for multi-step work
  • Close with PRs: Closes #XX in the PR body

Labels

Standard Labels (apply to every repo)

Label Color Description
bug #d73a4a Something isn't working
enhancement #a2eeef New feature or improvement
documentation #0075ca Documentation changes
deferred #e4e669 Acknowledged but not prioritized
blocked #b60205 Waiting on something external

Project-Specific Labels

Add category labels per project as needed:

  • auth, scoring, ui, database, api, etc.

Creating Labels via CLI

gh label create "bug" --color "d73a4a" --description "Something isn't working"
gh label create "enhancement" --color "a2eeef" --description "New feature or improvement"
gh label create "documentation" --color "0075ca" --description "Documentation changes"
gh label create "deferred" --color "e4e669" --description "Acknowledged but not prioritized"
gh label create "blocked" --color "b60205" --description "Waiting on something external"

Milestones

Use milestones to group related issues into a release or phase.

# Create a milestone
gh api repos/{owner}/{repo}/milestones -f title="v1.0" -f description="Initial release"

# List milestones
gh api repos/{owner}/{repo}/milestones

When to Use Milestones

  • Grouping issues for a specific release
  • Tracking progress toward a phase or sprint
  • Close the milestone when all issues are done

Pull Requests

PR Checklist

Before creating a PR:

  • Tests pass
  • TypeScript compiles (tsc --noEmit)
  • Changes are focused (one feature/fix per PR)
  • Commit messages follow conventions

Creating a PR

gh pr create --base develop --title "Add user search" --body "$(cat <<'EOF'
## Summary
- Add fuzzy search for users by display name

## Test Plan
- [ ] Search returns matching users
- [ ] Empty query returns no results
- [ ] Special characters are handled

## Related Issues
- Closes #42
EOF
)"

Merging

  • Squash merge for feature branches into develop (clean history)
  • Merge commit for develop into main (preserve the integration point)
gh pr merge --squash    # feature -> develop
gh pr merge --merge     # develop -> main