Release Workflow Standards

Comprehensive release management standards for blueflyio/agent-platform projects

Overview

This document defines the complete release workflow including milestones, branches, labels, approvals, and tagging conventions.

Key Principles:

Issue-driven development with GitLab milestones
Semantic versioning (0.x.y for pre-1.0)
Merge trains for protected branch merges
Automated quality gates at each stage

1. Milestone Naming

Format

v0.{minor}.x

Rules

Pre-1.0 releases: Use v0.{minor}.x pattern (e.g., v0.1.x, v0.2.x)
Post-1.0 releases: Use v{major}.{minor}.x pattern (e.g., v1.0.x, v1.1.x)
Milestones represent feature sets, not specific patch versions
Each milestone has corresponding release branch

Examples

v0.1.x   First feature set (MVP)
v0.2.x   Second feature set (API improvements)
v0.3.x   Third feature set (UI overhaul)
v1.0.x   Production-ready release

Milestone Lifecycle

Planning: Create milestone, assign issues
Active Development: Issues Feature branches Release branch
Feature Freeze: No new features, only bugfixes
Release Candidate: Tag v0.X.0-rc.1, v0.X.0-rc.2, etc.
Release: Tag v0.X.0 on main branch
Maintenance: Patch releases v0.X.1, v0.X.2, etc.

2. Branch Flow

Complete Flow Diagram

