Recap — Using GitHub Beyond Code

# Using GitHub Beyond Code Many teams use GitHub only for code. The other features — Issues, Projects, Discussions — turn it into a full collaboration platform. ## Issues — track tasks and bugs Each issue is a tracked item: bug, feature request, task. ```markdown # Issue: Login fails on slow networks ## Description When network is slow, login appears to succeed but session is invalid. ## Steps to reproduce 1. Throttle network to 3G 2. Submit login form 3. ... ## Expected Login succeeds; session valid. ## Actual Login UI shows success but next request gets 401. ## Environment - Browser: Chrome 130 - OS: macOS 14 ``` ### Labels Categorize: - `bug`, `enhancement`, `question`, `documentation` - `priority: high`, `priority: low` - `good first issue`, `help wanted` (for OSS) Color-coded; filterable. ### Assignees Assign to one or more people. Shows up in their notifications and "assigned to me" view. ### Milestones Group issues by release or sprint: `v1.5`, `Q3 2026`, `Beta`. See completion % at a glance. ### Linking issues to PRs In PR description: `Closes #123` automatically closes #123 when PR merges. Or `Refs #123` to reference without closing. ### Issue templates `.github/ISSUE_TEMPLATE/bug_report.md`: ```markdown --- name: Bug report about: Report a bug labels: bug --- ## Description ## Steps to reproduce ## Expected behavior ## Environment ``` Pre-fills when someone clicks "New issue". ## Projects (v2 — boards and tables) Project boards visualize issues across multiple repos. Two layouts: - **Board** (kanban): To Do / In Progress / Done columns. - **Table** (spreadsheet): rows per issue, custom columns. Custom fields: - Status (To Do, In Progress, Review, Done) - Priority (P0/P1/P2) - Sprint (current/next) - Estimate (story points) - Assignee, owner, etc. Filtered views: "My open P0s", "Backlog by milestone". In 2026, GitHub Projects v2 is a real Jira/Linear competitor for many teams. ### Automation - Move to "In Progress" when PR opened. - Move to "Done" when issue closes. - Auto-add new issues to project. Set up in project settings → Workflows. ## Discussions For community Q&A, ideas, and announcements that don't fit into Issues (which are work items). Categories: - **Q&A**: questions with answers. - **Ideas**: feature suggestions, vote-able. - **Show and tell**: community-shared work. - **General**: anything else. - **Announcements**: maintainer-only posts. When to use: - Open-source projects with users. - Internal "engineering questions" board. - Customer-facing repos with community. When not to use: - Pure internal tools with no external community. - Already have a Slack/Discord; Discussions might be redundant. ## GitHub Wiki Per-repo wiki for docs that don't fit in code. In 2026, most teams prefer: - README + `/docs/` markdown in the repo (versioned, reviewable in PRs). - Or a separate docs site (Docusaurus, Mintlify). Wiki has fallen out of favor; only good for very small projects. ## Releases Tag a commit; GitHub creates a Release page with: - Tag (e.g., v1.5.0). - Release notes (manual or auto-generated from PRs). - Attached binaries (CLI tools, installers). - Source code archives. ```bash git tag v1.5.0 git push origin v1.5.0 # Then create release on GitHub UI ``` Or via CLI: ```bash gh release create v1.5.0 --notes "Release notes here" ``` ### Auto-generated release notes GitHub can compose release notes from merged PRs. Configure in `.github/release.yml`: ```yaml changelog: exclude: labels: [skip-changelog] categories: - title: New Features labels: [enhancement] - title: Bug Fixes labels: [bug] ``` Saves hours per release. ## GitHub CLI (gh) Powerful command-line for GitHub: ```bash gh repo create myproject --public gh pr create --title "..." --body "..." gh pr list gh pr view 123 gh pr checkout 123 # checkout someone else's PR locally gh pr merge --squash gh issue create gh issue list --label bug gh release create v1.0 gh workflow run "Deploy" ``` For repeated tasks: scriptable. Install: `brew install gh` / `winget install GitHub.cli`. ## GitHub Packages Host packages (npm, Docker, PyPI alternatives) attached to a repo. Useful for internal/private packages. For public packages: usually use the canonical registry (npm, PyPI) instead. ## Common project-management mistakes 1. **Issues for everything mixed with PRs.** Use issues for what to do; PRs for the change. 2. **No labels.** Hard to filter; everything is "issue". 3. **Stale issues never closed.** Use a stale bot or quarterly cleanup. 4. **Project board but no one updates it.** Worse than no board. 5. **Discussions vs Issues confusion.** Discussions = open-ended; Issues = trackable work. ## Combining for a small team Minimum useful setup: - Issues for bugs/features/tasks. Labels: bug/enhancement/question + priority. - Project board with To Do / In Progress / Done. - PR template forcing description + tests. - Release tags for versions.