relman

v0.1.5

Published

3 months ago

Declarative release configuration system for reproducible, reliable releases

0High
0Medium
0Low

abassey

release deployment git ci-cd devops automation

Relman 🚀

Declarative Release Configuration System for Reproducible, Reliable Releases

Relman is an open-source tool that makes releases reproducible, reliable, and scalable across any development organization. It uses declarative YAML configuration to automate complex release workflows, from single applications to multi-service systems.

✨ Features

Core Release Management

🎯 Declarative Configuration: Define your entire release process in YAML
🔄 Multiple Versioning Strategies: Semantic, timestamp, build number, or custom
🌿 Intelligent Branch Merging: Automatic conflict resolution with configurable strategies
📦 Artifact Generation: Docker images, Git tags, changelogs, and custom artifacts
🏗️ System Orchestration: Coordinate releases across multiple repositories
🧪 Dry-Run Mode: Plan and validate releases before execution
🔒 Rollback Support: Safe rollback to previous versions
📸 Reproducibility: Automatic input branch tagging and release lockfiles
🐳 Docker Integration: Build and tag Docker images with multi-arch support

Interactive Terminal Interface (NEW! 🎉)

🖥️ Beautiful TUI: Claude Code CLI-inspired interactive terminal interface
🎯 Command Palette: Quick access to all commands with fuzzy search (Ctrl+P)
📁 File Browser: Navigate and explore repository files interactively
🔍 Interactive Diff Viewer: Compare changes between branches with syntax highlighting
🧙‍♂️ Configuration Wizard: Step-by-step guided setup for new configurations
📊 Release Planner: Visual release planning with conflict detection
⚡ Real-time Progress: Live progress tracking with animated indicators
⚙️ Settings Management: Configure preferences through intuitive interface

Performance & Developer Experience

⚡ Built with Bun: Fast performance and modern JavaScript runtime
🎨 Rich Terminal UI: Powered by Ink.js (React for CLI)
⌨️ Keyboard Navigation: Full keyboard support with intuitive shortcuts
🎭 Multiple Interfaces: Choose between CLI commands or interactive TUI

🚀 Quick Start

Installation

# Install globally
npm install -g relman

# Or use with Bun
bun install -g relman

# Or run directly
npx relman --help

Launch Interactive Mode (Recommended)

# Launch the beautiful interactive terminal interface
relman tui
# or
relman ui

# Or use the convenient npm script
npm run tui

Traditional CLI Commands

# Initialize configuration in your repository
relman init

# Validate your configuration
relman validate

# Plan your release (dry-run)
relman plan

# Execute the release
relman release

📋 Configuration

Relman supports two types of configurations:

Application-Level Configuration

For single repositories/applications:

# relman.yml
type: "app"
version_strategy: "semantic"
input_branches:
  - branch: "main"
    priority: 0
    conflict_strategy: "ours"
  - branch: "feature/new-auth"
    priority: 1
    conflict_strategy: "theirs"
output_branch: "release/v${VERSION}"
artifacts:
  docker_images:
    - name: "myapp"
      tags:
        - "myapp:${VERSION}"
        - "myapp:latest"
      dockerfile: "./Dockerfile"
      platforms: ["linux/amd64", "linux/arm64"]
  git_tags:
    - "v${VERSION}"
  changelog:
    format: "conventional"
    include_commits: true
# Reproducibility settings
reproducibility:
  tag_input_branches: true
  preserve_exact_commits: true
  generate_lockfile: true

System-Level Configuration

For orchestrating multiple repositories:

# relman.yml
type: "system"
dependencies:
  - repo: "frontend-app"
    path: "relman.yml"
    version_constraint: "^1.0.0"
  - repo: "backend-api"
    path: "relman.yml"
    version_constraint: "~2.1.0"
release_strategy: "parallel"
system_version: "${MAJOR}.${MINOR}.${PATCH}"

🛠️ CLI Commands

| Command | Description | |---------|-------------| | relman tui / relman ui | Launch interactive terminal interface | | relman init | Initialize relman.yml in current repository | | relman validate | Validate configuration files | | relman plan | Show what a release would do (dry-run) | | relman release | Execute the release process | | relman status | Check release status and artifacts | | relman rollback <version> | Rollback to previous version | | relman docs | Open documentation |

🖥️ Interactive Terminal Interface

