GITHUB WORKFLOW MANAGEMENT¶

CRITICAL SAFETY PROTOCOLS¶

MANDATORY: Before ANY destructive Git operations, you MUST ALWAYS verify: 1. Working directory status - Check for uncommitted changes 2. Branch context - Confirm current branch and target branch 3. Remote status - Verify synchronization with remote repository 4. Backup state - Ensure important work is committed or stashed

NEVER perform force operations without explicit user confirmation and clear warnings about data loss.

BRANCH MANAGEMENT GUIDELINES¶

Creating New Branches¶

ALWAYS follow this branch creation workflow:

Check working directory status:
```
./github-actions.sh status
```
Pull latest changes from main/master:
```
./github-actions.sh pull
```

Create feature branch with descriptive name:

./github-actions.sh branch feature/descriptive-name

Branch Naming Conventions¶

MANDATORY: Use these standardized branch naming patterns:

Features: feature/description (e.g., feature/user-authentication)
Bug fixes: bugfix/issue-description (e.g., bugfix/login-validation)
Hotfixes: hotfix/critical-fix (e.g., hotfix/security-patch)
Documentation: docs/update-description (e.g., docs/api-documentation)
Custom Scripts: custom-scripts/script-name (e.g., custom-scripts/github-actions)
Experiments: experiment/feature-name (e.g., experiment/new-ui-framework)

NEVER use spaces, special characters, or unclear abbreviations in branch names.

COMMIT MESSAGE STANDARDS¶

Commit Message Format¶

ALWAYS use clear, descriptive commit messages following this format:

Action: Brief description of what was done

- Detailed explanation if needed
- Multiple bullet points for complex changes
- Reference to issues or tickets when applicable

Examples of Good Commit Messages:¶

Add: User authentication system with JWT tokens
Fix: Resolve login validation bug preventing user access
Update: Improve error handling in payment processing
Refactor: Simplify database connection logic
Remove: Deprecated API endpoints from v1.0

Examples of BAD Commit Messages:¶

fix (too vague)
changes (meaningless)
wip (work in progress - should not be pushed)
test (unclear what was tested)

MERGING AND PULL REQUEST WORKFLOW¶

Safe Merge Process¶

MANDATORY: Follow this complete merge workflow:

Ensure feature branch is up-to-date:
```
./github-actions.sh pull
```

Switch to target branch (usually main):

./github-actions.sh branch main
./github-actions.sh pull

Test merge compatibility (dry run recommended):

./github-actions.sh merge feature/branch-name --dry-run

Perform actual merge only if dry run succeeds:

./github-actions.sh merge feature/branch-name

Push merged changes:
```
./github-actions.sh push
```
Clean up merged branches:
```
./github-actions.sh cleanup
```

Pull Request Creation Guidelines¶

WHEN TO CREATE PULL REQUESTS: - Feature implementation is complete - All tests pass locally - Code has been reviewed (if team environment) - Documentation has been updated - Branch is pushed to remote

PULL REQUEST STANDARDS:

./github-actions.sh pr "Clear, descriptive title explaining the change"

Include in PR description: - What was changed and why - How to test the changes - Any breaking changes or migration steps - Screenshots/demos for UI changes - Links to related issues or documentation

EMERGENCY PROCEDURES¶

Rollback Operations¶

Option 1: Rollback to previous commit (soft) Use when: You need to undo the last commit but keep changes staged

./github-actions.sh rollback

Option 2: Rollback to specific commit Use when: You need to return to a specific known good state

./github-actions.sh rollback abc123def

WARNING: Rollback operations are destructive. Always verify the target commit hash before proceeding.

Handling Merge Conflicts¶

WHEN CONFLICTS OCCUR: 1. Stop and assess - Do not force through conflicts 2. Check conflict files - Use git status to identify conflicted files 3. Manual resolution - Edit files to resolve conflicts properly 4. Test thoroughly - Ensure resolution doesn't break functionality 5. Commit resolution - Use descriptive commit message about conflict resolution

Recovery from Failed Operations¶

If a Git operation fails: 1. Read error messages carefully - Git errors are usually informative 2. Check repository status - Use ./github-actions.sh status 3. Verify remote connectivity - Ensure network and authentication work 4. Stash uncommitted changes if needed - git stash before retrying 5. Seek help - Ask for assistance rather than forcing operations

DEVELOPMENT WORKFLOW PATTERNS¶

Feature Development Workflow¶

STANDARD FEATURE DEVELOPMENT: 1. Create feature branch from main 2. Make incremental commits with clear messages 3. Push regularly to backup work 4. Create pull request when feature is complete 5. Merge after review/approval 6. Clean up branch after merge

Hotfix Workflow¶

EMERGENCY FIXES: 1. Create hotfix branch from main/production 2. Make minimal changes to fix critical issue 3. Test thoroughly in isolation 4. Fast-track review process 5. Merge immediately after verification 6. Tag release if applicable

Collaborative Development¶

TEAM COORDINATION: - Pull latest changes before starting work - Push work-in-progress branches for backup - Communicate about shared files/areas - Use draft pull requests for early feedback - Coordinate merge timing to avoid conflicts

AUTOMATION AND SAFETY¶

Pre-commit Checks¶

ALWAYS VERIFY before committing: - Code compiles/runs without errors - Tests pass (if test suite exists) - No debug code or personal credentials included - Documentation is updated for API changes - Formatting follows project standards

Repository Maintenance¶

REGULAR MAINTENANCE TASKS:

# Check repository health
./github-actions.sh status

# Synchronize with remote
./github-actions.sh sync

# Clean up merged branches
./github-actions.sh cleanup

Backup Strategies¶

PROTECTION AGAINST DATA LOSS: - Commit work frequently (at least daily) - Push branches to remote for backup - Use meaningful commit messages for easy recovery - Tag important milestones/releases - Maintain separate backup of critical configurations

TROUBLESHOOTING GUIDELINES¶

Common Issues and Solutions¶

Authentication Problems: 1. Verify GitHub CLI authentication: gh auth status 2. Check SSH key configuration: ssh -T git@github.com 3. Ensure remote URLs are correct: git remote -v

Sync Issues: 1. Check internet connectivity 2. Verify repository permissions 3. Ensure branch exists on remote 4. Try force sync only as last resort with --force flag

Merge Conflicts: 1. Never ignore or bypass conflicts 2. Understand what each conflicting change does 3. Test merged result thoroughly 4. Get team input for complex business logic conflicts

Performance Issues: 1. Large repositories may need shallow clones 2. Use .gitignore to exclude unnecessary files 3. Clean up old branches and tags periodically 4. Consider repository splitting for massive projects

INTEGRATION WITH DEVELOPMENT TOOLS¶

IDE Integration¶

OPTIMIZE WORKFLOW: - Configure IDE to show Git status in sidebar - Set up automatic formatting on save - Enable pre-commit hooks for quality checks - Use IDE's built-in merge conflict resolution tools

CI/CD Considerations¶

CONTINUOUS INTEGRATION: - Ensure commits trigger appropriate build/test pipelines - Use conventional commit messages for automated changelogs - Tag releases consistently for deployment automation - Coordinate with team on deployment branch strategies

Documentation Synchronization¶

KEEP DOCS UPDATED: - Update README files with feature changes - Maintain API documentation for interface changes - Include setup/installation instructions - Document breaking changes and migration paths

This GitHub partition provides comprehensive guidance for safe, effective Git and GitHub operations while maintaining code quality and team coordination.