Add version management helpers and Makefile improvements

- Add scripts/bump-version.sh for automated semantic versioning
  - Automatically updates version in pkg/commands/root.go
  - Creates git commits and tags
  - Includes safety checks and user confirmation
- Enhance Makefile with new targets:
  - Add help target with self-documenting commands
  - Add version-show, version-patch/minor/major targets
  - Add release-patch/minor/major for complete release workflow
  - Add .PHONY declarations for all targets
  - Add descriptive comments for all commands
- Update CLAUDE.md with version management documentation

Inspired by rootly-edge-connector Makefile structure.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: kwent

CLAUDE.md

@@ -43,12 +43,37 @@ make docker-build
 make docker-push
 ```
 
-### Release
+### Release & Version Management
+
+The project uses semantic versioning with automated version bumping:
+
 ```bash
-# Create and push a new version tag
+# Show current and next versions
+make version-show
+
+# Bump versions (updates root.go, commits, creates tag, and pushes)
+make release-patch  # 1.2.10 → 1.2.11 (for bug fixes)
+make release-minor  # 1.2.10 → 1.3.0 (for new features)
+make release-major  # 1.2.10 → 2.0.0 (for breaking changes)
+
+# Or use individual steps
+make version-patch  # Just bump and tag patch version
+make version-minor  # Just bump and tag minor version
+make version-major  # Just bump and tag major version
+
+# Preview next version without making changes
+make version-next
+
+# Legacy manual release (requires VERSION variable)
 make release VERSION="v1.0.0"
 ```
 
+**Note**: Version bumping requires a clean git working directory. The script will:
+1. Update version in `pkg/commands/root.go`
+2. Commit the change
+3. Create and push a git tag
+4. Trigger GitHub Actions to build and publish the release
+
 ## Architecture
 
 ### Package Structure
@@ -109,7 +134,25 @@ Critical fix context: Recent fix addressed panic in key-value parsing for refs a
 
 ## Version Management
 
-Current version is hardcoded in `pkg/commands/root.go:34`. Update this file when releasing new versions.
+Current version is maintained in `pkg/commands/root.go:34` and managed through git tags.
+
+### Version Bumping Process
+
+The `scripts/bump-version.sh` script automates version management:
+1. Reads current version from latest git tag
+2. Calculates next version based on semver (patch/minor/major)
+3. Updates `pkg/commands/root.go` with new version
+4. Commits the change with message "Update version to vX.Y.Z"
+5. Creates annotated git tag (vX.Y.Z)
+6. Pushes commit and tag to origin
+
+### Usage
+
+Use Makefile targets for version management:
+- `make version-show` - Display current and next versions
+- `make release-patch` - Bump patch (bug fixes)
+- `make release-minor` - Bump minor (new features)
+- `make release-major` - Bump major (breaking changes)
 
 The CLI checks for updates on `--version` flag using the `gleich/release` package.
 

Makefile

@@ -1,23 +1,71 @@
-build:
+.PHONY: build docker-build docker-push clean test lint release help
+.PHONY: version-show version-patch version-minor version-major version-next version-help
+.PHONY: release-patch release-minor release-major
+
+help: ## Show this help message
+	@echo 'Usage: make [target]'
+	@echo ''
+	@echo 'Available targets:'
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-20s %s\n", $$1, $$2}'
+
+build: ## Build the binary
 	CGO_ENABLED=0 go build -tags netgo -a -v -ldflags '-extldflags "-static"' -o ./bin/rootly ./cmd/rootly/
 
-docker-build:
+docker-build: ## Build Docker image
 	docker build -t rootlyhub/cli .
 
-docker-push:
+docker-push: ## Push Docker image
 	docker push rootlyhub/cli
 
-clean:
+clean: ## Remove build artifacts
 	rm -r ./bin
 
-test:
+test: ## Run tests
 	go test -count=1 -v ./...
 
-lint:
+lint: ## Run linters
 	golangci-lint run
 	hadolint Dockerfile
 	goreleaser check
 
-release:
+release: ## Create a release with VERSION variable (legacy)
 	git tag -a $(VERSION) -m $(VERSION)
 	git push origin $(VERSION)
+
+# Version management targets
+# These targets manage semantic versioning using git tags
+
+version-show: ## Show current and next versions
+	@echo "Current version: $$(git describe --tags --abbrev=0 2>/dev/null || echo 'No tags found')"
+	@echo "Next patch: $$(scripts/bump-version.sh show patch)"
+	@echo "Next minor: $$(scripts/bump-version.sh show minor)"
+	@echo "Next major: $$(scripts/bump-version.sh show major)"
+
+version-patch: ## Bump patch version (1.2.3 → 1.2.4)
+	@scripts/bump-version.sh patch
+
+version-minor: ## Bump minor version (1.2.3 → 1.3.0)
+	@scripts/bump-version.sh minor
+
+version-major: ## Bump major version (1.2.3 → 2.0.0)
+	@scripts/bump-version.sh major
+
+version-next: ## Show next patch version
+	@scripts/bump-version.sh show patch
+
+version-help: ## Show detailed version help
+	@scripts/bump-version.sh help
+
+# Release targets - these create git tags which trigger CI releases
+
+release-patch: version-patch ## Bump patch version and push tag (triggers CI release)
+	@echo "✅ Patch version bumped and tagged"
+	@echo "🚀 GitHub Actions will automatically build and publish the release"
+
+release-minor: version-minor ## Bump minor version and push tag (triggers CI release)
+	@echo "✅ Minor version bumped and tagged"
+	@echo "🚀 GitHub Actions will automatically build and publish the release"
+
+release-major: version-major ## Bump major version and push tag (triggers CI release)
+	@echo "✅ Major version bumped and tagged"
+	@echo "🚀 GitHub Actions will automatically build and publish the release"

scripts/bump-version.sh

@@ -0,0 +1,232 @@
+#!/bin/bash
+
+# Version bumping script for Rootly CLI
+# Uses git tags to manage versions with semver compatibility
+# Updates version in pkg/commands/root.go
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# File containing the version
+VERSION_FILE="pkg/commands/root.go"
+
+# Function to print colored output
+print_info() {
+    echo -e "${BLUE}INFO:${NC} $1"
+}
+
+print_success() {
+    echo -e "${GREEN}SUCCESS:${NC} $1"
+}
+
+print_warning() {
+    echo -e "${YELLOW}WARNING:${NC} $1"
+}
+
+print_error() {
+    echo -e "${RED}ERROR:${NC} $1"
+}
+
+# Function to get the current version from git tags
+get_current_version() {
+    local current_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+    if [[ -z "$current_tag" ]]; then
+        echo "0.0.0"
+    else
+        echo "$current_tag" | sed 's/^v//'
+    fi
+}
+
+# Function to parse semantic version
+parse_version() {
+    local version=$1
+    local major=$(echo "$version" | cut -d. -f1)
+    local minor=$(echo "$version" | cut -d. -f2)
+    local patch=$(echo "$version" | cut -d. -f3)
+    echo "$major $minor $patch"
+}
+
+# Function to calculate next version
+calculate_next_version() {
+    local type=$1
+    local current=$2
+
+    read -r major minor patch <<< $(parse_version "$current")
+
+    case $type in
+        "major")
+            echo "$((major + 1)).0.0"
+            ;;
+        "minor")
+            echo "$major.$((minor + 1)).0"
+            ;;
+        "patch")
+            echo "$major.$minor.$((patch + 1))"
+            ;;
+        *)
+            echo "Invalid version type: $type" >&2
+            exit 1
+            ;;
+    esac
+}
+
+# Function to check if working directory is clean
+check_git_status() {
+    if [[ -n $(git status --porcelain) ]]; then
+        print_error "Working directory is not clean. Please commit or stash your changes."
+        git status --short
+        exit 1
+    fi
+}
+
+# Function to update version in root.go
+update_version_file() {
+    local version=$1
+    local temp_file="${VERSION_FILE}.tmp"
+
+    print_info "Updating version in $VERSION_FILE"
+
+    if [[ ! -f "$VERSION_FILE" ]]; then
+        print_error "Version file not found: $VERSION_FILE"
+        exit 1
+    fi
+
+    # Update the version line using sed
+    sed "s/version := \"v[0-9]*\.[0-9]*\.[0-9]*\"/version := \"v$version\"/" "$VERSION_FILE" > "$temp_file"
+    mv "$temp_file" "$VERSION_FILE"
+
+    print_success "Version updated to v$version in $VERSION_FILE"
+}
+
+# Function to create and push tag
+create_tag() {
+    local version=$1
+    local tag="v$version"
+
+    print_info "Creating tag: $tag"
+    git tag -a "$tag" -m "Release $tag"
+
+    print_info "Pushing tag to origin..."
+    git push origin "$tag"
+
+    print_success "Tag $tag created and pushed successfully!"
+    print_info "GitHub Actions will build and publish the release automatically"
+}
+
+# Function to show version information
+show_version() {
+    local type=${1:-"patch"}
+    local current=$(get_current_version)
+    local next=$(calculate_next_version "$type" "$current")
+    echo "$next"
+}
+
+# Function to bump version
+bump_version() {
+    local type=${1:-"patch"}
+
+    # Check git status
+    check_git_status
+
+    # Get current version
+    local current=$(get_current_version)
+    print_info "Current version: $current"
+
+    # Calculate next version
+    local next=$(calculate_next_version "$type" "$current")
+    print_info "Next version: $next"
+
+    # Confirm with user
+    echo -n "Are you sure you want to bump from $current to $next? [y/N]: "
+    read -r confirm
+
+    if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+        print_warning "Version bump cancelled."
+        exit 0
+    fi
+
+    # Update version in code
+    update_version_file "$next"
+
+    # Commit the version file change
+    git add "$VERSION_FILE"
+    git commit -m "Update version to v$next"
+    git push origin main
+
+    # Create and push tag
+    create_tag "$next"
+
+    print_success "Version bumped from $current to $next"
+    print_info "Monitor the release at: https://github.com/rootlyhq/cli/releases"
+}
+
+# Function to show help
+show_help() {
+    cat << EOF
+Usage: $0 [COMMAND] [TYPE]
+
+COMMANDS:
+    patch       Bump patch version (default)
+    minor       Bump minor version
+    major       Bump major version
+    show        Show next version without creating tag
+    help        Show this help message
+
+EXAMPLES:
+    $0 patch              # Bump patch version (1.2.3 → 1.2.4)
+    $0 minor              # Bump minor version (1.2.3 → 1.3.0)
+    $0 major              # Bump major version (1.2.3 → 2.0.0)
+    $0 show patch         # Show next patch version
+    $0 show minor         # Show next minor version
+    $0 show major         # Show next major version
+
+This script manages semantic versioning using git tags.
+It updates the version in $VERSION_FILE and creates git tags.
+Version tags trigger GitHub Actions to build and publish releases.
+
+EOF
+}
+
+# Main script logic
+main() {
+    local command=${1:-"patch"}
+    local type=${2:-"patch"}
+
+    case $command in
+        "patch"|"minor"|"major")
+            bump_version "$command"
+            ;;
+        "show")
+            show_version "$type"
+            ;;
+        "help"|"-h"|"--help")
+            show_help
+            ;;
+        *)
+            print_error "Unknown command: $command"
+            show_help
+            exit 1
+            ;;
+    esac
+}
+
+# Check if git is available
+if ! command -v git &> /dev/null; then
+    print_error "git is required but not installed."
+    exit 1
+fi
+
+# Check if we're in a git repository
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    print_error "Not in a git repository."
+    exit 1
+fi
+
+# Run main function
+main "$@"