Examples

Real-world usage examples and patterns for HelixCommit

Overview

This page provides practical examples of using HelixCommit in various scenarios. Each example includes complete commands and explanations to help you adapt them to your needs.

Basic examples

Generate release notes for unreleased changes

The most common use case: see what’s changed since your last release.

helixcommit generate \
  --unreleased \
  --format markdown \
  --out RELEASE_NOTES.md

Works offline with --no-prs flag for faster generation.

Create notes between specific tags

Generate release notes for a specific version range:

helixcommit generate \
  --since-tag v1.2.0 \
  --until-tag v1.2.1 \
  --format markdown \
  --out release-1.2.1.md

Generate notes for custom commit range

Use commit SHAs or any Git refs:

helixcommit generate \
  --since abc123def \
  --until feature-branch \
  --format markdown

Output format examples

Generate all formats at once

Create release notes in Markdown, HTML, and plain text simultaneously:

#!/bin/bash

echo "Generating release notes in all formats..."

# Markdown for GitHub
helixcommit generate \
  --unreleased \
  --format markdown \
  --out RELEASE_NOTES.md

# HTML for website
helixcommit generate \
  --unreleased \
  --format html \
  --out docs/changelog.html

# Text for email
helixcommit generate \
  --unreleased \
  --format text \
  --out CHANGES.txt

echo "✓ Release notes generated in all formats"

Format for specific platforms

GitHub Releases

# Optimized for GitHub releases
helixcommit generate \
  --since-tag v1.0.0 \
  --until-tag v2.0.0 \
  --format markdown \
  --include-scopes \
  --out RELEASE_NOTES.md

# Use in GitHub CLI
gh release create v2.0.0 \
  --title "Version 2.0.0" \
  --notes-file RELEASE_NOTES.md

Slack/Discord

# Plain text for chat platforms
helixcommit generate \
  --unreleased \
  --format text \
  --no-prs \
  --max-items 20 > release.txt

# Post to Slack
curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
  -H 'Content-Type: application/json' \
  -d "{\"text\": \"$(cat release.txt)\"}"

Email

# HTML for rich email
helixcommit generate \
  --unreleased \
  --format html \
  --out email_body.html

# Send via email (example with mailx)
cat email_body.html | mail -s "Release Notes v2.0" \
  -a "Content-Type: text/html" [e-mail]

Website

# HTML for embedding in website
helixcommit generate \
  --since-tag v1.0.0 \
  --format html \
  --no-merge-commits \
  --out public/changelog.html

# Deploy with your site
npm run build
npm run deploy

AI-powered examples

Basic AI summarization

Generate AI-enhanced release notes with OpenAI:

export OPENAI_API_KEY=sk-...

helixcommit generate \
  --unreleased \
  --use-llm \
  --openai-model gpt-4o-mini \
  --format markdown \
  --out AI_RELEASE_NOTES.md

Free AI with OpenRouter

Use free AI models via OpenRouter:

export OPENROUTER_API_KEY=sk-or-...

helixcommit generate \
  --unreleased \
  --use-llm \
  --llm-provider openrouter \
  --openrouter-model x-ai/grok-4.1-fast:free \
  --format markdown

OpenRouter’s free tier is perfect for testing AI features without cost.

Advanced AI with custom prompts

Customize AI behavior for your domain:

export OPENAI_API_KEY=sk-...

helixcommit generate \
  --unreleased \
  --use-llm \
  --openai-model gpt-4o-mini \
  --domain-scope "healthcare technology" \
  --expert-role "Product Manager" \
  --expert-role "Clinical Engineer" \
  --expert-role "Compliance Officer" \
  --rag-backend simple \
  --format markdown \
  --out RELEASE_NOTES.md

GitHub integration examples

With full GitHub enrichment

Include pull request information and links:

export GITHUB_TOKEN=ghp_...

helixcommit generate \
  --unreleased \
  --format markdown \
  --include-scopes \
  --out RELEASE_NOTES.md

GitHub integration automatically adds PR links, author information, and compare URLs.

Offline mode without GitHub

Generate notes without any external API calls:

helixcommit generate \
  --unreleased \
  --no-prs \
  --format markdown \
  --out RELEASE_NOTES.md

With caching for repeated runs

Enable caching to speed up subsequent runs:

export GITHUB_TOKEN=ghp_...
export HELIXCOMMIT_GH_CACHE=1

helixcommit generate \
  --unreleased \
  --format markdown

Filtering examples

Exclude merge commits

Create cleaner release notes by excluding merge commits:

helixcommit generate \
  --unreleased \
  --no-merge-commits \
  --format markdown

Limit commit count

Process only recent commits for faster generation:

helixcommit generate \
  --unreleased \
  --max-items 50 \
  --format markdown

Hide commit scopes

Generate notes without showing commit scopes:

helixcommit generate \
  --unreleased \
  --no-include-scopes \
  --format markdown

Output with scopes:

- **api**: Add authentication endpoint

Output without scopes:

- Add authentication endpoint

Programmatic usage

Python API basic example

Use HelixCommit as a Python library:

from datetime import datetime
from pathlib import Path
from helixcommit.changelog import ChangelogBuilder
from helixcommit.formatters.markdown import render_markdown
from helixcommit.git_client import CommitRange, GitRepository

# Initialize repository
repo = GitRepository(Path("."))

# Define commit range
commit_range = CommitRange(
    since="v1.0.0",
    until="v2.0.0",
    include_merges=False
)

