Contributing

GitFlow workflow and release process

GitFlow Branching Model

The project uses GitFlow with GitHub Actions for CI/CD.

Branches

BranchPurpose
mainProduction-ready code
developDevelopment integration
feature/*New features
hotfix/*Production fixes
release/*Release preparation

Workflow Diagram

feature/my-feature
        │
        ▼ (PR)
    develop
        │
        ▼ (PR)
      main ──────► auto tag + release
        │
        ▼
   hotfix/fix (merge back to develop)

Creating a Feature

# Create feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/my-feature

# Work on your feature...
git add .
git commit -m "Add my feature"

# Push and create PR to develop
git push origin feature/my-feature

Then create a Pull Request from feature/my-feature to develop.

Creating a Release

Releases are created automatically when PRs are merged to main.

Steps

  1. Create feature branch and update VERSION file:
git checkout develop
git checkout -b feature/my-feature

# Make changes...
echo "1.9.0" > VERSION
git add .
git commit -m "Add feature and bump version to 1.9.0"
git push origin feature/my-feature

  1. Create PR feature → develop, then merge

  2. Create PR develop → main, then merge

  3. Automatic release - GitHub Actions will:

    • Read version from VERSION file
    • Create tag v1.9.0
    • Build binaries for all platforms
    • Create GitHub Release with artifacts

Creating a Hotfix

For urgent production fixes:

# Create hotfix from main
git checkout main
git pull origin main
git checkout -b hotfix/critical-fix

# Fix the issue...
echo "1.9.1" > VERSION
git add .
git commit -m "Fix critical bug"

# Push and create PR to main
git push origin hotfix/critical-fix

After merging to main:

# Merge back to develop
git checkout develop
git merge main
git push origin develop

Version Format

FormatDescription
1.0.0Stable release
1.0.0-rc.1Release candidate
1.0.0-beta.1Beta release
1.0.0-alpha.1Alpha release

Checking Version

# From Makefile
make version

# From binary
./build/k8s-provisioner-darwin-arm64 version

Example output:

k8s-provisioner v1.9.0
  Git Commit: 988c0a1
  Build Date: 2026-02-17T14:30:00Z
  Go Version: go1.22
  Platform:   darwin/arm64

Code Guidelines

Commit Messages

  • Use imperative mood: “Add feature” not “Added feature”
  • First line: 50 characters max
  • Body: 72 characters per line

Example:

Add Ollama cloud model support

- Add API key configuration for cloud models
- Support minimax-m2.5:cloud and other cloud variants
- Reduce resources for cloud models (no local GPU needed)

Pull Request Checklist

  • Code compiles (make build)
  • Tests pass (make test)
  • Linter passes (make lint)
  • Documentation updated (if needed)
  • VERSION updated (for releases)

CI/CD Pipeline

On push to main:

  1. Read version from VERSION file
  2. Create git tag if it doesn’t exist
  3. Run tests
  4. Build binaries for all platforms
  5. Generate checksums
  6. Create GitHub Release with artifacts

No manual tagging required! Just update the VERSION file.