ReleaseCraft.Engine 1.1.0-preview

🎯 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 (coming soon) | 📚 Documentation | 💬 Community

📦 Current Release Status

Production Ready (v0.1 MVP):

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

In Development (Code Exists, Not Production):

• 🔄 AI summarization (OpenAI GPT-4)
• 🔄 Multiple output formats (JSON, HTML, CSV)
• 🔄 REST API (ASP.NET Core)
• 🔄 Web UI (Blazor WebAssembly)

Planned Features:

• ⏳ Config file support (.releasecraftrc.json)
• ⏳ GitHub Action automation
• ⏳ NuGet package publication
• ⏳ GitHub Marketplace listing
• ⏳ 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
• 🖥️ Web UI - Modern graphical interface for non-technical users
• 🌐 REST API - HTTP endpoints for programmatic access and integrations
• ⚡ 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

🌐 REST API (v1.0+) 🔄 IN DEVELOPMENT

Note: REST API exists in the codebase but is not yet production-ready. Use for local development only.

ReleaseCraft includes a REST API (experimental) for programmatic access and integrations.

Quick Start

Start the API server:

cd src/ReleaseCraft.API
dotnet run

The API will be available at http://localhost:5026 with Swagger UI at http://localhost:5026/swagger/ui

API Endpoints

• POST /api/release-notes - Generate release notes
• POST /api/validate - Validate repository and tags
• GET /api/formats - List supported formats
• GET /api/health - Health check

Example: Generate Release Notes via API

curl -X POST http://localhost:5026/api/release-notes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ghp_your_token" \
  -d '{
    "owner": "microsoft",
    "repo": "vscode",
    "fromTag": "1.90.0",
    "toTag": "1.90.1",
    "format": "markdown"
  }'

For full API documentation, see src/ReleaseCraft.API/README.md

##🖥️ Web UI (v1.0+) 🔄 IN DEVELOPMENT

Note: Web UI exists in the codebase but is not yet production-ready. Use for local development only.

ReleaseCraft includes a modern web interface (experimental) for generating release notes without using the command line.

Perfect for product managers, marketing teams, and anyone who prefers a graphical interface.

Features

• 📝 Easy Configuration - Input repository details through a clean form
• 🎨 Format Selection - Choose from Markdown, JSON, HTML, or CSV
• 👥 Audience Modes - Internal (technical) or Client (non-technical)
• 🤖 AI Enhancement - Optional AI features with tone control
• 👁️ Live Preview - See your release notes in real-time
• 📥 Export Options - Download or copy to clipboard

Quick Start

1. Start the API server:

cd src/ReleaseCraft.API
dotnet run

2. Start the Web UI:

cd src/ReleaseCraft.Web
dotnet run

3. Open your browser: Navigate to https://localhost:5001 and start generating release notes!

Screenshots

Deployment

The Web UI can be deployed to:

• Azure Static Web Apps (recommended)
• GitHub Pages
• Any static web hosting (Netlify, Vercel, AWS S3, etc.)

For deployment instructions, see docs/WEB_UI_DEPLOYMENT.md

🤖 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:

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.ConsoleApp/          # 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) 🔄 IN DEVELOPMENT

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

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
• website/ - Marketing website and landing page (Next.js)

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

🌐 Marketing Website

A professional landing page has been created in the website/ directory:

• Tech Stack: Next.js 16, TypeScript, Tailwind CSS
• Features: Responsive design, SEO optimized, fast static export
• Pages: Landing, Pricing (5 tiers), Features, Demo
• Deployment: Ready for Vercel, Netlify, Cloudflare Pages, or any static host

To run the website locally:

cd website
npm install
npm run dev

Visit http://localhost:3000 to see the site.

For deployment instructions, see website/DEPLOYMENT.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 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