nagare

Getting Started with Nagare Documentation

Welcome to the Nagare documentation! This guide uses the Diátaxis framework to help you find exactly what you need.

Prerequisites

Before you start using Nagare:

• Deno 2.4+ - You need Deno installed for the runtime
• Git repository - A project with git initialized and conventional commits
• GitHub CLI (optional) - For automatic GitHub release creation
• Text editor - Any editor that supports TypeScript/JavaScript

🆕 Latest Updates

v1.10.0+ - Enhanced Documentation & Branding

• 📚 COMPREHENSIVE: Complete Diátaxis documentation - Structured learning paths for all skill levels
• 🎨 CONSISTENT: Unified branding system - All CLI output uses consistent 🌊 Nagare: messaging
• 📊 VISUAL: Mermaid diagrams - Interactive flow charts and architecture diagrams
• 🔗 INTEGRATED: GitHub Pages ready - Professional documentation hosted at rickcogley.GitHub.io/nagare
• 🛡️ SECURITY: OWASP-compliant architecture - Comprehensive security model documentation
• 🤖 INTELLIGENT: Smart file handlers - Automatic updates for common file types
• 🌊 FLOW-FOCUSED: Release workflow visualization - Clear understanding of the release process

The Documentation Revolution: This release establishes enterprise-grade documentation with visual diagrams, structured learning paths, and comprehensive coverage of all Nagare features - from quick start to advanced security considerations.

📚 Documentation Types

🎓 Tutorials

Learning-oriented - Start here if you’re new to Nagare

• Getting Started - Complete setup and your first release
• Advanced Configuration - Custom templates and file handlers
• CI/CD Integration - Automated releases in GitHub Actions

🔧 How-to Guides

Task-oriented - Practical guides for specific tasks

• Configure File Updates - Set up automatic version updates across multiple files
• Use Custom Templates - Create custom version file templates
• Set Up CI/CD Integration - Integrate with GitHub Actions, GitLab CI, and more
• Use Hooks - Customize release workflows with lifecycle hooks
• Rollback Releases - Safely rollback failed or incorrect releases

📖 Reference

Information-oriented - Complete technical reference

• CLI Reference - Command-line interface documentation
• Configuration Reference - Complete configuration options
• Template Reference - Template system and built-in templates
• Environment Variables - All environment variables and their effects
• API Documentation - Complete TypeScript API reference

💡 Explanation

Understanding-oriented - Deep dives into concepts and design decisions

• Architecture Overview - System architecture and design
• Design Principles - Core design philosophy and decisions
• Security Model - Comprehensive security architecture
• Branding System - Consistent CLI messaging and brand identity
• File Update System - How intelligent file handlers work
• Release Workflow - How releases work internally
• Version Management - Semantic versioning implementation

📊 Visual Diagrams & Architecture

For the best experience viewing interactive Mermaid diagrams, visit these pages directly on GitHub:

• 🏗️ Architecture Overview - Complete system architecture with component diagrams
• 🔄 Release Workflow - Visual release process flow with decision trees
• 🔒 Security Model - Security layers and threat analysis diagrams
• 📁 File Update System - File handler architecture and flow diagrams

🚀 Where to Start?

New to Nagare?

1. Start with Getting Started
2. Follow the Quick Start section below
3. Read Architecture Overview

Need to accomplish something specific?

• Browse How-to Guides for your task
• Check Reference for detailed information
• Review Configuration Reference for all options

Want to understand Nagare deeply?

• Read Design Principles
• Study Architecture Overview
• Explore Security Model

🚀 Quick Start

Don’t want to read the full tutorial? Here’s the fastest path to your first release:

# 1. Initialize Nagare in your project
deno run -A jsr:@rick/nagare/cli init

# 2. Add tasks to your deno.json (copy from init output)
{
  "tasks": {
    "nagare": "deno run -A nagare-launcher.ts",
    "nagare:patch": "deno task nagare patch",
    "nagare:minor": "deno task nagare minor",
    "nagare:major": "deno task nagare major",
    "nagare:dry": "deno task nagare --dry-run"
  }
}

# 3. Create your first release
deno task nagare:dry    # Preview changes first
deno task nagare       # Create actual release

