Automated Versioning and Release Workflow

This document describes the automated release workflow for the generate-repo-file-list GitHub Action.

Overview

The action uses semantic versioning (v1.2.3) and automatically creates releases when changes are pushed to the main branch.

How It Works

1. Version Detection

The workflow examines your commit messages since the last release to determine the version bump:

Commit Pattern	Version Bump	Example
BREAKING CHANGE or !:	Major	v1.0.0 → v2.0.0
feat: or feature:	Minor	v1.0.0 → v1.1.0
All others (fix, docs, etc.)	Patch	v1.0.0 → v1.0.1

2. Automatic Tagging

When you push to main:

1. The workflow calculates the next version
2. Creates a new version tag (e.g., v1.2.3)
3. Updates the major version tag (e.g., v1) to point to the latest release
4. Generates a changelog from commit messages
5. Creates a GitHub Release with the changelog

3. Tag Strategy

The workflow maintains two types of tags:

• Specific version tags (v1.2.3, v1.2.4, etc.) - immutable, pinned releases
• Major version tags (v1, v2, etc.) - updated to point to the latest minor/patch

Usage in Other Repositories

Recommended: Use Major Version Tag

This automatically gets bug fixes and new features (non-breaking):

- uses: nick2bad4u/generate-repo-file-list@v1
  with:
   directory: "."

Alternative: Pin to Specific Version

For maximum stability, pin to a specific release:

- uses: nick2bad4u/generate-repo-file-list@v1.2.3
  with:
   directory: "."

Commit Message Format

Follow Conventional Commits for proper versioning:

Patch Release (Bug Fixes)

git commit -m "fix: correct file path handling on Windows"
git commit -m "docs: update README with new examples"
git commit -m "chore: update dependencies"

Minor Release (New Features)

git commit -m "feat: add support for custom file categories"
git commit -m "feature: implement lazy loading for large repos"

Major Release (Breaking Changes)

git commit -m "feat!: restructure action inputs

BREAKING CHANGE: The 'file-list' input has been renamed to 'output-file'"

Or:

git commit -m "refactor: change API structure

BREAKING CHANGE: action now requires Python 3.11+"

Workflow Configuration

The auto-release workflow is triggered on every push to main, except for:

• Changes to *.md files
• Changes to LICENSE
• Changes to .gitignore
• Changes to workflow files themselves

To disable auto-release, delete or disable .github/workflows/auto-release.yml.

Manual Release Override

If you need to create a release manually:

# Create and push a tag manually
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

# Create a GitHub release
gh release create v1.2.3 --title "v1.2.3" --notes "Release notes here"

# Update major version tag
git tag -f v1
git push origin v1 --force

First Release

The workflow will create v1.0.0 as the first semantic version tag when you push to main.

Troubleshooting

Release Not Created

Check that:

1. You pushed to the main branch
2. Your changes aren't only documentation/config files (see paths-ignore)
3. The workflow has contents: write permission
4. No errors in the Actions tab

Wrong Version Bump

The workflow analyzes commit messages. Ensure:

1. Commit messages follow the conventional format
2. Use feat: for new features
3. Use BREAKING CHANGE: or !: for breaking changes
4. Other commits default to patch bumps

Migration from Old Tags

Old tags (github-action-published-final, etc.) are preserved but won't affect new semantic versioning. The workflow starts from v1.0.0 if no v*.*.* tags exist.