--- name: github-flow description: >- Guides git and GitHub workflow using GitHub Flow: branch creation off main, atomic conventional commits, pull requests, automated CI checks, code reviews, merge strategies, and branch cleanup. Use when creating branches, preparing commits, managing PRs, resolving merge conflicts, or integrating changes into main. --- # GitHub Flow: Branching, Commits, and Pull Requests A lightweight, branch-based workflow optimized for continuous delivery, code quality, and rapid iteration. Under **GitHub Flow**, the `main` branch is always stable and deployable, and all new features, bugfixes, or refactors are developed in dedicated, short-lived branches integrated via Pull Requests (PRs). --- ## 1. Core Principles of GitHub Flow ``` main (deployable) ───────────────────●──────────────────────●───────► \ / / feat/chat-export ●───●─────● (PR #42: Merged) / \ / fix/socket-reconnect ●──────●─────────────────● (PR #43: Merged) ``` 1. **`main` is always deployable**: No untested or half-finished code is committed directly to `main`. 2. **Branch from `main`**: Always create descriptive branches directly from the latest updated `main`. 3. **Commit early and atomically**: Small, logical commits following the **Conventional Commits** specification. 4. **Open a Pull Request early**: Open a PR as soon as work is ready (or draft PR for early feedback). 5. **Review and discuss**: Solicit feedback, pass CI tests, and address comments. 6. **Merge and delete branch**: Integrate into `main` (Squash & Merge or Rebase & Merge) and immediately delete the feature branch. --- ## 2. Step-by-Step Workflow Guide ### Step 1: Synchronize `main` & Create Feature Branch Before starting any new task, ensure your local `main` matches the remote repository: ```bash # Switch to main and pull latest changes git checkout main git pull --ff-only origin main # Create a new branch with a semantic prefix git checkout -b / ``` #### Branch Naming Conventions: | Prefix | Purpose | Example | | :--- | :--- | :--- | | `feat/` | New feature or capability | `feat/speech-to-text` | | `fix/` | Bugfix or patch | `fix/admin-session-timeout` | | `refactor/` | Code refactoring without behavior change | `refactor/websocket-handler` | | `perf/` | Performance improvement | `perf/vector-search-indexing` | | `docs/` | Documentation only | `docs/api-endpoints-guide` | | `test/` | Adding or correcting unit/integration tests | `test/faq-repository-suite` | | `chore/` | Maintenance, dependencies, build configs | `chore/upgrade-vite` | --- ### Step 2: Atomic Commits with Conventional Commits Keep each commit focused on a single logical change. Follow the **Conventional Commits** format: ```text (): [optional body explaining WHY and WHAT changed] [optional footer: Closes #123, BREAKING CHANGE: ...] ``` #### Commit Types: * `feat`: A new feature for the user or system. * `fix`: A bug fix. * `refactor`: Code change that neither fixes a bug nor adds a feature. * `style`: Formatting, missing semicolons, whitespace (no code logic change). * `perf`: Performance optimization. * `test`: Adding missing tests or refactoring test suites. * `docs`: Documentation updates. * `chore`: Build process, package updates, tooling config. #### Good vs. Bad Commits: * ✅ `feat(chat): add auto-reconnect backoff on WebSocket disconnect` * ✅ `fix(auth): prevent token leakage in error response payloads` * ❌ `changes` * ❌ `fixed stuff and updated tests and ui` --- ### Step 3: Local Verification & Pre-Push Validation Before pushing, verify code quality, syntax, and test suites locally: 1. **Check status & modified files**: ```bash git status git diff ``` 2. **Run tests & linters** (project specific): ```bash # Run frontend build / lint if applicable npm run build # Run backend tests / static analysis if applicable composer test ``` 3. **Verify no sensitive secrets or temporary files are staged**: Ensure `.env`, credentials, local cache files, or `.system_generated/` are ignored in `.gitignore`. --- ### Step 4: Push to Remote & Open Pull Request Push the branch to `origin` setting the upstream tracking: ```bash git push -u origin ``` #### Creating the PR: - **Using GitHub CLI (`gh`)**: ```bash gh pr create --title "feat(chat): implement speech-to-text integration" --body-file .agents/skills/github-flow/references/pull-request-template.md ``` - **Using GitHub Web**: Navigate to repository URL, click **Compare & pull request**, and fill in the PR template. --- ### Step 5: Keep Branch Synchronized with `main` If other PRs were merged into `main` while working on your branch, rebase your branch on top of latest `main` to maintain clean history: ```bash # Fetch latest main without switching branches git fetch origin main # Rebase feature branch on origin/main git rebase origin/main # If conflicts occur: # 1. Edit conflicting files and resolve markers (<<<<<<< / ======= / >>>>>>>) # 2. Stage resolved files: git add # 3. Continue rebase: git rebase --continue # 4. Force-push with lease: git push --force-with-lease origin ``` > [!IMPORTANT] > Always use `--force-with-lease` instead of `--force` when pushing rebased branches to prevent overwriting team member commits. --- ### Step 6: Code Review, Approval, & Merge 1. **Review**: Team members and automated CI pipelines review the PR. 2. **Address Feedback**: Push additional commits to the same branch; GitHub updates the PR automatically. 3. **Merge Method**: * **Squash and Merge** (Recommended for feature branches): Combines all branch commits into one clean commit on `main`. * **Rebase and Merge**: Retains individual commits in a flat linear history. 4. **Branch Cleanup**: ```bash # Delete remote branch (GitHub web does this via button or gh) gh pr merge --squash --delete-branch # Or locally clean up: git checkout main git pull --ff-only origin main git branch -d git remote prune origin ``` --- ## 3. Pull Request Template Standard When opening a PR, structure the description with the following markdown format: ```markdown ## Description Provide a concise overview of what this PR does and why it was created. ## Type of Change - [ ] 🚀 New feature (non-breaking change adding functionality) - [ ] 🐛 Bug fix (non-breaking change fixing an issue) - [ ] ♻️ Refactoring (clean code, structure improvement) - [ ] ⚡ Performance optimization - [ ] 📝 Documentation update - [ ] 🔒 Security patch ## Key Changes - Detailed bullet points of main changes - Touched components, models, or endpoints ## How Has This Been Tested? - [ ] Unit tests pass - [ ] Integration tests pass - [ ] Manual test in local browser/environment ## Checklist - [ ] Code follows project style guidelines and naming conventions. - [ ] Self-review conducted; no console.logs or dead debug code left behind. - [ ] No sensitive credentials, secrets, or .env files included. - [ ] Documentation updated where relevant. ``` --- ## 4. Git Emergency & Utility Cheatsheet | Task | Command | | :--- | :--- | | **Discard unstaged changes in a file** | `git restore ` | | **Unstage a file without losing changes** | `git restore --staged ` | | **Undo last commit keeping changes staged** | `git reset --soft HEAD~1` | | **Temporarily stash work in progress** | `git stash save "wip: message"` | | **Restore stashed work** | `git stash pop` | | **Clean untracked files & directories** | `git clean -fd` (Use with caution!) | | **View pretty one-line git log graph** | `git log --oneline --graph --decorate -n 15` | | **Show diff of staged changes** | `git diff --cached` | --- ## 5. Integration with Scrum Multi-Agent Framework When working with `scrum-multi-agent-orchestration`: 1. **Developer Agents (Frontend / Backend)**: Create branches named `feat/-description` or `fix/-description`. 2. **QA Agent**: Checks out the branch, executes verification test suites, and posts results to the PR. 3. **Code Reviewer Agent**: Audits the PR diff against security, clean code, accessibility (WCAG), and Definition of Done (DoD). 4. **Scrum Master / Tech Lead**: Approves and triggers Squash & Merge into `main`.