gh-action-readme/docs/development.md

Development Guide

Comprehensive guide for developing and contributing to gh-action-readme.

🚨 CRITICAL: README Protection

NEVER overwrite /README.md - The root README.md is the main project documentation.

For testing generation commands:

# New enhanced targeting (recommended)
gh-action-readme gen testdata/example-action/
gh-action-readme gen testdata/composite-action/action.yml

# Traditional method (still supported)
cd testdata/
../gh-action-readme gen [options]

🛠️ Development Setup

Prerequisites

• Go 1.24+ (required)
• golangci-lint (for linting)
• pre-commit (for git hooks)
• Docker (optional, for containerized testing)

Quick Start

# Clone repository
git clone https://github.com/ivuorinen/gh-action-readme.git
cd gh-action-readme

# Install development tools
make devtools

# Install pre-commit hooks
make pre-commit-install

# Build and test
make build
make test
make lint

🏗️ Architecture

Core Components

• main.go - CLI with Cobra framework, enhanced gen command
• internal/generator.go - Core generation logic with custom output paths
• internal/config.go - Viper configuration (XDG compliant)
• internal/output.go - Colored terminal output with progress bars
• internal/errors/ - Contextual error handling with suggestions
• internal/wizard/ - Interactive configuration wizard
• internal/progress.go - Progress indicators for batch operations

Template System

• templates/readme.tmpl - Default template
• templates/themes/ - Theme-specific templates
  • github/ - GitHub-style with badges
  • gitlab/ - GitLab CI/CD focused
  • minimal/ - Clean, concise
  • professional/ - Comprehensive with ToC
  • asciidoc/ - AsciiDoc format

Testing Framework

• testutil/ - Comprehensive testing utilities
• testdata/ - Test fixtures and sample actions
• Table-driven tests - Consistent testing patterns
• Mock implementations - Isolated unit tests

🧪 Testing Strategy

Running Tests

# All tests
make test

# With coverage
make test-coverage

# Specific package
go test ./internal/generator

# Verbose output
go test -v ./...

# Race condition detection
go test -race ./...

Test Types

Unit Tests (*_test.go):

go test ./internal        # Core logic tests
go test ./testutil        # Test framework tests

Integration Tests (*_integration_test.go):

go test -tags=integration ./...

Comprehensive Tests (comprehensive_test.go):

go test ./internal -run Comprehensive

Testing Best Practices

1. Use testutil framework for consistent test patterns
2. Table-driven tests for multiple scenarios
3. Mock external dependencies (GitHub API, filesystem)
4. Test error conditions and edge cases
5. Verify thread safety with race detection

Test Coverage

Current coverage: 51.2% overall

• Cache module: 91.4%
• Errors module: 91.5%
• Git detector: 78.4%
• Validation: 76.2%

Target: >80% coverage for all new code

🔧 Build System

Makefile Targets

# Building
make build               # Build binary
make clean              # Clean build artifacts

# Testing
make test               # Run all tests
make test-coverage      # Run tests with coverage
make lint               # Run all linters

# Development
make devtools           # Install dev tools
make format             # Format code
make pre-commit-install # Install git hooks

# Security
make security           # Run security scans
make vulncheck          # Go vulnerability check

# Dependencies
make deps-check         # Check outdated dependencies
make deps-update        # Interactive dependency updates

Build Configuration

# Build with version info
go build -ldflags "-X main.version=v1.0.0 -X main.commit=$(git rev-parse HEAD)"

# Cross-platform builds (handled by GoReleaser)
GOOS=linux GOARCH=amd64 go build
GOOS=darwin GOARCH=arm64 go build
GOOS=windows GOARCH=amd64 go build

📝 Code Style & Quality

Linting Configuration

• golangci-lint with 35+ enabled linters
• EditorConfig compliance required
• Pre-commit hooks for automated checking
• Zero linting violations policy

Code Quality Standards

• ✅ Cyclomatic complexity <10 for all functions
• ✅ Test coverage >80% for critical modules
• ✅ Error handling for all possible errors
• ✅ Documentation for all exported functions
• ✅ Thread safety for concurrent operations

Formatting Rules

# Auto-format code
make format

# Check formatting
gofmt -d .
goimports -d .

🔄 Adding New Features

New Theme

1. Create templates/themes/THEME_NAME/readme.tmpl
2. Add to resolveThemeTemplate() in config.go
3. Update configThemesHandler() in main.go
4. Add tests and documentation

New Output Format

