TypeDialog/docs/RELEASE.md

Release Workflow

Guide for preparing and publishing TypeDialog releases.

Release Stages

Complete release workflow has 4 stages:

1. Build - Compile binaries (see BUILD.md)
2. Package - Create distribution archives
3. Prepare - Generate checksums and release notes
4. Publish - Upload to GitHub

Stage 1: Build Binaries

See BUILD.md for complete build instructions.

Quick reference:

# Build release binaries
just distro::build-release

# Or cross-compile all platforms
just distro::cross

Output: Binaries in target/release/

Stage 2: Create Distribution Package

Package includes binaries, configs, and installers:

# Create distribution
just distro::create-package

Output: distribution/typedialog-0.1.0/

Contains:

• bin/ - Compiled binaries
• config/ - Configuration templates
• installers/ - Installation scripts
• MANIFEST.json - Package metadata

See BUILD.md for details.

Stage 3: Prepare Release

Generate checksums and release notes:

# Generate checksums
just distro::create-checksums

# Prepare release
just distro::package-release

Output: release/

release/
├── typedialog-0.1.0.tar.gz      # Distribution package
├── SHA256SUMS                     # Checksums
└── RELEASE_NOTES.md               # Release documentation

Checksums

Verify package integrity:

# On your machine
sha256sum -c SHA256SUMS

# For users
sha256sum typedialog-0.1.0.tar.gz
# Compare with SHA256SUMS

Release Notes

Auto-generated with:

• Installation instructions (all platforms)
• Verification steps
• Contents summary
• Platform support matrix

Edit release/RELEASE_NOTES.md if needed:

nano release/RELEASE_NOTES.md

Stage 4: GitHub Release

Create Release with GitHub CLI

# Create release
gh release create v0.1.0 \
    release/typedialog-0.1.0.tar.gz \
    release/SHA256SUMS \
    --title "TypeDialog 0.1.0" \
    --notes-file release/RELEASE_NOTES.md

Create Release via Web UI

1. Go to GitHub Releases
2. Click "Draft a new release"
3. Fill in:
   • Tag version: v0.1.0
   • Release title: TypeDialog 0.1.0
   • Description: Copy from release/RELEASE_NOTES.md
4. Upload files:
   • release/typedialog-0.1.0.tar.gz
   • release/SHA256SUMS
5. Publish

Complete Release Example

Step-by-step release process:

# 1. Update version in Cargo.toml
nano crates/typedialog-core/Cargo.toml
# Change version = "0.1.0" to new version

# 2. Commit version change
git add crates/typedialog-core/Cargo.toml
git commit -m "chore: bump version to 0.1.0"

# 3. Run full CI/CD
just ci-full

# 4. Build and package
just distro::build-release
just distro::create-package
just distro::create-checksums

# 5. Prepare release
just distro::package-release

# 6. Verify contents
just distro::list-packages

# 7. Review release notes
cat release/RELEASE_NOTES.md

# 8. Create git tag
git tag -a v0.1.0 -m "Release 0.1.0"
git push origin v0.1.0

# 9. Create GitHub release
gh release create v0.1.0 \
    release/typedialog-0.1.0.tar.gz \
    release/SHA256SUMS \
    --title "TypeDialog 0.1.0" \
    --notes-file release/RELEASE_NOTES.md

# 10. Verify installation works
curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.sh | bash
typedialog --version

Installation Verification

After release, verify installation methods work:

Linux/macOS

# Download and run installer
curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.sh | bash

# Verify
typedialog --version
typedialog-tui --version
typedialog-web --version

Windows PowerShell

# Download and run installer
irm https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.ps1 | iex

# Verify
typedialog --version
typedialog-tui --version
typedialog-web --version

Manual Installation

# Extract distribution
tar -xzf typedialog-0.1.0.tar.gz
cd typedialog-0.1.0

# Install
bash installers/install.sh

# Verify
typedialog --version

Distribution Structure

Inside typedialog-0.1.0.tar.gz

typedialog-0.1.0/
├── bin/
│   ├── typedialog        # CLI binary
│   ├── typedialog-tui    # TUI binary
│   └── typedialog-web    # Web binary
├── config/
│   ├── cli/
│   │   ├── default.toml
│   │   ├── dev.toml
│   │   └── production.toml
│   ├── tui/
│   │   ├── default.toml
│   │   ├── dev.toml
│   │   └── production.toml
│   └── web/
│       ├── default.toml
│       ├── dev.toml
│       └── production.toml
├── installers/
│   ├── install.sh         # Linux/macOS
│   ├── install.ps1        # Windows
│   └── README.md          # Instructions
└── MANIFEST.json          # Metadata

MANIFEST.json

Package metadata with structure and contents:

{
  "name": "typedialog",
  "version": "0.1.0",
  "created": "2024-12-17T12:00:00Z",
  "structure": {...},
  "binaries": [...],
  "configs": {...},
  "installers": {...}
}

Security Considerations

Checksums

Always provide checksums:

sha256sum typedialog-0.1.0.tar.gz > SHA256SUMS

Users verify with:

sha256sum -c SHA256SUMS

Installation Scripts

Review before releasing:

# Linux/macOS
less installers/bootstrap/install.sh

# Windows
less installers/bootstrap/install.ps1

Production Configurations

Verify security settings in production configs:

# config/web/production.toml
[security]
require_https = true
csrf_enabled = true
rate_limit = 100
add_security_headers = true

See CONFIGURATION.md for all settings.

Continuous Integration

GitHub Actions

Example CI workflow for automated releases:

# .github/workflows/release.yml
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: rust-lang/rust-action@v1

      - name: Build release
        run: just distro::build-release

      - name: Create package
        run: just distro::create-package

      - name: Generate checksums
        run: just distro::create-checksums

      - name: Prepare release
        run: just distro::package-release

      - name: Create GitHub release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            release/typedialog-*.tar.gz
            release/SHA256SUMS
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Troubleshooting

Release file not found

Ensure files exist in release/:

just distro::list-packages
ls -la release/

Checksum mismatch

Regenerate checksums:

just distro::create-checksums

Installation script fails

Test locally:

# macOS/Linux
bash installers/bootstrap/install.sh

# Windows
pwsh installers/bootstrap/install.ps1

GitHub release failed

Check permissions:

gh auth status
gh release list

Release Checklist

Before releasing:

• Version updated in crates/typedialog-core/Cargo.toml
• All tests passing: just ci::full
• Binaries built: just distro::build-release
• Package created: just distro::create-package
• Checksums verified: just distro::create-checksums
• Release notes generated: just distro::package-release
• Installation tested (at least one platform)
• GitHub tag created: git tag v0.1.0
• Release published to GitHub
• Documentation updated

Release Notes Template

When editing release/RELEASE_NOTES.md:

# TypeDialog 0.1.0

## What's New

- Feature 1
- Feature 2
- Bug fix 1

## Installation

### Linux/macOS
\`\`\`bash
curl -fsSL https://github.com/.../install.sh | bash
\`\`\`

### Windows
\`\`\`powershell
irm https://github.com/.../install.ps1 | iex
\`\`\`

## Verification

\`\`\`bash
sha256sum -c SHA256SUMS
\`\`\`

## Downloads

- typedialog-0.1.0.tar.gz
- SHA256SUMS

## Platforms

- Linux x86_64, ARM64
- macOS Intel, Apple Silicon
- Windows x86_64

Next Steps

• BUILD.md - Building binaries
• CONFIGURATION.md - Configuration options
• INSTALLATION.md - User installation guide

---

Release complete! 🎉

Users can now install via automated installers.