GitFlow Guide for gem-ci

This guide explains the Git workflow and branching strategy used in gem-ci projects.

Overview

gem-ci follows a simplified GitFlow model optimized for Ruby gem development with automated CI/CD integration.

📊 Visual Guide: See the GitFlow Diagram for a visual representation of this workflow.

Branch Structure

Main Branches

Supporting Branches

Workflow Steps

Feature Development

1
2
3
4
5
6
7
8
9
10
11
12

# Start new feature
git checkout develop
git pull origin develop
git checkout -b feature/new-awesome-feature

# Work on feature
git add .
git commit -m "feat: add awesome feature"
git push origin feature/new-awesome-feature

# Create pull request to develop
# After review and CI passes, merge via GitHub

Bug Fixes

1
2
3
4
5
6
7
8
9
10
11

# Start bug fix
git checkout develop
git pull origin develop
git checkout -b bugfix/fix-critical-issue

# Fix the bug
git add .
git commit -m "fix: resolve critical issue with validation"
git push origin bugfix/fix-critical-issue

# Create pull request to develop

Hotfix Process

1
2
3
4
5
6
7
8
9
10
11
12

# Start hotfix from master
git checkout master
git pull origin master
git checkout -b hotfix/v1.2.1

# Apply critical fix
git add .
git commit -m "fix: critical security vulnerability"
git push origin hotfix/v1.2.1

# Create PR to master
# After merge, also merge to develop to sync changes

Release Process

1
2
3
4
5
6
7
8
9
10
11
12

# Start release preparation
git checkout develop
git pull origin develop
git checkout -b release/v1.3.0

# Prepare release (version bumps, changelog, etc.)
git add .
git commit -m "chore: prepare release v1.3.0"
git push origin release/v1.3.0

# Create PR to master
# After merge, tag will be created automatically by release-please

Automated Workflows

gem-ci includes automated workflows that integrate with this GitFlow:

CI Triggers

Branch Protection

Repository rulesets enforce the GitFlow model:

Automated Release

Commit Message Convention

Follow Conventional Commits:

1
2
3
4
5

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Examples

1
2
3
4

git commit -m "feat: add support for custom linting rules"
git commit -m "fix: resolve memory leak in test runner"
git commit -m "docs: update installation guide with Ruby 3.3 requirements"
git commit -m "ci: optimize workflow to use only Ruby 3.3 for cost savings"

Integration with gem-ci Workflows

Status Checks

Each branch type triggers appropriate workflows:

1
2
3
4
5

# .github/workflows/02-ci.yml runs on:
- feature/* branches (PR events)
- bugfix/* branches (PR events)  
- develop branch (push events)
- master branch (push events)

Quality Gates

Release Automation

1
2
3
4
5
6

# .github/workflows/06-release.yml handles:
- Version detection from conventional commits
- Changelog generation
- GitHub release creation
- RubyGems publication
- Slack notifications

Best Practices

Branch Naming

Pull Request Guidelines

Merge Strategy

Troubleshooting

Common Issues

Branch protection conflicts:

1
2
3

# If direct push is blocked
git checkout -b fix/update-readme
# Make changes, then PR instead of direct push

Merge conflicts:

1
2
3
4
5
6

# Update your branch with latest develop
git checkout feature/my-feature
git fetch origin
git rebase origin/develop
# Resolve conflicts, then continue
git rebase --continue

Failed status checks:

1
2
3
4

# Run tests locally first
bundle exec rspec
bundle exec rubocop
# Fix issues before pushing

References

This GitFlow model balances structure with simplicity, ensuring quality while maintaining development velocity.