[Issue #123]
     (Create MR from issue)
[feature/123-add-auth]
     (Auto-merge after CI passes)
[release/v0.2.x]
     (Tag: v0.2.x-dev.N)
     (Manual merge after 2 approvals)
[main]
     (Tag: v0.2.0)

Branch Types

Feature Branches

Format: feature/{issue#}-{slug}
Target: Release branch for assigned milestone
Approvals: 0 (auto-merge after CI)
Lifespan: Deleted after merge
Example: feature/123-add-user-auth release/v0.2.x

Release Branches

Format: release/v{major}.{minor}.x
Target: Main branch
Approvals: 1 human approval required
Lifespan: Permanent (for LTS releases) or until milestone end
Example: release/v0.2.x main
Tags: v0.2.x-dev.1, v0.2.x-dev.2, ... (development snapshots)

Hotfix Branches

Format: hotfix/{slug} or hotfix/{issue#}-{slug}
Target: Main branch directly
Approvals: 2 human approvals (emergency override possible)
Lifespan: Deleted after merge
Example: hotfix/critical-security-patch main

Main Branch

Purpose: Production-ready code, tagged releases
Approvals: 2 human approvals required
Protection: Force push disabled, maintainers only
Tags: v0.1.0, v0.2.0, v1.0.0, etc.

3. Required MR Labels

All merge requests MUST have these labels applied:

Type Labels (Required - Choose ONE)

type::feature - New functionality
type::bugfix - Bug fixes
type::docs - Documentation changes
type::chore - Maintenance, dependencies, CI
type::refactor - Code restructuring without behavior change
type::security - Security fixes or improvements

Priority Labels (Required - Choose ONE)

priority::p0 - Critical, blocking release (must complete)
priority::p1 - High priority (should complete)
priority::p2 - Medium priority (could complete)
priority::p3 - Low priority (won't block release)

Semver Impact Labels (Required - Choose ONE)

semver::major - Breaking changes (0.x.0 0.y.0 or 1.0.0 2.0.0)
semver::minor - New features, backward compatible (0.1.x 0.2.x)
semver::patch - Bug fixes, no API changes (0.1.0 0.1.1)

Component Labels (Optional - Choose one or more)

component::drupal - Drupal modules, themes, recipes
component::npm - NPM packages (BuildKit, OSSA tools)
component::model - AI model integrations, agent behaviors
component::infra - Infrastructure, CI/CD, deployment

Status Labels (Automated)

status::triage - Needs review and classification
status::ready - Ready for development
status::in-progress - Actively being worked on
status::review - In code review
status::done - Merged and closed

4. Tagging Conventions

Development Tags (on release branches)

v{major}.{minor}.x-dev.{N}

Examples:

v0.2.x-dev.1 - First development snapshot on release/v0.2.x
v0.2.x-dev.2 - Second development snapshot
v0.2.x-dev.15 - Fifteenth development snapshot

Purpose:

Track progress on release branch
Enable testing of integration builds
Provide rollback points during development

When to Tag:

After each significant feature merge to release branch
Before starting risky refactoring
Daily snapshots for active development

Release Candidate Tags (on release branches)

v{major}.{minor}.{patch}-rc.{N}

Examples:

v0.2.0-rc.1 - First release candidate
v0.2.0-rc.2 - Second release candidate
v1.0.0-rc.1 - First 1.0 release candidate

Purpose:

Signal feature freeze
Enable broader testing
Final validation before production release

Requirements:

All priority::p0 issues resolved
All CI checks passing
Documentation complete
Migration guides ready (if applicable)

Production Tags (on main branch)

v{major}.{minor}.{patch}

Examples:

v0.1.0 - First release of 0.1.x series
v0.2.0 - First release of 0.2.x series
v0.2.1 - First patch release for 0.2.x
v1.0.0 - Production-ready 1.0 release

Requirements:

All tests passing
2 human approvals on MR to main
Release notes published
CHANGELOG.md updated
Migration guides available (if breaking changes)

Tag Automation

# Tag development snapshot on release branch
git tag v0.2.x-dev.$(git rev-list --count release/v0.2.x)
git push origin v0.2.x-dev.$(git rev-list --count release/v0.2.x)

# Tag release candidate
git tag v0.2.0-rc.1
git push origin v0.2.0-rc.1

# Tag production release on main
git tag v0.2.0
git push origin v0.2.0

5. Approval Gates

Feature Release Branch

Approvals Required: 0 (automated)
CI Requirements:
- All tests passing
- Code coverage 80%
- Linting passing (PHPCS, ESLint, etc.)
- No TypeScript errors (if applicable)
- Security scan passing
Auto-Merge: Enabled via merge train
Labels Required: type::*, priority::*, semver::*

Release Branch Main

Approvals Required: 1 human approval (release manager)
CI Requirements: Same as feature release
Additional Requirements:
- All priority::p0 issues resolved
- Release notes drafted
- CHANGELOG.md updated
- Migration guides ready (if breaking changes)
Auto-Merge: Disabled (manual click required)

Hotfix Main

Approvals Required: 2 human approvals
CI Requirements: Same as above
Emergency Override: Possible with maintainer role
Post-Merge: Cherry-pick to active release branches

6. Complete Workflow Example

Scenario: Adding User Authentication to v0.2.x

Step 1: Create Issue

# In GitLab UI or via CLI
glab issue create \
  --title "Add user authentication system" \
  --milestone "v0.2.x" \
  --label "type::feature,priority::p0,component::drupal"
# Returns: Issue #123

Step 2: Create MR from Issue

1. Open issue #123 in GitLab
2. Click "Create merge request" button
3. GitLab auto-creates branch: 123-add-user-authentication-system
4. MR auto-targets: release/v0.2.x (from milestone)

Step 3: Set Up Worktree

cd ~/Sites/LLM/llm-platform
git fetch origin
git worktree add ../worktrees/123-add-user-authentication-system 123-add-user-authentication-system
cd ../worktrees/123-add-user-authentication-system

Step 4: Develop and Push

# Make changes
buildkit drupal module:create user_auth
# ... implement authentication ...

# Commit with conventional format
git add .
git commit -m "feat(auth): implement JWT-based authentication

- Add user_auth module with JWT tokens
- Implement login/logout endpoints
- Add authentication middleware
- Include unit tests with 85% coverage

Closes #123"

# Push to trigger CI
git push origin 123-add-user-authentication-system

Step 5: Review MR

1. CI pipeline runs automatically
2. All checks pass (tests, linting, coverage)
3. Apply labels if missing: type::feature, priority::p0, semver::minor
4. Merge train auto-merges to release/v0.2.x
5. Issue #123 auto-closes

Step 6: Tag Development Snapshot

# On release/v0.2.x branch
git checkout release/v0.2.x
git pull
git tag v0.2.x-dev.5
git push origin v0.2.x-dev.5

Step 7: Prepare for Release

# When all p0 issues resolved
git tag v0.2.0-rc.1
git push origin v0.2.0-rc.1

# Test release candidate
# ... testing ...

# If bugs found, fix and tag v0.2.0-rc.2
# ... repeat until stable ...

Step 8: Release to Production

# Create MR: release/v0.2.x  main
glab mr create \
  --source-branch release/v0.2.x \
  --target-branch main \
  --title "Release v0.2.0" \
  --label "type::release,priority::p0"

# Add release notes to MR description
# Request 2 approvals from release managers
# Manually merge after approvals

# Tag production release
git checkout main
git pull
git tag v0.2.0
git push origin v0.2.0

# Publish release in GitLab
glab release create v0.2.0 \
  --notes-file RELEASE_NOTES.md

7. Quality Gates Enforcement

Pre-Merge Checks (CI Pipeline)

# .gitlab-ci.yml
include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml

stages:
  - lint
  - test
  - security
  - deploy

lint:
  stage: lint
  script:
    - buildkit golden lint
  rules:
    - if: $CI_MERGE_REQUEST_ID

test:
  stage: test
  script:
    - buildkit golden test
  coverage: '/Coverage:\s+(\d+\.\d+)%/'
  rules:
    - if: $CI_MERGE_REQUEST_ID
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura.xml

security:
  stage: security
  script:
    - buildkit golden audit
  rules:
    - if: $CI_MERGE_REQUEST_ID

Coverage Requirements

Minimum: 80% overall coverage
New Code: 90% coverage for new files
Critical Paths: 95% coverage for authentication, authorization, payment

Linting Standards

PHP: PHPCS with Drupal standards
JavaScript/TypeScript: ESLint + Prettier
CSS: Stylelint
YAML: yamllint
Markdown: markdownlint

8. Troubleshooting

Divergent Branch History

See Release Workflow Critical Updates for detailed recovery procedures.

Quick Fix:

# Preferred: Squash merge
glab mr close $MR_ID
glab mr create \
  --source-branch $SOURCE \
  --target-branch $TARGET \
  --squash-before-merge

Failed Merge Train

# Check merge train status
glab mr view $MR_ID

# If stuck, remove and re-add to train
glab api -X DELETE "projects/$PROJECT_ID/merge_requests/$MR_ID/merge_train"
# Wait for pipeline to pass, then set auto-merge again

Missing Labels

# Add required labels
glab mr update $MR_ID \
  --label "type::feature,priority::p1,semver::minor,component::drupal"

10. Automation Opportunities

BuildKit Commands (Future)

# Automate milestone management
buildkit release milestone create v0.3.x
buildkit release milestone close v0.2.x

# Automate tagging
buildkit release tag --type dev  # Creates v0.2.x-dev.N
buildkit release tag --type rc   # Creates v0.2.0-rc.N
buildkit release tag --type prod # Creates v0.2.0

# Validate MR compliance
buildkit release validate-mr $MR_ID
# Checks: labels, approvals, CI status, milestone assignment

Version: 1.0.0 Created: 2025-12-09 Author: Governance Coordinator Agent Next Review: 2025-12-23

Release Workflow Standards

Release Workflow Standards

Overview

1. Milestone Naming

Format

Rules

Examples

Milestone Lifecycle

2. Branch Flow

Complete Flow Diagram

Branch Types

Feature Branches

Release Branches

Hotfix Branches

Main Branch

3. Required MR Labels

Type Labels (Required - Choose ONE)

Priority Labels (Required - Choose ONE)

Semver Impact Labels (Required - Choose ONE)

Component Labels (Optional - Choose one or more)

Status Labels (Automated)

4. Tagging Conventions

Development Tags (on release branches)

Release Candidate Tags (on release branches)

Production Tags (on main branch)

Tag Automation

5. Approval Gates

Feature Release Branch

Release Branch Main

Hotfix Main

6. Complete Workflow Example

Scenario: Adding User Authentication to v0.2.x

Step 1: Create Issue

Step 2: Create MR from Issue

Step 3: Set Up Worktree

Step 4: Develop and Push

Step 5: Review MR

Step 6: Tag Development Snapshot

Step 7: Prepare for Release

Step 8: Release to Production

7. Quality Gates Enforcement

Pre-Merge Checks (CI Pipeline)

Coverage Requirements

Linting Standards

8. Troubleshooting

Divergent Branch History

Failed Merge Train

Missing Labels

9. Related Documentation

10. Automation Opportunities

BuildKit Commands (Future)