# Get commits
commits = list(repo.iter_commits(commit_range))

# Build changelog
builder = ChangelogBuilder(include_scopes=True)
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs={},
    pr_index={}
)

# Render to markdown
markdown = render_markdown(changelog)
print(markdown)

# Save to file
Path("RELEASE_NOTES.md").write_text(markdown)

With AI summarization

Add AI-powered summaries programmatically:

from helixcommit.summarizer import PromptEngineeredSummarizer
from pathlib import Path

# Configure AI summarizer
summarizer = PromptEngineeredSummarizer(
    api_key="sk-...",
    model="gpt-4o-mini",
    cache_path=Path(".cache/summaries.json"),
    domain_scope="software release notes",
    expert_roles=["Product Manager", "Tech Lead"],
    rag_backend="simple"
)

# Use with ChangelogBuilder
builder = ChangelogBuilder(
    summarizer=summarizer,
    include_scopes=True
)

# Build changelog with AI
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs={},
    pr_index={}
)

Custom formatter

Create a custom output format:

from helixcommit.models import Changelog

def custom_formatter(changelog: Changelog) -> str:
    """Custom release notes formatter."""
    lines = [f"# Release {changelog.version}"]
    lines.append(f"Date: {changelog.date.strftime('%Y-%m-%d') if changelog.date else ''}")
    lines.append("")
    
    for section in changelog.sections:
        lines.append(f"## {section.title}")
        for item in section.items:
            lines.append(f"- {item.title}")
        lines.append("")
    
    return "\n".join(lines)

# Use custom formatter
output = custom_formatter(changelog)
print(output)

CI/CD integration examples

GitHub Actions

Automated release notes on tag creation:

name: Generate Release Notes

on:
  push:
    tags:
      - 'v*'

jobs:
  release-notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Full history for tags
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install HelixCommit
        run: pip install helixcommit
      
      - name: Generate release notes
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          helixcommit generate \
            --since-tag $(git describe --tags --abbrev=0 HEAD^) \
            --until-tag ${{ github.ref_name }} \
            --format markdown \
            --out RELEASE_NOTES.md
      
      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          body_path: RELEASE_NOTES.md

GitLab CI

generate_release_notes:
  stage: release
  image: python:3.11
  only:
    - tags
  script:
    - pip install helixcommit
    - |
      helixcommit generate \
        --since-tag $CI_COMMIT_BEFORE_SHA \
        --until-tag $CI_COMMIT_TAG \
        --format markdown \
        --out RELEASE_NOTES.md
  artifacts:
    paths:
      - RELEASE_NOTES.md

Jenkins

pipeline {
    agent any
    
    stages {
        stage('Generate Release Notes') {
            steps {
                sh '''
                    pip install helixcommit
                    helixcommit generate \
                        --unreleased \
                        --format markdown \
                        --out RELEASE_NOTES.md
                '''
            }
        }
        
        stage('Publish') {
            steps {
                archiveArtifacts artifacts: 'RELEASE_NOTES.md'
            }
        }
    }
}

Shell script examples

Complete release script

Automated script for creating releases:

#!/bin/bash
set -e

# Configuration
NEW_VERSION=$1
PREVIOUS_TAG=$(git describe --tags --abbrev=0)

if [ -z "$NEW_VERSION" ]; then
    echo "Usage: $0 <version>"
    exit 1
fi

echo "Creating release $NEW_VERSION from $PREVIOUS_TAG"

# Generate release notes
echo "Generating release notes..."
helixcommit generate \
    --since-tag "$PREVIOUS_TAG" \
    --until HEAD \
    --format markdown \
    --out "releases/$NEW_VERSION.md"

echo "✓ Release notes: releases/$NEW_VERSION.md"

# Create git tag
git tag -a "$NEW_VERSION" -m "Release $NEW_VERSION"

echo "✓ Created tag $NEW_VERSION"
echo ""
echo "Next steps:"
echo "  1. Review: cat releases/$NEW_VERSION.md"
echo "  2. Push: git push origin $NEW_VERSION"

Weekly changelog script

Generate weekly update summaries:

#!/bin/bash

# Get changes from last week
SINCE_DATE="7 days ago"
OUTPUT_FILE="weekly-update-$(date +%Y-%m-%d).md"

echo "Generating weekly update..."

helixcommit generate \
    --since "$SINCE_DATE" \
    --format markdown \
    --no-merge-commits \
    --out "$OUTPUT_FILE"

echo "✓ Weekly update: $OUTPUT_FILE"

# Send to team (example)
# cat "$OUTPUT_FILE" | mail -s "Weekly Update" [e-mail]

Troubleshooting examples

Debug mode

Enable verbose output for troubleshooting:

# Add debug information
helixcommit --help generate

# Check git repository status
git status
git log --oneline -10
git tag -l

# Verify GitHub token
echo $GITHUB_TOKEN | cut -c1-10

# Test with minimal options
helixcommit generate --format text --max-items 5

Handling edge cases

# Empty commits (fail early in CI)
helixcommit generate --unreleased --fail-on-empty || echo "No changes"

# Very large repositories (limit processing)
helixcommit generate --max-items 100 --no-merge-commits

# Repositories without tags
helixcommit generate --since "30 days ago" --format markdown

Next steps

CI/CD integration

Deep dive into CI/CD automation

Python API

Complete programmatic API reference

Configuration

Advanced configuration options

CLI reference

Full command-line reference