Release Workflow

🟡 Beta

This guide walks through creating versioned releases with nanx, from simple manual releases to fully automated AI-powered workflows.

nanx

gilfoyle@anton ➜ sonofanton git:(main)

Quick Start

# Interactive release (recommended for first time)
nanx repo release

# Automated patch release
nanx repo release --bump patch --yes

The Release Process

1. Prepare Your Changes

Ensure all changes are committed:

# Check status
nanx r s

# If you have uncommitted changes, commit them
nanx r a .
nanx r c "final changes before release"

2. Run Release Command

nanx repo release

3. Interactive Prompts

Nanx will guide you through:

Current version detection - Shows current version from tags/package.json
Version bump selection - Choose major/minor/patch/prerelease
Release notes - Review/edit auto-generated changelog
Tag creation - Creates git tag with new version
Push to remote - Pushes commits and tags

4. Post-Release

After release:

Git tag is created locally and pushed
Changelog is updated (if configured)
CI/CD pipelines are triggered (if configured)
Package registries are notified (if configured)

Version Bump Strategies

Manual Strategy

Always prompt for bump type:

# .repo.yml
release:
  bump_strategy: manual

Best for:

Small teams with tight release control
Projects with irregular release patterns
When you want explicit control over versions

Auto Strategy

Automatically determine bump from commit messages:

# .repo.yml
release:
  bump_strategy: auto
  bump_engine: conventional  # or accid-git

Analyzes commits since last release:

feat: commits → minor bump
fix: commits → patch bump
BREAKING CHANGE → major bump

Smart-Auto Strategy (Recommended)

AI-assisted version determination:

# .repo.yml
release:
  bump_strategy: smart-auto
  bump_engine: accid-git

Combines commit analysis with AI to:

Understand semantic meaning of changes
Detect breaking changes not marked explicitly
Suggest appropriate version bump with reasoning

Bump Engines

ACCID-Git Engine

Analyzes ACCID-format commits:

# .repo.yml
release:
  bump_engine: accid-git

Looks for:

feat: → minor (new features)
fix: → patch (bug fixes)
refactor: → patch (internal changes)
(breaking) tag → major

Conventional Commits Engine

Standard Conventional Commits parser:

# .repo.yml
release:
  bump_engine: conventional

Follows Conventional Commits specification.

Changelog Generation

Enable Changelog

# .repo.yml
release:
  changelog: true
  changelog_file: CHANGELOG.md

Custom Template

# .repo.yml
release:
  changelog: true
  changelog_template: |
    ## [{version}] - {date}
    
    ### Added
    {features}
    
    ### Fixed
    {fixes}
    
    ### Changed
    {changes}

Example Generated Changelog

## [1.2.0] - 2024-01-15

### Added
- OAuth authentication support
- User profile management
- Dark mode toggle

### Fixed
- Login redirect loop
- Session timeout handling

### Changed
- Updated API endpoints to v2

AI-Powered Changelog Generation New in v0.3.0

nanx can generate professional changelogs using AI. The AI analyzes your commits since the last release and creates both technical (internal) and user-friendly (end-user) release notes.

Enable AI Changelog

# .repo.yml
release:
  changelog:
    ai_enabled: true
    ai_provider: claude              # Use configured AI provider
    internal_dir: change-logs        # Where to save internal changelog
    end_user_dir: change-logs/end-user  # Where to save user-facing changelog

Changelog Formats

AI generates two types of changelogs:

Internal/Technical - Detailed implementation notes with code locations, statistics, and contributor info
End-User - User-friendly summary focusing on features, improvements, and bug fixes

Pause/Continue Workflow New in v0.3.0

When AI changelog generation is enabled, the release process pauses after generating changelogs, giving you a chance to review and edit them before finalizing:

# Start release - pauses after changelog generation
nanx repo release

# Review the generated changelogs in your editor
# Edit as needed...

# Continue and finalize the release
nanx repo release --continue

# Abort a paused release
nanx repo release --abort

Changelog Control Flags New in v0.3.2

Control changelog behavior during releases:

# Skip changelog generation entirely
nanx repo release --no-changelog

# Use a specific changelog format
nanx repo release --changelog-format keep-a-changelog

# Skip end-user changelog (generate only internal)
nanx repo release --no-end-user-changelog

# Use existing changelog if found (don't regenerate)
nanx repo release --use-existing-changelog

# Force regeneration even if changelog exists
nanx repo release --regenerate-changelog

For manual changelog generation outside of releases, see the Changelog Command documentation.

Changelog Path Filtering New in v0.3.0

Control which changes appear in your changelogs:

# .repo.yml
release:
  changelog:
    include_dependencies: true      # Include dependency changes (default: true)
    include_paths:                  # Only include these paths (empty = all)
      - src/
      - lib/
    exclude_paths:                  # Exclude these paths from changelog
      - tests/
      - docs/
      - .github/

Git Tag Message Generation New in v0.3.0

nanx generates rich git tag messages that include a summary, changelog URL, and contributor attribution:

# .repo.yml
release:
  tag_message:
    changelog_public_url_base: "https://github.com/org/repo/blob/main/CHANGELOG.md"
    contributor_format: "{name} ({email})"

Example generated tag message:

Release v1.2.0

## What's New
- OAuth authentication support
- User profile management

Changelog: https://github.com/org/repo/blob/main/CHANGELOG.md#v120

Contributors: Alice ([email protected]), Bob ([email protected])

Release Hooks

Pre-Release Hook

Run checks before creating release:

# .repo.yml
release:
  pre_release_hook: ./scripts/pre-release.sh

Example scripts/pre-release.sh:

#!/bin/bash
set -e

echo "Running pre-release checks..."

# Run tests
npm test

# Check for uncommitted changes
if [[ -n $(git status -s) ]]; then
  echo "Error: Uncommitted changes detected"
  exit 1
fi

# Build
npm run build

# Verify build artifacts
if [[ ! -d "dist" ]]; then
  echo "Error: Build failed"
  exit 1
fi

echo "Pre-release checks passed!"

Post-Release Hook

Run tasks after successful release:

# .repo.yml
release:
  post_release_hook: ./scripts/post-release.sh

Example scripts/post-release.sh:

#!/bin/bash
set -e

echo "Running post-release tasks..."

# Publish to npm
npm publish

# Deploy to production
npm run deploy

# Notify team via webhook
curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL

echo "Post-release tasks complete!"