Skip to content

AGENTS.md

Latest commit

 

History

History
110 lines (93 loc) · 5.13 KB

AGENTS.md

File metadata and controls

110 lines (93 loc) · 5.13 KB

Semantic Version Manager - Agent Guidelines

Quick Start Commands

  • Local pipeline: task pipeline:local - Runs format, lint, build, test, coverage, and docs
  • Show version: task version:show:full - Displays current version
  • Bump version: task version:bump:patch (or minor/major)
  • Release: task release:patch (or minor/major) - Full release pipeline
  • Build binary: task build:release - Creates universal binary (arm64 + x86_64)

Build/Test Commands

  • Build debug: swift build or task build:debug
  • Build release: task build:release - Creates optimized universal binary
  • Test all: swift test --parallel or task test
  • Test single: swift test --filter <TestName> (e.g., swift test --filter SemanticVersionTests)
  • Format: task format or swift package plugin --allow-writing-to-package-directory format-source-code
  • Lint: task lint or swift package plugin lint-source-code
  • Coverage: task test:coverage (requires 85% threshold)
  • Documentation: task document - Generates DocC documentation in ./docs

Version Management

  • Version file: version.json - Contains semantic version components
  • Version bumping: Use task version:bump:[patch|minor|major] (auto-commits)
  • Pre-release: task version:set:prerelease -- alpha.1
  • Build metadata: task version:set:build -- 20250514.3
  • Git tags: Created automatically during release (task release:*)

Release Process

  1. Prepare release: task release:dry-run - Test without pushing
  2. Create release: task release:[patch|minor|major] - Full automated release
    • Bumps version and commits
    • Builds universal binary
    • Generates Homebrew formula with SHA256
    • Creates GitLab package and release
    • Tags and pushes to main
  3. Rollback: task release:rollback - Reverts last release if needed

GitLab CI/CD Pipeline

The .gitlab-ci.yml defines automated workflows:

Stages

  1. build: Compiles project and runs initial checks
  2. test: Runs test suite with coverage
  3. package: Creates release artifacts (manual trigger)
  4. release: Publishes to GitLab registry (manual trigger)

Pipeline Jobs

  • build-job: Format, lint, and build debug version
  • test-job: Run tests with 85% coverage requirement
  • package-job: Build universal binary and generate Homebrew formula
  • release-job: Upload to GitLab package registry

Artifacts

  • Test coverage reports (Cobertura format)
  • Universal binary: .build/release/semantic-version-manager
  • Homebrew formula: Formula/semantic-version-manager.rb

Code Style

  • Swift version: 6.1, macOS 14+ minimum
  • Formatting: 2-space indentation, 100 char line length, 1 blank line max (via .swift-format.json)
  • Imports: Foundation first, then external packages, then internal modules
  • Naming: PascalCase for types, camelCase for variables/functions, SCREAMING_SNAKE for constants
  • Access control: Explicit public/internal/private, prefer let over var
  • Error handling: Use custom errors (e.g., SemanticVersionError), throw specific errors
  • Testing: Use Swift Testing framework (@Test, @Suite), descriptive test names
  • File structure: Sources/[Module]/ for code, Tests/[Module]Tests/ for tests
  • Dependencies: Check Package.swift before adding new packages
  • Documentation: Swift DocC for public APIs with AllPublicDeclarationsHaveDocumentation rule enabled

Task Automation (Taskfile.yml)

The project uses Task for automation. Key task groups:

Version Tasks

  • version:show:[core|full|major|minor|patch|prerelease|build] - Display version components
  • version:bump:[patch|minor|major] - Increment version with git commit
  • version:set:[major|minor|patch|prerelease|build] - Set specific version values

Build Tasks

  • build:debug - Debug build with code coverage
  • build:release - Optimized universal binary (arm64 + x86_64)

Quality Tasks

  • format - Auto-format code
  • lint - Check code style
  • test - Run test suite
  • test:coverage - Generate coverage report
  • document - Generate DocC documentation

Pipeline Tasks

  • pipeline:local - Complete local validation
  • pipeline:ci - GitLab CI pipeline steps

Release Tasks

  • release:prepare - Generate Homebrew formula
  • release:create - Create GitLab release
  • release:dry-run - Test release without pushing
  • release:patch|minor|major - Complete release workflow
  • release:rollback - Undo last release

GitLab Integration

  • Registry: Packages published to ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/semantic-version-manager
  • Releases: Created via GitLab API with binary and formula as assets
  • Protected branches: Release jobs require protected branch/tag
  • Manual triggers: Package and release stages require manual approval

Important Notes

  • Always run task pipeline:local before committing
  • Documentation comments required for all public APIs
  • Universal binaries built with lipo for both architectures
  • Homebrew formula auto-generated with SHA256 checksums
  • Git commits automated for version bumps (use --no-commit to disable)