1. Add constant to generator.go
2. Add case to GenerateFromFile() switch
3. Implement generate[FORMAT]() method
4. Update CLI help and documentation

New CLI Command

1. Add command in main.go using Cobra
2. Implement handler function
3. Add flags and validation
4. Write tests and update documentation

New Template Functions

Add to templateFuncs() in internal/template.go:

"myFunction": func(input string) string {
    // Implementation
    return processed
},

🚀 Performance Optimization

Profiling

# CPU profiling
go test -cpuprofile=cpu.prof -bench=.
go tool pprof cpu.prof

# Memory profiling
go test -memprofile=mem.prof -bench=.
go tool pprof mem.prof

# Benchmark testing
go test -bench=. -benchmem

Performance Guidelines

• Use sync.Pool for frequently allocated objects
• Implement caching for expensive operations
• Minimize memory allocations in hot paths
• Concurrent processing for I/O bound operations
• Profile before optimizing

🔐 Security Practices

Security Scanning

make security           # Run all scans
make vulncheck         # Go vulnerabilities
make trivy             # Filesystem scan
make gitleaks          # Secrets detection

Secure Coding

• Validate all inputs especially user-provided data
• Use secure defaults for all configurations
• Sanitize file paths to prevent directory traversal
• Handle secrets safely never log or expose tokens
• Regular dependency updates with security patches

GitHub Token Handling

// ❌ Wrong - logging token
log.Printf("Using token: %s", token)

// ✅ Correct - masking sensitive data
log.Printf("Using token: %s", maskToken(token))

func maskToken(token string) string {
    if len(token) < 8 {
        return "***"
    }
    return token[:4] + "***" + token[len(token)-4:]
}

📚 Documentation

Documentation Standards

• godoc comments for all exported functions
• README updates for user-facing changes
• CHANGELOG entries following Keep a Changelog format
• Architecture Decision Records for significant changes

Writing Guidelines

// Package generator provides core documentation generation functionality.
//
// The generator processes GitHub Action YAML files and produces formatted
// documentation in multiple output formats (Markdown, HTML, JSON, AsciiDoc).
package generator

// GenerateReadme creates formatted documentation from an ActionYML struct.
//
// The function applies the specified theme and output format to generate
// comprehensive documentation including input/output tables, usage examples,
// and metadata sections.
//
// Parameters:
//   - action: Parsed action.yml data structure
//   - theme: Template theme name (github, gitlab, minimal, professional, default)
//   - format: Output format (md, html, json, asciidoc)
//
// Returns formatted documentation string and any processing error.
func GenerateReadme(action *ActionYML, theme, format string) (string, error) {
    // Implementation...
}

🤝 Contributing Guidelines

Contribution Process

1. Fork repository and create feature branch
2. Make changes following code style guidelines
3. Add tests for new functionality
4. Update documentation as needed
5. Run quality checks (make test lint)
6. Submit pull request with clear description

Pull Request Guidelines

• Clear title describing the change
• Detailed description of what and why
• Link related issues if applicable
• Include tests for new features
• Update documentation for user-facing changes
• Ensure CI passes all quality checks

Code Review Process

• Two approvals required for merging
• All checks must pass (tests, linting, security)
• Documentation review for user-facing changes
• Performance impact assessment for core changes

🐛 Debugging

Debug Mode

# Enable verbose output
gh-action-readme gen --verbose

# Debug configuration
gh-action-readme config show --debug

# Trace execution
TRACE=1 gh-action-readme gen

Common Issues

Template Errors:

# Validate action.yml syntax
gh-action-readme validate --verbose

# Check template syntax
gh-action-readme gen --dry-run --verbose

GitHub API Issues:

# Check rate limits
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/rate_limit

# Test API access
gh-action-readme gen --verbose --github-token $GITHUB_TOKEN

Build Issues:

# Clean and rebuild
make clean
make build

# Check dependencies
go mod verify
go mod tidy

📊 Metrics & Monitoring

Performance Metrics

• Generation time per action
• GitHub API request count and timing
• Memory usage during processing
• Cache hit rates for repeated operations

Quality Metrics

• Test coverage percentage
• Linting violations count
• Security vulnerabilities detected
• Documentation coverage for public APIs

Tracking Tools

# Performance benchmarks
go test -bench=. -benchmem ./...

# Memory profiling
go test -memprofile=mem.prof ./...

# Coverage reporting
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

---

Status: ENTERPRISE READY ✅ Enhanced gen command, thread-safety, comprehensive testing, and enterprise features fully implemented.