The TUI provides a modern, intuitive interface inspired by Claude Code CLI:

Key Features

Welcome Screen: Overview of all available commands with keyboard shortcuts
Command Palette (Ctrl+P): Fuzzy search through all commands
File Browser: Navigate repository files with visual indicators
Configuration Wizard: Step-by-step setup for new projects
Release Planner: Visual planning with conflict detection
Diff Viewer: Side-by-side branch comparison
Progress Tracking: Real-time release progress with animations
Settings: Configure preferences interactively

Keyboard Shortcuts

Ctrl+P: Open command palette
Ctrl+C: Quit application
Esc: Go back/cancel current action
↑↓: Navigate lists and menus
Enter: Select/confirm
Tab: Switch between input modes

Navigation

[i] Initialize Configuration
[p] Plan Release
[r] Execute Release
[b] Browse Files
[d] View Diff
[s] Settings
[q] Quit

Command Options

--verbose, -v: Enable verbose output
--dry-run: Show what would be done without making changes
--config, -c <path>: Specify configuration file path
--force, -f: Skip safety checks and confirmations

🔧 Configuration Reference

Version Strategies

semantic: Automatic semantic versioning based on commit messages
timestamp: Version based on current timestamp (YYYYMMDDHHMMSS)
build_number: Incremental build numbers (1.0.0-build.123)
custom: Custom version calculation script

Conflict Resolution Strategies

ours: Keep our version when conflicts occur
theirs: Accept their version when conflicts occur
manual_review: Stop and require manual intervention
custom_script: Use custom script for conflict resolution

Reproducibility Features

Relman ensures 100% reproducible releases through:

Input Branch Tagging: Automatically creates immutable tags for each input branch
Commit Hash Locking: Records exact commit hashes in release metadata
Release Lockfiles: Generates .relman-lock.json with complete release state
Artifact Checksums: Tracks checksums of all generated artifacts

Example Release Lockfile:

{
  "version": "1.2.0",
  "input_branches": [
    {
      "branch_name": "feature/auth",
      "commit_hash": "a1b2c3d4e5f6...",
      "tag_name": "input-feature-auth-20231225120000",
      "timestamp": "2023-12-25T12:00:00.000Z"
    }
  ],
  "artifacts": [...],
  "relman_version": "0.1.0"
}

Release Strategies (System-Level)

sequential: Release dependencies one at a time
parallel: Release multiple dependencies simultaneously
dependency_graph: Smart ordering based on dependency relationships

📖 Examples

See the examples/ directory for complete configuration examples:

app-config.yml - Application-level configuration
system-config.yml - System-level configuration
custom-version-script.sh - Custom versioning
conflict-resolution-script.sh - Custom conflict resolution

🧪 Development

Prerequisites

Bun >= 1.0.0
Git >= 2.20.0
Node.js >= 18.0.0 (for compatibility)

Setup

# Clone the repository
git clone https://github.com/relman-project/relman.git
cd relman

# Install dependencies
bun install

# Run tests
bun test

# Build the CLI
bun run build

# Run in development
bun run src/cli.ts --help

Testing

# Run all tests
bun test

# Run specific test file
bun test tests/unit/config-parser.test.ts

# Run tests in watch mode
bun test --watch

# Run with coverage
bun test --coverage

Project Structure

relman/
├── src/
│   ├── cli.ts              # CLI interface
│   ├── config/
│   │   └── parser.ts       # Configuration parsing and validation
│   ├── version/
│   │   └── calculator.ts   # Version calculation strategies
│   ├── git/
│   │   └── operations.ts   # Git operations and merging
│   └── types/
│       └── config.ts       # TypeScript type definitions
├── tests/
│   └── unit/               # Unit tests
├── examples/               # Example configurations
├── docs/                   # Documentation
└── dist/                   # Built CLI

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Ensure all tests pass (bun test)
Commit your changes (git commit -m 'Add amazing feature')
Push to your branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

TypeScript: Strict mode enabled
Testing: Comprehensive unit tests required
Documentation: Update docs for new features
Formatting: Use built-in Bun formatting
Commits: Follow conventional commit format

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Bun for the fast JavaScript runtime
simple-git for Git operations
Commander.js for CLI framework
semver for semantic versioning

📞 Support

Built with ❤️ by the Relman community