Skip to content

chore: slim dataset templates to essential info #323

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rucka merged 2 commits into from
Jul 13, 2026
Merged

chore: slim dataset templates to essential info #323

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
76e9294
chore: slim dataset templates to essential info
rucka Jul 12, 2026
3084ebf
chore: link KB pointers in slimmed templates (review #323)
rucka Jul 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
329 changes: 18 additions & 311 deletions .pair/knowledge/guidelines/collaboration/templates/branch-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,79 +39,16 @@ release/v1.2.0-preparation

## Branch Workflow

### 1. Branch Creation

```bash
# Ensure you're on the latest base branch
git checkout main
git pull origin main

# Create and switch to new branch
git checkout -b feature/US-123-user-authentication

# Set upstream tracking
git push -u origin feature/US-123-user-authentication
```

### 2. Development Workflow

```bash
# Make changes and stage them
git add .

# Commit using commit template standards
git commit -m "feat(auth): implement user authentication system

- Add JWT token generation and validation
- Implement password hashing with bcrypt
- Create authentication middleware
- Add login/logout endpoints

Closes US-123"

# Push changes regularly
git push origin feature/US-123-user-authentication
```

### 3. Branch Synchronization

```bash
# Keep branch updated with base branch
git checkout main
git pull origin main
git checkout feature/US-123-user-authentication
git rebase main

# Or use merge if preferred by team
git merge main

# Push updated branch
git push origin feature/US-123-user-authentication --force-with-lease
```

### 4. Pull Request Creation

```bash
# Ensure branch is ready for review
git push origin feature/US-123-user-authentication

# Create PR using gh CLI or web interface
gh pr create --title "[US-123] feat: implement user authentication system" \
--body-file .github/pull_request_template.md \
--assignee @me \
--reviewer @teammate1,@teammate2
```
1. **Creation**: branch from the up-to-date base branch, push with upstream tracking (`git checkout -b <branch> && git push -u origin <branch>`).
2. **Development**: commit per the [commit template](commit-template.md), push regularly.
3. **Synchronization**: keep the branch updated with the base branch (rebase or merge per team preference); after a rebase, push with `--force-with-lease`.
4. **Pull request**: create the PR per the [PR template](pr-template.md) when the branch is ready for review.

## Branch Lifecycle Management

### Branch States

- **Active Development** - Feature work in progress
- **Ready for Review** - Code complete, PR created
- **In Review** - Undergoing code review process
- **Approved** - Approved and ready to merge
- **Merged** - Successfully merged to base branch
- **Archived** - Branch deleted after merge
Active Development → Ready for Review → In Review → Approved → Merged → Archived (deleted).

### Branch Protection Rules

Expand All @@ -123,18 +60,7 @@ gh pr create --title "[US-123] feat: implement user authentication system" \

### Cleanup Process

```bash
# After successful merge, delete local branch
git checkout main
git pull origin main
git branch -d feature/US-123-user-authentication

# Delete remote branch (usually done automatically after PR merge)
git push origin --delete feature/US-123-user-authentication

# Clean up tracking references
git remote prune origin
```
After merge: delete the local and remote branch, then `git remote prune origin` (remote deletion is usually automatic after PR merge).

## Branch Management Guidelines

Expand All @@ -147,129 +73,26 @@ git remote prune origin

### Short-Lived Branches

- **feature/xxx** - Individual feature development
- **bug/xxx** - Bug fix development
- **chore/xxx** - Maintenance and tooling work
- **feature/xxx**, **bug/xxx**, **chore/xxx** - Individual story, fix, or maintenance work; created from the base branch, deleted after merge.

### Branching Strategy

#### Git Flow Model
- **Git Flow**: features branch from `develop`; `release/*` and `hotfix/*` branch toward `main`.
- **GitHub Flow**: everything branches directly from `main`.

```text
main
├── develop
│ ├── feature/US-123-authentication
│ ├── feature/US-124-user-profile
│ └── feature/US-125-dashboard
├── release/v1.2.0
└── hotfix/v1.1.1-critical-fix
```

#### GitHub Flow Model

```text
main
├── feature/US-123-authentication
├── feature/US-124-user-profile
└── hotfix/critical-security-fix
```

### Branch Naming Conventions

#### User Story Branches

```text
feature/US-[story-number]-[brief-description]
feature/US-123-user-authentication
feature/US-124-profile-management
```

#### Bug Fix Branches

```text
bug/BUG-[bug-number]-[brief-description]
bug/BUG-456-login-validation
bug/BUG-789-payment-error
```

#### Task Branches

```text
chore/TASK-[task-number]-[brief-description]
chore/TASK-321-update-dependencies
chore/TASK-654-refactor-api-client
```

#### Hotfix Branches

```text
hotfix/[severity]-[brief-description]
hotfix/critical-payment-processing
hotfix/security-user-data-leak
```
The adopted strategy determines each branch type's base branch.

## Commit Strategy on Branches

### Atomic Commits

Each commit should represent a single logical change:

```bash
git commit -m "feat(auth): add JWT token generation"
git commit -m "test(auth): add authentication middleware tests"
git commit -m "docs(auth): update API documentation for auth endpoints"
```

### Commit Message Format

```text
<type>(<scope>): <description>

<optional body>

<optional footer>
```

### Pre-Commit Checklist

- [ ] Code compiles without errors
- [ ] All tests pass locally
- [ ] Code follows style guidelines
- [ ] Documentation updated if needed
- [ ] No sensitive data in commit
- [ ] Commit message follows standards
Commits on branches follow the [commit template](commit-template.md): atomic commits, standard message format, pre-commit checklist (tests pass, style clean, no sensitive data).

## Collaboration Guidelines

### Branch Ownership

- **Primary Developer** - Creates and owns the branch
- **Collaborators** - Can contribute with permission
- **Collaborators** - Can contribute with permission (pull, commit, push on the shared branch)
- **Reviewers** - Review code but don't commit directly

### Collaboration Commands

```bash
# Add collaborator to branch
git checkout feature/US-123-authentication
git pull origin feature/US-123-authentication

# Make changes and push
git add .
git commit -m "feat(auth): add additional validation"
git push origin feature/US-123-authentication
```

### Conflict Resolution

```bash
# When conflicts occur during rebase/merge
git status # Check conflicted files
# Edit files to resolve conflicts
git add .
git rebase --continue # or git merge --continue
git push origin feature/US-123-authentication --force-with-lease
```
Conflicts are resolved by the branch owner during rebase/merge, then pushed with `--force-with-lease`.

## Quality Assurance

Expand All @@ -283,127 +106,11 @@ git push origin feature/US-123-authentication --force-with-lease
- [ ] No merge commits in feature branch
- [ ] Branch is up to date with base branch

### Automated Checks

- **CI/CD Pipeline** - Runs on every push
- **Code Quality** - Linting and formatting checks
- **Security Scan** - Dependency and code security
- **Test Coverage** - Maintains minimum coverage threshold

### Manual Review Points

- **Code Standards** - Follows team conventions
- **Architecture** - Aligns with system design
- **Performance** - No performance regressions
- **Security** - No security vulnerabilities
Automated checks (CI/CD, linting, security scan, coverage) and review standards are defined in the [quality-assurance guidelines](../../quality-assurance/README.md).

## Troubleshooting

### Common Issues

#### Branch Diverged from Base

```bash
# Solution: Rebase onto latest base
git checkout main
git pull origin main
git checkout feature/US-123-authentication
git rebase main
```

#### Force Push After Rebase

```bash
# Use force-with-lease for safety
git push origin feature/US-123-authentication --force-with-lease
```

#### Branch Name Conflicts

```bash
# Rename local branch
git branch -m old-branch-name new-branch-name

# Delete old remote branch and push new one
git push origin --delete old-branch-name
git push -u origin new-branch-name
```

#### Lost Commits After Rebase

```bash
# Use reflog to find lost commits
git reflog
git checkout [commit-hash]
git checkout -b recovery-branch
```

### Emergency Procedures

#### Revert Branch Changes

```bash
# Revert last commit
git revert HEAD

# Revert multiple commits
git revert HEAD~3..HEAD

# Hard reset to specific commit (use with caution)
git reset --hard [commit-hash]
```

#### Emergency Hotfix Process

```bash
# Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-fix

# Make minimal fix
# Test thoroughly
# Create emergency PR with expedited review
```

---

## Branch Templates for Different Types

### Feature Branch Template

```text
Branch: feature/US-[ID]-[description]
Purpose: Implement new functionality
Base: develop (or main for GitHub Flow)
Lifecycle: Create → Develop → PR → Review → Merge → Delete
```

### Bug Fix Branch Template

```text
Branch: bug/BUG-[ID]-[description]
Purpose: Fix identified issues
Base: develop (or main for hotfixes)
Lifecycle: Create → Fix → Test → PR → Review → Merge → Delete
```

### Chore Branch Template

```text
Branch: chore/TASK-[ID]-[description]
Purpose: Maintenance, refactoring, tooling
Base: develop (or main)
Lifecycle: Create → Work → PR → Review → Merge → Delete
```

### Release Branch Template

```text
Branch: release/v[version]
Purpose: Release preparation and stabilization
Base: develop
Lifecycle: Create → Stabilize → Merge to main → Tag → Delete
```

This branch template provides comprehensive guidance for professional Git workflow management, ensuring consistent practices across all development activities.
- **Branch diverged from base**: rebase onto the latest base branch.
- **Push rejected after rebase**: `git push --force-with-lease`.
- **Lost commits after rebase**: recover via `git reflog`.
- **Emergency hotfix**: branch `hotfix/<severity>-<description>` from `main`, minimal fix, expedited PR review.
Loading
Loading