{"id":29534451,"url":"https://github.com/warengonzaga/magic-release","last_synced_at":"2025-09-09T13:33:23.000Z","repository":{"id":302302587,"uuid":"1008144212","full_name":"warengonzaga/magic-release","owner":"warengonzaga","description":"Instantly generate beautiful AI-powered changelogs from your Git commits—no setup, just magicr. 🪄📝💻","archived":false,"fork":false,"pushed_at":"2025-08-27T08:14:59.000Z","size":855,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-06T05:58:44.074Z","etag":null,"topics":["ai","artificial-intelligence","changelog","changelog-generator","changelogs","javascript","magic","nodejs"],"latest_commit_sha":null,"homepage":"https://warengonzaga.com/magic-release","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/warengonzaga.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"warengonzaga","buy_me_a_coffee":"warengonzaga"}},"created_at":"2025-06-25T05:19:59.000Z","updated_at":"2025-08-21T13:00:53.000Z","dependencies_parsed_at":"2025-08-08T18:45:28.435Z","dependency_job_id":null,"html_url":"https://github.com/warengonzaga/magic-release","commit_stats":null,"previous_names":["warengonzaga/magic-release"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/warengonzaga/magic-release","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warengonzaga%2Fmagic-release","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warengonzaga%2Fmagic-release/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warengonzaga%2Fmagic-release/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warengonzaga%2Fmagic-release/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/warengonzaga","download_url":"https://codeload.github.com/warengonzaga/magic-release/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/warengonzaga%2Fmagic-release/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274301402,"owners_count":25260001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-09T02:00:10.223Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","changelog","changelog-generator","changelogs","javascript","magic","nodejs"],"created_at":"2025-07-17T00:11:36.921Z","updated_at":"2025-09-09T13:33:22.971Z","avatar_url":"https://github.com/warengonzaga.png","language":"TypeScript","funding_links":["https://github.com/sponsors/warengonzaga","https://buymeacoffee.com/warengonzaga","https://github.com/sponsors/warengonzaga)!","https://buymeacoffee.com/warengonzaga)!"],"categories":[],"sub_categories":[],"readme":"# Magic Release 🪄 [![author/maintainer](https://img.shields.io/badge/by-warengonzaga-016eea.svg?logo=github\u0026labelColor=181717\u0026longCache=true\u0026style=flat-square)](https://warengonzaga.com/) [![nominate](https://img.shields.io/badge/nominate-%20@warengonzaga%20as%20GitHub%20Star-yellow.svg?logo=github\u0026labelColor=181717\u0026longCache=true\u0026style=flat-square)](https://stars.github.com/nominate)\n\n[![member of ossph](https://img.shields.io/badge/member-OSS%20PH-0060a0.svg?logo=github\u0026longCache=true\u0026labelColor=181717\u0026style=flat-square)](https://github.com/ossphilippines) [![sponsors](https://img.shields.io/badge/sponsor-%E2%9D%A4-%23db61a2.svg?\u0026logo=github\u0026logoColor=white\u0026labelColor=181717\u0026style=flat-square)](https://github.com/sponsors/warengonzaga) [![release](https://img.shields.io/github/release/warengonzaga/magic-release.svg?logo=github\u0026labelColor=181717\u0026color=green\u0026style=flat-square)](https://github.com/warengonzaga/magic-release/releases) [![star](https://img.shields.io/github/stars/warengonzaga/magic-release.svg?\u0026logo=github\u0026labelColor=181717\u0026color=yellow\u0026style=flat-square)](https://github.com/warengonzaga/magic-release/stargazers) [![license](https://img.shields.io/github/license/warengonzaga/magic-release.svg?\u0026logo=github\u0026labelColor=181717\u0026style=flat-square)](https://github.com/warengonzaga/magic-release/blob/main/license) [![NPM Installs](https://img.shields.io/npm/dt/magicr?color=CB3837\u0026logo=npm\u0026label=installs\u0026labelColor=181717\u0026style=flat-square)](https://npmjs.com/package/magicr)\n\n\u003c!-- ![banner](https://your-banner-url.com) --\u003e\n\n\u003e 🪄 AI-powered changelog generator that transforms your Git commit history into beautiful, professional changelogs following Keep a Changelog standards.\n\nMagic Release automatically generates comprehensive, well-structured changelogs from your Git commit history using advanced AI. Simply run `magicr` in your repository and watch as it intelligently categorizes commits, creates semantic release notes, and produces professional documentation that your users will love. ✨\n\n## ✨ Key Features\n\n- 🤖 **Multiple AI Providers** - Support for OpenAI GPT-4, Anthropic Claude, and Azure OpenAI\n- 📋 **Keep a Changelog Format** - Industry-standard changelog structure and formatting\n- 🎯 **Smart Categorization** - AI-powered commit analysis into features, fixes, breaking changes, and more\n- ⚡ **Zero Configuration** - Works out of the box with intelligent defaults\n- 🛠️ **Flexible Setup** - Interactive configuration wizard and project initialization\n- 🔍 **Range Support** - Generate changelogs for specific commit ranges or versions\n- 🚀 **No Installation Required** - Use with `npx` without global installation\n- 📝 **Conventional Commits** - Full support for conventional commit format\n- 🔗 **Smart Linking** - Automatic GitHub/GitLab issue and PR linking\n- 🎨 **Customizable** - Configurable output format and content inclusion\n\nHave suggestions? [Let me know!](https://github.com/warengonzaga/magic-release/issues)\n\n\u003e [!IMPORTANT]  \n\u003e This project is currently in beta (v0.1.0-beta). While fully functional, expect occasional improvements and refinements. Report any issues you encounter - your feedback helps make it better! 🙏\n\n## 🚀 Quick Start\n\nGet up and running in seconds with these simple steps:\n\n### Option 1: Use with npx (Recommended)\n\n```bash\n# Navigate to your project\ncd your-project\n\n# Generate changelog instantly\nnpx magicr\n\n# Or with custom options\nnpx magicr --from v1.0.0 --to HEAD --verbose\n```\n\n### Option 2: Global Installation\n\n```bash\n# Install globally\nnpm install -g magicr\n\n# Use anywhere\ncd your-project\nmagicr\n```\n\n### What happens when you run it\n\n1. 🔍 **Analyzes** your Git commit history intelligently\n2. 🤖 **Categorizes** commits using AI into proper changelog sections\n3. 📝 **Generates** a beautiful `CHANGELOG.md` following Keep a Changelog standards\n4. 🎯 **Preserves** existing changelog content and adds new entries\n5. 🔗 **Links** to issues, PRs, and commits automatically\n\n## 😎 Demo\n\n\u003e 📹 Coming soon! In the meantime, try it out in your project.\n\n### Common Commands\n\n```bash\n# Basic usage - generate changelog from all commits\nmagicr\n# or with npx\nnpx magicr\n\n# Generate changelog from specific commit range\nmagicr --from v1.0.0 --to v2.0.0\n# or with npx\nnpx magicr --from v1.0.0 --to v2.0.0\n\n# Preview without writing files\nmagicr --dry-run\n\n# Include verbose output for debugging\nmagicr --verbose\n\n# Set up API key (auto-detects OpenAI)\nmagicr --set-key sk-your-openai-key\n# or with npx\nnpx magicr --set-key sk-your-openai-key\n\n# Interactive configuration setup\nmagicr --config\n\n# Initialize project configuration\nmagicr --init\n\n# Switch or list AI providers\nmagicr --provider\n```\n\n\u003e [!NOTE]\n\u003e Magic Release supports multiple AI providers including OpenAI, Anthropic, and Azure OpenAI. By default, it uses OpenAI's `gpt-4o-mini` model. You'll need an API key from your chosen provider:\n\u003e\n\u003e **OpenAI:** Get your API key at [platform.openai.com](https://platform.openai.com/api-keys)\n\u003e **Anthropic:** Get your API key at [console.anthropic.com](https://console.anthropic.com/)\n\u003e **Azure OpenAI:** Configure through your Azure portal\n\u003e\n\u003e ```bash\n\u003e # Set up your API key (auto-detects provider)\n\u003e magicr --set-key your-api-key\n\u003e # or with npx\n\u003e npx magicr --set-key your-api-key\n\u003e\n\u003e # Or specify provider explicitly\n\u003e magicr --provider anthropic --set-key your-anthropic-key\n\u003e # or with npx\n\u003e npx magicr --provider anthropic --set-key your-anthropic-key\n\u003e ```\n\n## 📦 Installation\n\n**Requirements:**\n\n- Node.js ≥ 20.0.0\n- Yarn ≥ 4.0.0 (recommended) or npm\n\n### Global Installation\n\n```bash\n# Using npm\nnpm install -g magicr\n\n# Using yarn\nyarn global add magicr\n```\n\n### Using npx (No Installation Required)\n\n```bash\n# Run directly without installing\nnpx magicr\n\n# You can use all the same options\nnpx magicr --set-key your-api-key\nnpx magicr --from v1.0.0 --to v2.0.0\n```\n\n## 💖 Motivation\n\nCreating and maintaining changelogs is often a tedious, time-consuming task that many developers either skip or do inconsistently. Magic Release was born from the frustration of manually categorizing commits, writing user-friendly descriptions, and maintaining proper changelog formatting across multiple projects.\n\nBy leveraging the power of modern AI, Magic Release transforms this chore into an effortless, automated process. It not only saves countless hours but also ensures consistency, professionalism, and adherence to industry standards like Keep a Changelog format.\n\n**The vision:** Every project deserves a professional changelog that helps users understand what changed, when, and why - without the developer overhead. 🎯\n\n## 🏗️ Architecture\n\nMagic Release is built with a modular, extensible architecture:\n\n### Core Components\n\n- **🧠 LLM Service** - Unified interface supporting multiple AI providers\n- **📝 Commit Parser** - Analyzes conventional commits and semantic patterns  \n- **🏷️ Tag Manager** - Handles version detection and semantic versioning\n- **📊 Git Service** - Interfaces with Git repository operations\n- **📄 Changelog Generator** - Produces Keep a Changelog format output\n- **⚙️ Configuration Store** - Secure credential and settings management\n\n### Supported AI Providers\n\n- **OpenAI** - GPT-4, GPT-3.5 Turbo models\n- **Anthropic** - Claude 3 family models\n- **Azure OpenAI** - Enterprise-grade AI with custom deployments\n\n### Data Flow\n\n1. **Repository Analysis** → Extract commits, tags, and metadata\n2. **AI Processing** → Categorize and enhance commit descriptions  \n3. **Content Generation** → Create structured changelog entries\n4. **Format \u0026 Output** → Generate final changelog following standards\n\n## 🎯 Contributing\n\nWe welcome contributions! Here's how you can help make Magic Release even better:\n\n### Ways to Contribute\n\n- 🐛 **Report bugs** - Found an issue? [Create a bug report](https://github.com/warengonzaga/magic-release/issues/new?template=bug_report.md)\n- 💡 **Request features** - Have an idea? [Suggest a feature](https://github.com/warengonzaga/magic-release/issues/new?template=feature_request.md)\n- 📝 **Improve docs** - Help us make the documentation clearer\n- 🔧 **Submit PRs** - Fix bugs or implement new features\n- ⭐ **Give feedback** - Share your experience using Magic Release\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/warengonzaga/magic-release.git\ncd magic-release\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm test\n\n# Build the project\nnpm run build\n\n# Test locally\nnpm run dev\n```\n\n### Contributing Guidelines\n\n- Please read our [Contributing Guide](https://github.com/warengonzaga/magic-release/blob/main/CONTRIBUTING.md) first\n- Submit pull requests to the `dev` branch\n- Follow the existing code style and conventions\n- Add tests for new features\n- Update documentation as needed\n\n**Your contributions help make changelog generation effortless for developers worldwide!** 🌍\n\n## 🐛 Issues\n\nPlease report any issues and bugs by [creating a new issue here](https://github.com/warengonzaga/magic-release/issues/new/choose), also make sure you're reporting an issue that doesn't exist. Any help to improve the project would be appreciated. Thanks! 🙏✨\n\n## 🙏 Sponsor\n\nLike this project? Leave a star! ⭐⭐⭐⭐⭐\n\nWant to support my work and get some perks? [Become a sponsor](https://github.com/sponsors/warengonzaga)! 💖\n\nOr, you just love what I do? [Buy me a coffee](https://buymeacoffee.com/warengonzaga)! ☕\n\nRecognized my open-source contributions? [Nominate me](https://stars.github.com/nominate) as GitHub Star! 💫\n\n## 📋 Code of Conduct\n\nRead the project's [code of conduct](https://github.com/warengonzaga/magic-release/blob/main/CODE_OF_CONDUCT.md).\n\n## 📃 License\n\nThis project is licensed under [GNU General Public License v3.0](https://opensource.org/licenses/GPL-3.0).\n\n## 📝 Author\n\nThis project is created by [Waren Gonzaga](https://github.com/warengonzaga), with the help of awesome [contributors](https://github.com/warengonzaga/magic-release/graphs/contributors).\n\n[![contributors](https://contrib.rocks/image?repo=warengonzaga/magic-release)](https://github.com/warengonzaga/magic-release/graphs/contributors)\n\n💻 with ❤️ by [Waren Gonzaga](https://warengonzaga.com/) and [Him](https://www.youtube.com/watch?v=HHrxS4diLew\u0026t=44s) 🙏\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarengonzaga%2Fmagic-release","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwarengonzaga%2Fmagic-release","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwarengonzaga%2Fmagic-release/lists"}