ReleaseCraft 0.5.3

🎯 ReleaseCraft

ReleaseCraft is an automated release notes generator that transforms GitHub pull requests into beautifully formatted release notes. Stop writing release notes manually—let ReleaseCraft do it for you!

🌐 Visit our website | 📚 Documentation | 💬 Community

---

📦 Current Release Status

Production Ready (v1.0):

• ✅ GitHub connector with Octokit
• ✅ Markdown release notes generator
• ✅ CLI console application
• ✅ Integration tests with real GitHub API
• ✅ Comprehensive documentation
• ✅ Marketing website with interactive demos

In Development (Code Exists, Not Production):

• 🔄 AI summarization (OpenAI GPT-4)
• 🔄 Multiple output formats (JSON, HTML, CSV)

Planned Features:

• ⏳ Config file support (.releasecraftrc.json)
• ⏳ GitHub Action automation
• ⏳ NuGet package publication
• ⏳ GitHub Marketplace listing
• ⏳ Web UI and REST API
• ⏳ SaaS infrastructure (Auth, Billing, Monitoring)

Note: This is an active development project. Features marked 🔄 exist in the codebase but are experimental and not production-ready yet.

---

✨ Features

• 🚀 Automated Generation - Fetches merged PRs between two git tags automatically
• 📊 Smart Categorization - Organizes changes by labels (features, bugs, docs, etc.)
• 🤖 AI-Powered Summarization - Generate intelligent release summaries with OpenAI GPT-4
• 🎭 Tone Control - Adapt content for different audiences (Professional, Casual, Marketing, Technical)
• 🎨 Multiple Formats - Supports Markdown, JSON, HTML, and CSV formats
• ⚡ CLI & Library - Use as a command-line tool or integrate into your .NET application
• 🔌 GitHub Integration - Seamless integration with GitHub API via Octokit
• 🏗️ Extensible Architecture - Hexagonal design allows custom adapters and generators

🚀 Quick Start

Prerequisites

• .NET 10.0 SDK or later
• GitHub Personal Access Token (optional, but recommended for higher rate limits)

Installation

Option 1: Install as Global Tool (Recommended)

Install the ReleaseCraft CLI as a global .NET tool:

dotnet tool install -g ReleaseCraft.CLI

Then use it from anywhere:

releasecraft --owner microsoft --repo vscode --from-tag 1.84.0 --to-tag 1.85.0

Option 2: Install as Library

Add ReleaseCraft packages to your .NET project:

# Install all components (recommended)
dotnet add package ReleaseCraft

# Or install specific components
dotnet add package ReleaseCraft.Engine           # Core interfaces and models
dotnet add package ReleaseCraft.Connectors.GitHub # GitHub integration
dotnet add package ReleaseCraft.Templates         # Markdown, JSON, HTML, CSV generators
dotnet add package ReleaseCraft.AI               # AI-powered summarization

Option 3: Clone and Build from Source

Clone and Build:

git clone https://github.com/releasecraft/releasecraft-core.git
cd releasecraft-core
dotnet build ReleaseCraft.slnx -c Release

Basic Usage

Generate release notes from the command line:

# Using global tool
releasecraft --owner microsoft --repo vscode --from-tag 1.84.0 --to-tag 1.85.0

# Or from source
cd src/ReleaseCraft.CLI
dotnet run -- --owner microsoft --repo vscode --from-tag 1.84.0 --to-tag 1.85.0

With authentication (recommended):

export GITHUB_TOKEN="your_github_token_here"
releasecraft --owner kubernetes --repo kubernetes --from-tag v1.28.0 --to-tag v1.29.0

Save to a file:

releasecraft --owner facebook --repo react --from-tag v18.0.0 --to-tag v18.2.0 --output release-notes.md

With AI summarization:

export OPENAI_API_KEY="sk-your-openai-key"
releasecraft --owner microsoft --repo vscode --from-tag 1.84.0 --to-tag 1.85.0 --ai

