232 lines
8.5 KiB
Markdown
232 lines
8.5 KiB
Markdown
---
|
|
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 <type>/<short-description>
|
|
```
|
|
|
|
#### 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
|
|
<type>(<scope>): <short imperative summary>
|
|
|
|
[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 <branch-name>
|
|
```
|
|
|
|
#### 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 <resolved-file>
|
|
# 3. Continue rebase: git rebase --continue
|
|
# 4. Force-push with lease:
|
|
git push --force-with-lease origin <branch-name>
|
|
```
|
|
|
|
> [!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 <branch-name>
|
|
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 <file>` |
|
|
| **Unstage a file without losing changes** | `git restore --staged <file>` |
|
|
| **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/<ticket-id>-description` or `fix/<ticket-id>-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`.
|