🎯 Contribute to Magic Release

Any contributions are welcome, encouraged, and valued. See the following information below for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for the maintainer and smooth out the experience for all involved. The community looks forward to your contributions. 🎉✌✨

📋 Code of Conduct

This project and everyone participating in it is governed by the project's Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@warengonzaga.com.

💖 How to Contribute

There are many ways to contribute to this open source project. Any contributions are welcome and appreciated. Be sure to read the details of each section for you to start contributing.

🧬 Development

If you can write code then create a pull request to this repo and I will review your code. Please consider submitting your pull request to the dev branch. I will auto reject if you submit your pull request to the main branch.

🔧 Development Setup

To get started with development:

Fork and clone the repository

git clone https://github.com/your-username/magic-release.git
cd magic-release

Install dependencies
```
pnpm install
```
⚠️ Important: This project uses PNPM as the package manager. Ensure you have PNPM 9.0+ installed.

Set up your development environment

# Build the project
pnpm build

# Start development with watch mode
pnpm dev

Test the CLI locally

# Link the package globally for testing
pnpm link -g

# Test the CLI in a git repository
cd /path/to/your/test-repo
magicr --help

🏗️ Development Commands

# Development with auto-reload
pnpm dev

# Build for production
pnpm build

# Type checking only
pnpm type-check

# Clean build artifacts
pnpm clean

# Linting
pnpm lint              # Fix linting issues
pnpm lint:check        # Check linting without fixing
pnpm lint:security     # Security-focused linting

# Testing
pnpm test              # Run test suite
pnpm test:watch        # Run tests in watch mode
pnpm test:coverage     # Run tests with coverage report

# Security scanning
pnpm secure:code       # Code security analysis
pnpm secure:deps       # Dependency vulnerability check

🏛️ Project Structure

src/
├── index.ts                    # Main library entry point
├── cli/                        # CLI application
│   ├── index.tsx              # CLI entry point
│   ├── App.tsx                # Main CLI app component
│   └── commands/              # CLI command handlers
├── constants/                  # Application constants
│   └── index.ts
├── core/                       # Core business logic
│   ├── MagicRelease.ts        # Main orchestrator class
│   ├── generator/             # Changelog generation
│   │   ├── ChangelogParser.ts
│   │   └── KeepChangelogGenerator.ts
│   ├── git/                   # Git operations
│   │   ├── CommitParser.ts
│   │   ├── GitService.ts
│   │   └── TagManager.ts
│   └── llm/                   # LLM integrations
│       ├── LLMService.ts
│       ├── ProviderFactory.ts
│       ├── prompts/           # AI prompts
│       └── providers/         # LLM provider implementations
├── types/                      # TypeScript type definitions
│   ├── index.ts
│   └── interfaces.ts
└── utils/                      # Utility functions
    ├── config-store.ts
    ├── errors.ts
    ├── logger.ts
    ├── package-info.ts
    └── project-config.ts

🎯 Development Guidelines

TypeScript First: All code must be written in TypeScript with strict type checking
Error Handling: Implement comprehensive error handling with detailed error messages
Package Manager: Use PNPM exclusively (9.0+)
Code Style: Follow existing patterns and maintain consistency
Environment: Use Node.js 20+ for development
Testing: Write tests for new features and bug fixes
Security: Follow secure coding practices, especially for API integrations
Documentation: Update documentation for new features and changes

🧪 Testing Guidelines

When contributing to this project:

Write unit tests for new functionality
Test CLI commands manually with various git repositories
Verify LLM provider integrations work correctly
Test error handling for edge cases
Ensure proper handling of different git repository structures
Test with different changelog formats and conventions
Verify security measures (no API keys in logs, proper input validation)

🔍 Code Review Process

Pre-submission checks:
- Code builds without errors (pnpm build)
- TypeScript type checking passes (pnpm type-check)
- All tests pass (pnpm test)
- Linting passes (pnpm lint:check)
- Security checks pass (pnpm lint:security)
- CLI functionality works end-to-end
- No sensitive data exposed in outputs
Pull Request Requirements:
- Target the dev branch (PRs to main will be rejected)
- Include clear description of changes
- Follow existing code patterns
- Update documentation if needed
- Add or update tests for new functionality
- Ensure no breaking changes without version bump

🏗️ Architecture & Technical Details

🔄 How the System Works

Magic Release is an AI-powered changelog generator that analyzes your git commit history and generates professional changelogs using Large Language Models (LLMs).

📥 Changelog Generation Flow

Git Analysis: Scans git repository for commits since last release tag
Commit Parsing: Extracts commit messages, authors, and metadata
Content Processing: Categorizes commits by type (features, fixes, etc.)
AI Enhancement: Uses LLM to generate professional changelog entries
Format Generation: Outputs changelog in Keep a Changelog format
File Integration: Updates CHANGELOG.md with new release section

🤖 LLM Integration Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Git Commits   │───▶│   AI Provider   │───▶│   Changelog     │
│                 │    │   (OpenAI,      │    │   Output        │
│   Raw History   │    │   Anthropic,    │    │                 │
│                 │    │   Azure, etc.)  │    │   Formatted     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🔧 Configuration Management

Secure Config Store: API keys stored using the conf package for security
Project Config Files: Project-specific settings in .magicrrc files
CLI Arguments: Runtime options and overrides
Automatic Detection: Smart defaults based on repository structure

⚙️ Configuration Requirements

LLM Provider Setup

Magic Release uses a secure configuration store to manage API keys. Choose one of the supported providers:

OpenAI (Default):

# Set API key via CLI
magicr --set-api-key sk-your-openai-key

# Or set without validation (for offline setup)
magicr --set-api-key-unsafe sk-your-openai-key

Anthropic:

