feat: add simple release workflow

[yibeichan]

Summary

This PR implements a simple, maintainable release workflow to replace the complex auto-based approach from PR #7.

Changes

1. Release Workflow (.github/workflows/release.yml)

• Manual trigger only - releases are intentional, not automatic
• Version validation - ensures proper semantic versioning format
• Automated version updates - updates pyproject.toml and cookiecutter.json
• Git tag creation - creates annotated tags
• Automatic release notes - uses GitHub's built-in functionality
• Security - uses only built-in GITHUB_TOKEN, no additional secrets needed

2. Documentation

CHANGELOG.md

• Follows Keep a Changelog format
• Documents all notable changes
• Includes unreleased changes from recent PRs

CONTRIBUTING.md

• Development setup instructions
• Testing guidelines
• Commit message conventions
• Pull request process
• Detailed release process documentation

Why This Approach?

As analyzed by our DevOps automation engineer:

• ✅ Simpler - No external dependencies or complex configuration
• ✅ Secure - Uses built-in GITHUB_TOKEN, no additional secrets
• ✅ Manual control - Releases are intentional, not automatic
• ✅ Compatible - Works with existing test workflows
• ✅ Maintainable - Easy for contributors to understand

How to Use

1. Go to Actions → Release workflow
2. Click "Run workflow"
3. Enter version (e.g., 1.1.0) and release type
4. Workflow handles the rest:
   • Updates versions
   • Creates tag
   • Generates release

Related Issues

Closes the discussion from PR #7 by implementing a simpler alternative.

Testing

• Workflow syntax validated
• Version update logic tested
• Documentation reviewed for clarity

[gemini-code-assist]

Summary of Changes

Hello @yibeichan, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

I've introduced a new, simplified release workflow for the project, moving away from a more complex, automated approach. This change aims to make releases more intentional and easier to manage. Alongside the new workflow, I've added comprehensive documentation for both project changes and contribution guidelines, ensuring clarity for all contributors and maintainers.

Highlights

• New Release Workflow: I've implemented a new GitHub Actions workflow (.github/workflows/release.yml) that allows for manual, intentional releases. This workflow handles version validation, automated updates to pyproject.toml and cookiecutter.json, Git tag creation, and automatic generation of release notes. It's designed to be secure by using only the built-in GITHUB_TOKEN.
• Comprehensive Changelog: I've added a CHANGELOG.md file that adheres to the Keep a Changelog format and Semantic Versioning. This file documents all notable changes, including both unreleased changes and those from the initial 1.0.0 release.
• Updated Contributing Guidelines: I've introduced a CONTRIBUTING.md file that provides detailed guidelines for contributors. This includes instructions for development setup, testing, code style, commit message conventions, and the pull request process. Crucially, it also documents the new release process, explaining how maintainers can use the GitHub Actions workflow to create new releases.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new manual release workflow and adds corresponding documentation in CHANGELOG.md and CONTRIBUTING.md. The new documentation is clear and well-structured. My primary feedback is to consider automating the manual step of updating the CHANGELOG.md file. Given that the project uses conventional commits, this can be accomplished with existing GitHub Actions, which would make the release process more robust and less susceptible to human error.

[gemini-code-assist]

The manual post-release step for updating CHANGELOG.md is well-documented, but it's a manual process that can be error-prone. If this step is forgotten, the changelog can become out of sync with the project's releases.

Since the project has adopted Conventional Commits, I recommend automating this step. You could integrate a tool like release-drafter or git-cliff into the release workflow. This would allow you to:

• Automatically generate changelog entries from commits.
• Update CHANGELOG.md with the new version's changes.
• Prepare the Unreleased section for the next development cycle.

Automating this would make the release process more robust and reduce the manual burden on maintainers.

[yibeichan]

🎯 Addressed Gemini's Feedback: Automated Changelog Generation

Thank you @gemini-code-assist for the excellent feedback about automating the manual changelog update process!

✅ Solution Implemented: Hybrid Release Approach

We've implemented a hybrid approach that combines:

• Manual release workflow (for intentional versioning appropriate to cookiecutter templates)
• Automated changelog generation using git-cliff from conventional commits

🔧 Changes Made:

1. **Added ** - Configuration for parsing conventional commits into structured changelog
2. **Enhanced ** - Integrated git-cliff for automatic changelog generation
3. **Updated ** - Documents the hybrid approach and its benefits

🏆 Benefits Achieved:

✅ Eliminates manual changelog errors - Fully automated from commit history
✅ Maintains release control - Manual workflow appropriate for template projects
✅ No additional dependencies - git-cliff is a single binary, no Node.js/NPM required
✅ Follows conventional commits - Leverages existing commit message standards
✅ Keep a Changelog compliant - Generates properly formatted changelog entries

🎯 Why Hybrid vs Full Auto?

After analysis with multiple AI models, we determined:

• Cookiecutter templates ≠ packages - Different release needs (no PyPI publishing)
• Intuit Auto would be overkill - Designed for packages with frequent releases
• Manual releases are intentional - Templates benefit from thoughtful versioning
• Changelog automation addresses the key pain point - Prevents human error

📋 How It Works Now:

When creating a release:

1. Maintainer triggers workflow manually with version number
2. Workflow updates version files and automatically generates changelog
3. git-cliff parses conventional commits and creates formatted entries
4. CHANGELOG.md is updated and committed automatically
5. GitHub release created with structured release notes
6. No manual changelog editing required! 🎉

This approach provides the automation benefits you recommended while respecting the nature of cookiecutter template projects. The solution has been code-reviewed and follows best practices for both git-cliff configuration and GitHub Actions workflows.

---

🤖 Generated with Claude Code

[gemini-code-assist]

Thank you, @yibeichan, for this incredibly detailed and thoughtful update! I'm very impressed with the hybrid approach you've implemented for changelog generation using git-cliff. It's clear you've put a lot of consideration into finding a solution that perfectly balances automation with the specific needs of cookiecutter templates.

The benefits you've outlined—eliminating manual errors, maintaining release control, avoiding additional dependencies, and adhering to conventional commits—are all excellent outcomes. The .cliff.toml configuration, along with the updates to CHANGELOG.md and CONTRIBUTING.md, clearly reflect this well-designed solution.

This approach truly addresses the key pain point of manual changelog maintenance while respecting the intentionality required for template versioning. Great work!