That’s it! Your project now has automated release management.

🌊 Release Flow Visualization

graph TD
    A[📝 Commit with Conventional Format] --> B[🔍 Nagare Analyzes Commits]
    B --> C{🎯 Determine Version Bump}
    C -->|feat:| D[📈 Minor Version]
    C -->|fix:| E[🔧 Patch Version]
    C -->|BREAKING:| F[💥 Major Version]
    
    D --> G[📄 Update Version Files]
    E --> G
    F --> G
    
    G --> H[📝 Generate Changelog]
    H --> I[🏷️ Create Git Tag]
    I --> J[📤 Push to GitHub]
    J --> K[🎉 Create GitHub Release]
    K --> L[✅ Release Complete]
    
    style A fill:#e1f5fe
    style B fill:#e3f2fd
    style C fill:#e8eaf6
    style L fill:#e8f5e8
    style G fill:#fff3e0
    style H fill:#fff3e0
    style K fill:#f3e5f5

📋 Quick Links

Most Common Tasks

• Initialize Nagare
• Configure file updates
• Set up GitHub releases
• Create custom templates
• Rollback a release

Essential Reference

• All CLI commands
• Configuration options
• Template system
• Environment variables
• API documentation

Key Concepts

• Release workflow - How releases work internally
• File update system - Intelligent file handlers
• Security model - OWASP-compliant architecture
• Version management - Semantic versioning

📝 Generating API Documentation

IMPORTANT: Always use the predefined tasks to generate API documentation. This ensures docs are placed in the correct location (docs/api/).

Available Documentation Tasks

# Generate HTML API documentation (recommended)
deno task docs:api

# Generate JSON API documentation
deno task docs:json

# Check JSDoc syntax without generating files
deno task docs:check

# Clean and regenerate all API docs
deno task docs:clean && deno task docs:api

# Serve API documentation locally
deno task docs:serve

⚠️ Never Run Directly

DO NOT run deno doc without the --output flag as it will generate files in the wrong location:

# ❌ WRONG - Will generate in current directory
deno doc --html cli.ts

# ✅ CORRECT - Use the task instead
deno task docs:api

🎯 Finding What You Need

By User Type

Solo Developer

• Getting Started
• Configure File Updates
• Architecture Overview

Team Lead

• CI/CD Integration
• Set Up CI/CD
• Use Hooks
• Design Principles

Enterprise User

• Security Model
• Configuration Reference
• Architecture Overview

By Task

Setting Up Nagare

• Getting Started Tutorial
• CLI Reference
• Configuration Reference

Customizing Releases

• Configure File Updates
• Use Custom Templates
• Template Reference

Automation & CI/CD

• Set Up CI/CD Integration
• Use Hooks
• Environment Variables

Troubleshooting

• Rollback Releases
• Security Model
• CLI Reference

🔧 Key Features Overview

🚀 Automated Releases

• Smart version bumping based on conventional commits
• Professional changelogs following Keep a Changelog format
• GitHub integration with automatic release creation

🤖 Intelligent File Updates

• Built-in handlers for common file types (JSON, TypeScript, Markdown)
• Custom patterns for special requirements
• Template system using Vento for complex version files

🛡️ Security & Reliability

• OWASP-compliant architecture with comprehensive input validation
• Atomic operations with backup and rollback capabilities
• Security audit logging for compliance requirements

⚙️ Highly Configurable

• Convention over configuration with sensible defaults
• Extensible hooks for custom workflows
• Full TypeScript support with comprehensive type definitions

📝 Documentation Principles

This documentation follows these principles:

1. User-focused language - We address you directly with clear, actionable guidance
2. Present tense - We describe what happens now, not what will happen
3. Examples first - We show working examples before explaining concepts
4. Task-oriented structure - We organize content around what you want to accomplish
5. Progressive disclosure - We start simple and add complexity as needed

🤝 Contributing

Found an issue or want to improve the docs?

• File an issue on GitHub
• Read our Contributing Guide
• Submit a pull request with improvements

📄 License

Nagare is MIT licensed. See LICENSE for details.

---

Made with ❤️ by eSolia for the Deno community

This site is open source. Improve this page.