With AI and custom tone:

releasecraft --owner facebook --repo react --from-tag v18.0.0 --to-tag v18.2.0 --ai --tone marketing

🤖 AI Features (v0.5+) 🔄 IN DEVELOPMENT

Note: AI features exist in the codebase but are not yet production-ready. Use with caution.

ReleaseCraft includes AI-powered summarization capabilities (experimental) to generate intelligent, context-aware release notes.

Setup

1. Get an OpenAI API key from OpenAI Platform
2. Set environment variable:

   export OPENAI_API_KEY="sk-your-openai-key-here"
   

Usage

Enable AI with default settings (Professional tone):

dotnet run -- --owner microsoft --repo vscode --from-tag 1.84.0 --to-tag 1.85.0 --ai

Specify a tone style:

# Professional (default) - formal, business-appropriate
dotnet run -- --owner org --repo repo --from-tag v1.0 --to-tag v2.0 --ai --tone professional

# Casual - friendly, conversational for internal teams
dotnet run -- --owner org --repo repo --from-tag v1.0 --to-tag v2.0 --ai --tone casual

# Marketing - engaging, benefit-focused for public releases
dotnet run -- --owner org --repo repo --from-tag v1.0 --to-tag v2.0 --ai --tone marketing

# Technical - precise, detailed for developer audiences
dotnet run -- --owner org --repo repo --from-tag v1.0 --to-tag v2.0 --ai --tone technical

Example Output

Without AI:

# v1.5.0

**Release Date:** 2024-02-03