# First set up Anthropic as your provider
magicr --config  # Use interactive config to set provider and API key

Azure OpenAI:

# Configure Azure settings via interactive config
magicr --config  # Set provider to azure and configure endpoint/keys

Project Configuration

Create a .magicrrc file in your project root for project-specific settings:

# Generate a sample configuration file
magicr --generate-config

Example .magicrrc file:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "temperature": 0.1,
    "maxTokens": 150
  },
  "changelog": {
    "filename": "CHANGELOG.md",
    "includeCommitLinks": true,
    "includePRLinks": true,
    "includeIssueLinks": true
  },
  "git": {
    "tagPattern": "^v?\\d+\\.\\d+\\.\\d+",
    "remote": "origin"
  },
  "rules": {
    "minCommitsForUpdate": 1,
    "includePreReleases": false,
    "groupUnreleasedCommits": true
  }
}

🏗️ Installation & Deployment

📦 Global Installation

# Install globally via npm
npm install -g magicr

# Install globally via pnpm
pnpm add -g magicr

# Verify installation
magicr --version

🔧 Local Development Installation

# Clone repository
git clone https://github.com/warengonzaga/magic-release.git
cd magic-release

# Install dependencies
pnpm install

# Build project
pnpm build

# Link for global usage
pnpm link -g

⚙️ Usage Examples

# Basic usage - generate changelog for current repository
magicr

# Set up API key
magicr --set-api-key sk-your-openai-key

# Interactive configuration
magicr --config

# Generate sample project configuration
magicr --generate-config

# Test API key connectivity
magicr --test-api-key sk-your-openai-key

# Initialize project (checks git repo, creates CHANGELOG.md if needed)
magicr --init

# Show help and available options
magicr --help

🛡️ Security Best Practices

API Key Management

Store API keys using the built-in secure config store (magicr --set-api-key)
Never commit API keys to version control
Use .gitignore to exclude configuration files with sensitive data
Rotate API keys regularly
Monitor API usage for unusual activity

Input Validation

All git repository paths are validated
Commit message content is sanitized
File paths prevent directory traversal attacks
Configuration values are type-checked and validated

Output Security

Generated changelogs are sanitized to prevent injection attacks
No sensitive information (API keys, internal paths) included in output
Proper error handling prevents information disclosure
Audit logging for security-relevant operations

🐞 Bug Reports & Feature Requests

🐞 Reporting Bugs

For security bugs, please follow our Security Policy.

For other bugs, please create an issue with:

Clear description of the problem
Steps to reproduce the issue
Expected vs actual behavior
Environment details (Node.js version, OS, LLM provider)
Relevant logs or error messages (without sensitive data)
Git repository characteristics (if relevant)

💡 Feature Requests

We welcome suggestions for new features! Please create an issue with:

Clear description of the feature
Use case and benefits
Any implementation considerations
Examples or mockups if applicable
Integration considerations with existing functionality

📖 Documentation

Improvements to documentation are always welcome! This includes:

README updates
Code comments and JSDoc documentation
CLI help text improvements
Configuration examples
Troubleshooting guides
API documentation
Fixing typos or clarifying existing documentation

🎯 Project Status

Current Focus (v0.1.x)

Core changelog generation functionality
Support for major LLM providers (OpenAI, Anthropic, Azure)
CLI interface with essential commands
Git repository analysis and commit parsing
Keep a Changelog format support
Secure configuration management

Potential Future Enhancements

Additional changelog formats
Enhanced commit categorization
Custom prompt templates
Improved error handling and user experience
Performance optimizations

Note: This project is in active development. Feature requests and contributions are welcome!

📚 Resources

Keep a Changelog - Changelog format specification
Semantic Versioning - Version numbering guidelines
Conventional Commits - Commit message conventions
OpenAI API Documentation
Anthropic API Documentation

💻 with ❤️ by Waren Gonzaga, WG Technology Labs, and Him 🙏

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

🎯 Contribute to Magic Release

📋 Code of Conduct

💖 How to Contribute

🧬 Development

🔧 Development Setup

🏗️ Development Commands

🏛️ Project Structure

🎯 Development Guidelines

🧪 Testing Guidelines

🔍 Code Review Process

🏗️ Architecture & Technical Details

🔄 How the System Works

📥 Changelog Generation Flow

🤖 LLM Integration Architecture

🔧 Configuration Management

⚙️ Configuration Requirements

LLM Provider Setup

Project Configuration

🏗️ Installation & Deployment

📦 Global Installation

🔧 Local Development Installation

⚙️ Usage Examples

🛡️ Security Best Practices

API Key Management

Input Validation

Output Security

🐞 Bug Reports & Feature Requests

🐞 Reporting Bugs

💡 Feature Requests

📖 Documentation

🎯 Project Status

Current Focus (v0.1.x)

Potential Future Enhancements

📚 Resources

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

🎯 Contribute to Magic Release

📋 Code of Conduct

💖 How to Contribute

🧬 Development

🔧 Development Setup

🏗️ Development Commands

🏛️ Project Structure

🎯 Development Guidelines

🧪 Testing Guidelines

🔍 Code Review Process

🏗️ Architecture & Technical Details

🔄 How the System Works

📥 Changelog Generation Flow

🤖 LLM Integration Architecture

🔧 Configuration Management

⚙️ Configuration Requirements

LLM Provider Setup

Project Configuration

🏗️ Installation & Deployment

📦 Global Installation

🔧 Local Development Installation

⚙️ Usage Examples

🛡️ Security Best Practices

API Key Management

Input Validation

Output Security

🐞 Bug Reports & Feature Requests

🐞 Reporting Bugs

💡 Feature Requests

📖 Documentation

🎯 Project Status

Current Focus (v0.1.x)

Potential Future Enhancements

📚 Resources