## 🚀 Features
- Add dark mode support [#127](https://github.com/owner/repo/pull/127) by @user1
- Implement new search algorithm [#128](https://github.com/owner/repo/pull/128) by @user2

With AI Summarization:

# v1.5.0

**Release Date:** 2024-02-03

**Summary:** This release focuses on user experience improvements with dark mode support and significantly faster search performance. Several critical security fixes are also included.

## 🚀 Features
- Add dark mode support [#127](https://github.com/owner/repo/pull/127) by @user1
- Implement new search algorithm [#128](https://github.com/owner/repo/pull/128) by @user2

Configuration File

Create .releasecraftrc.json in your project root:

{
  "owner": "microsoft",
  "repo": "vscode",
  "ai": {
    "enabled": true,
    "apiKey": "env:OPENAI_API_KEY",
    "model": "gpt-4-turbo",
    "tone": "professional",
    "maxTokens": 1000,
    "features": {
      "summarization": true,
      "toneControl": true
    }
  }
}

Cost Considerations

AI features use OpenAI's GPT-4 Turbo model. Estimated costs:

• Small release (10 PRs): ~$0.02
• Medium release (50 PRs): ~$0.10
• Large release (200 PRs): ~$0.40

Cost optimization:

• Set maxTokens to limit usage per request
• Disable AI when not needed (don't use --ai flag)
• Use cheaper models like gpt-3.5-turbo in config

Security

• Never commit API keys to source control
• Always use environment variables: OPENAI_API_KEY
• API keys are never sent to GitHub or stored in generated files
• AI is opt-in only - disabled by default

📚 Documentation

• Installation Guide - Detailed setup instructions
• CLI Usage - Command-line examples and troubleshooting
• GitHub Action - Using ReleaseCraft as a GitHub Action
• AI Features - AI summarization, tone control, and pricing
• API Reference - Using ReleaseCraft as a library
• Configuration - Customizing category mappings
• Examples - Sample outputs and use cases
• Contributing - How to contribute to the project

💡 Usage Examples

CLI Examples

Generate release notes between two tags:

dotnet run -- -o nodejs -r node -f v20.0.0 -t v20.1.0

With custom output path:

dotnet run -- --owner rails --repo rails --from-tag v7.0.0 --to-tag v7.1.0 --output docs/CHANGELOG_v7.1.0.md

Library Usage

Use ReleaseCraft programmatically in your .NET application:

using ReleaseCraft.Connectors.GitHub;
using ReleaseCraft.Templates;
using ReleaseCraft.Engine.Ports;

// Configure GitHub connection
var githubOptions = new GitHubOptions
{
    ProductName = "MyApp",
    Token = Environment.GetEnvironmentVariable("GITHUB_TOKEN") ?? string.Empty
};

// Create services
var changeSource = new GitHubChangeSource(githubOptions);
var generator = new MarkdownReleaseNotesGenerator(new MarkdownGeneratorOptions());

// Generate release notes
var changes = await changeSource.GetMergedPullRequestsBetweenTagsAsync(
    owner: "dotnet",
    repo: "aspnetcore",
    fromTag: "v8.0.0",
    toTag: "v8.1.0",
    ct: CancellationToken.None
);

var releaseNotes = generator.Generate(
    changes,
    version: "v8.1.0",
    releaseDate: DateTimeOffset.UtcNow
);

Console.WriteLine(releaseNotes);

🎨 Configuration

ReleaseCraft categorizes pull requests based on their labels. Default categories:

Category	Labels	Priority
🔒 Security	security, vulnerability, cve	1
⚠️ Breaking Changes	breaking, breaking-change	2
🚀 Features	feature, enhancement	3
🐛 Bug Fixes	bug, fix	4
⚡ Performance	performance, optimization, speed	5
📝 Documentation	documentation, docs	6
🔧 Maintenance	chore, maintenance, refactor	7
Other Changes	(unlabeled PRs)	Default

See Configuration Guide for customization options.

🔄 GitHub Action (v1.1+) ⏳ PLANNED

Note: GitHub Action is not yet implemented. This is planned for v1.1.

ReleaseCraft will be available as a GitHub Action (planned) to automatically generate and update release notes when new releases are created.

Quick Start

Add this to your repository at .github/workflows/release-notes.yml:

name: Generate Release Notes

on:
  release:
    types: [created]

jobs:
  release-notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      
      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'
      
      - name: Generate Release Notes
        uses: releasecraft/releasecraft-core@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Features

• ✅ Automatic Trigger - Runs on release creation/edit
• ✅ Auto-Detection - Automatically finds previous release tag
• ✅ AI Support - Optional AI summarization
• ✅ Multiple Formats - Markdown, JSON, HTML, CSV
• ✅ No Setup Required - Just add the workflow file

With AI Summarization

- name: Generate AI-Enhanced Release Notes
  uses: releasecraft/releasecraft-core@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    enable-ai: true
    ai-tone: marketing
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

For complete GitHub Action documentation, see GitHub Action Guide

🏗️ Architecture

ReleaseCraft follows Hexagonal (Ports & Adapters) Architecture:

┌─────────────────────────────────────────┐
│          User Interface Layer           │
│    CLI  │  REST API  │  GitHub Action   │
└─────────────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────┐
│           Core Domain Layer             │
│  IGitChangeSource  │  IReleaseNotes     │
│                    │  Generator         │
└─────────────────────────────────────────┘
          ↓                    ↓
┌──────────────────┐  ┌──────────────────┐
│  GitHub Adapter  │  │  Markdown Gen    │
│  (Octokit)       │  │  JSON/HTML/CSV   │
└──────────────────┘  └──────────────────┘

For detailed architecture documentation, see ARCHITECTURE.md.

🛠️ Development

Build the Project

dotnet build ReleaseCraft.slnx -c Release

Run Tests

dotnet test ReleaseCraft.slnx

Project Structure

releasecraft-core/
├── src/
│   ├── ReleaseCraft.Engine/              # Core interfaces and models
│   ├── ReleaseCraft.Connectors.GitHub/   # GitHub API adapter
│   ├── ReleaseCraft.Templates/           # Output generators
│   └── ReleaseCraft.CLI/                # CLI application
├── tests/
│   ├── ReleaseCraft.Engine.Tests/        # Unit tests
│   └── ReleaseCraft.Integration.Tests/   # Integration tests
└── docs/                                 # Documentation

See DEVELOPMENT.md for contributing guidelines.

🔒 Authentication

ReleaseCraft supports two authentication methods:

1. Environment Variable (Recommended):

   export GITHUB_TOKEN="ghp_your_token_here"
   

2. Command-line Flag:

   dotnet run -- --owner owner --repo repo --from-tag v1.0 --to-tag v2.0 --token ghp_your_token
   

Creating a GitHub Token:

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
2. Click "Generate new token (classic)"
3. Select scopes: public_repo (for public repos) or repo (for private repos)
4. Copy the token and store it securely

See CLI Usage Guide for more details.

🤝 Contributing

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

Quick Contribution Flow:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following our coding standards
4. Run tests (dotnet test)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📋 Roadmap

✅ Phase 1 — Core Engine (MVP v0.1) — COMPLETE

• ✅ GitHub connector with Octokit
• ✅ Markdown release notes generator
• ✅ CLI console application
• ✅ Integration tests
• ✅ Documentation

Phase 2 — Intelligence (v0.5) 🔄 IN DEVELOPMENT

• 🔄 AI summarization with OpenAI GPT-4 (code exists, not in prod)
• 🔄 Tone control (Professional, Casual, Marketing, Technical) (code exists, not in prod)
• 🔄 Config file support (.releasecraftrc.json) (code exists, not in prod)
• ⏳ Smart categorization (planned for v0.5.1)
• ⏳ Audience modes (Client vs Internal) (planned)

Phase 3 — Platform (v1.0) ⏳ PLANNED

• ⏳ REST API (planned)
• ⏳ Multiple output formats (JSON, HTML, CSV) (code exists, not in prod)
• ⏳ Web UI (planned)

Phase 4 — Ecosystem (v1.1+) ⏳ PLANNED

• ⏳ GitHub Action for automation (not started)
• ⏳ NuGet package publishing (not started)
• ⏳ Marketplace distribution (not started)

See VISION.md for the complete long-term vision.

📚 Project Documentation

Comprehensive documentation for understanding and contributing to ReleaseCraft:

• VISION.md - Product vision, strategy, and business model
• PRD.md - Product requirements document with detailed feature specifications
• PROJECT.md - Technical project overview and architecture summary
• ARCHITECTURE.md - Detailed technical architecture and design patterns
• DEVELOPMENT.md - Developer setup, workflow, and contribution guide
• docs/ - API reference, CLI usage, and examples

Start with VISION.md to understand the product goals, then dive into technical details with ARCHITECTURE.md.

🌐 Website

The ReleaseCraft website is now live at releasecraft.io, featuring:

• Product information and documentation
• Interactive demos and examples
• Community resources and support
• Download links and installation guides
• Privacy-focused design with no invasive tracking

Built with Angular 21, the website achieved a 9.2/10 quality score in business analysis review.

📊 Product-Market Fit Validation

We're validating demand for ReleaseCraft before investing in Phase 3 (Web UI + SaaS). Help us by:

• ⭐ Star this repository if you find it useful
• 📦 Download and try the CLI from NuGet
• 📧 Join our early access list on releasecraft.io
• 💬 Share feedback in GitHub Discussions

We're tracking key metrics (stars, downloads, signups) to make data-driven decisions about future development. See ISSUE-26-IMPLEMENTATION.md for details on our automated PMF validation process.

Current Status: v1.1 - Website Improvements (post-launch optimizations)
Next Phase Decision: Based on community interest and usage patterns

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Built with Octokit.NET for GitHub API integration
• Inspired by tools like Release Drafter

📞 Support

• 📖 Documentation
• 🐛 Report a Bug
• 💡 Request a Feature
• 💬 Discussions

---

Made with ❤️ by the ReleaseCraft team