xtr.dev/payload-mailing
1
0
Fork 0
mirror of https://github.com/xtr-dev/payload-mailing.git synced 2025-12-10 00:03:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3 from xtr-dev/feature/version-management-workflow

Browse Source 
feat: add automated version management with AI-generated changelogs
This commit is contained in:
Bas
2025-09-13 13:27:02 +02:00
committed by GitHub
parent 94a9bf68c8 75e3875ebc
commit 2ab174c052
2 changed files with 530 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
.github/workflows/version-and-publish.yml vendored Normal file
View File

@@ -0,0 +1,375 @@
name: Version and Publish
on:
push:
branches:
- main
pull_request:
branches:
- main
types: [closed]
jobs:
version-and-publish:
if: github.event_name == 'push' || (github.event.pull_request.merged == true && (contains(github.event.pull_request.head.ref, 'version/major') || contains(github.event.pull_request.head.ref, 'version/minor') || contains(github.event.pull_request.head.ref, 'version/patch')))
runs-on: ubuntu-latest
outputs:
new-version: ${{ steps.version-bump.outputs.new-version }}
current-version: ${{ steps.version-bump.outputs.current-version }}
version-type: ${{ steps.version-type.outputs.type }}
package-name: ${{ steps.prerequisites.outputs.package-name }}
steps:
- name: Checkout code
uses: actions/checkout@v4
with:
fetch-depth: 0
token: ${{ secrets.GITHUB_TOKEN }}
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
- name: Setup pnpm
uses: pnpm/action-setup@v4
with:
version: 8
- name: Get pnpm store directory
shell: bash
run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
- name: Setup pnpm cache
uses: actions/cache@v4
with:
path: ${{ env.STORE_PATH }}
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
restore-keys: |
${{ runner.os }}-pnpm-store-
- name: Validate prerequisites and setup
id: prerequisites
run: |
# Extract package info
PACKAGE_NAME=$(node -p "require('./package.json').name")
CURRENT_VERSION=$(node -p "require('./package.json').version")
echo "package-name=$PACKAGE_NAME" >> $GITHUB_OUTPUT
echo "current-version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
echo "📦 Package: $PACKAGE_NAME"
echo "📌 Current Version: $CURRENT_VERSION"
# Validate version branches exist
echo "🔍 Validating version branches..."
MISSING_BRANCHES=""
for branch in "version/major" "version/minor" "version/patch"; do
if ! git ls-remote --heads origin "$branch" | grep -q "$branch"; then
MISSING_BRANCHES="$MISSING_BRANCHES $branch"
fi
done
if [ -n "$MISSING_BRANCHES" ]; then
echo "❌ ERROR: Missing required version branches:$MISSING_BRANCHES"
echo "Please create these branches first:"
for branch in $MISSING_BRANCHES; do
echo " git checkout -b $branch && git push origin $branch"
done
exit 1
fi
echo "✅ All version branches exist"
# Validate Node.js version matches package.json engines
NODE_VERSION=$(node --version)
echo "🔍 Validating Node.js version: $NODE_VERSION"
# Basic validation - check if we're on Node 20+
if ! echo "$NODE_VERSION" | grep -qE "^v(20|21|22)\."; then
echo "⚠️ WARNING: Node.js version $NODE_VERSION may not match package.json engines requirements"
fi
echo "✅ Prerequisites validation complete"
- name: Install dependencies
run: pnpm install --frozen-lockfile
- name: Run tests
run: pnpm test
- name: Run build
run: pnpm build
- name: Determine version bump type
id: version-type
run: |
if [[ "${{ github.event.pull_request.head.ref }}" =~ version/major ]]; then
echo "type=major" >> $GITHUB_OUTPUT
elif [[ "${{ github.event.pull_request.head.ref }}" =~ version/minor ]]; then
echo "type=minor" >> $GITHUB_OUTPUT
elif [[ "${{ github.event.pull_request.head.ref }}" =~ version/patch ]]; then
echo "type=patch" >> $GITHUB_OUTPUT
elif [[ "${{ github.event_name }}" == "push" ]]; then
# Default to patch for direct pushes to main
echo "type=patch" >> $GITHUB_OUTPUT
else
echo "type=none" >> $GITHUB_OUTPUT
fi
- name: Configure git
if: steps.version-type.outputs.type != 'none'
run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "github-actions[bot]@users.noreply.github.com"
- name: Install Claude Code CLI
if: steps.version-type.outputs.type != 'none'
run: |
curl -fsSL https://claude.ai/cli/install.sh | bash
echo "$HOME/.claude/bin" >> $GITHUB_PATH
- name: Generate changelog with Claude (with fallback)
if: steps.version-type.outputs.type != 'none'
id: changelog
run: |
# Get commits since last tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then
COMMITS=$(git log --oneline --no-merges --since="1 week ago" || echo "No recent commits")
else
COMMITS=$(git log --oneline --no-merges ${LAST_TAG}..HEAD || echo "No new commits")
fi
# Generate changelog using Claude (fail if it fails)
if ! command -v claude-code >/dev/null 2>&1; then
echo "❌ ERROR: Claude CLI not found. Please ensure Claude Code is properly installed."
exit 1
fi
echo "🤖 Generating changelog with Claude..."
CHANGELOG=$(timeout 240s claude-code << 'CLAUDE_EOF'
Please analyze the following git commits and generate a concise changelog in this exact format:
## Changes
### 🚀 Features
- Brief description of new features
### 🐛 Bug Fixes
- Brief description of bug fixes
### 🔧 Improvements
- Brief description of improvements/refactoring
### 📚 Documentation
- Brief description of documentation changes
### ⚡ Performance
- Brief description of performance improvements
Only include sections that have actual changes. Keep each bullet point concise and user-focused.
Git commits to analyze:
$COMMITS
CLAUDE_EOF
)
# Check if changelog generation succeeded
if [ $? -ne 0 ] || [ -z "$CHANGELOG" ]; then
echo "❌ ERROR: Failed to generate changelog with Claude. Workflow cannot continue."
echo "Debug info - Commits to analyze:"
echo "$COMMITS"
exit 1
fi
echo "✅ Successfully generated changelog with Claude"
# Save changelog to output
echo "changelog<<EOF" >> $GITHUB_OUTPUT
echo "$CHANGELOG" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
- name: Create version bump script
if: steps.version-type.outputs.type != 'none'
run: |
# Create Node.js script to safely bump version
cat > bump-version.js << 'VERSION_SCRIPT_EOF'
const fs = require('fs');
const path = require('path');
const versionType = process.argv[2];
const packagePath = path.join(process.cwd(), 'package.json');
try {
const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
const currentVersion = packageJson.version;
const [major, minor, patch] = currentVersion.split('.').map(Number);
let newVersion;
switch (versionType) {
case 'major':
newVersion = `${major + 1}.0.0`;
break;
case 'minor':
newVersion = `${major}.${minor + 1}.0`;
break;
case 'patch':
newVersion = `${major}.${minor}.${patch + 1}`;
break;
default:
throw new Error(`Invalid version type: ${versionType}`);
}
packageJson.version = newVersion;
fs.writeFileSync(packagePath, JSON.stringify(packageJson, null, 2) + '\n');
console.log(`${currentVersion}:${newVersion}`);
} catch (error) {
console.error('Error bumping version:', error.message);
process.exit(1);
}
VERSION_SCRIPT_EOF
- name: Create single atomic commit with all changes
if: steps.version-type.outputs.type != 'none'
id: version-bump
run: |
# Extract version type for commit title
VERSION_TYPE="${{ steps.version-type.outputs.type }}"
# Create clean commit message title
if [ "$VERSION_TYPE" = "major" ]; then
COMMIT_TITLE="🚀 Major Release"
elif [ "$VERSION_TYPE" = "minor" ]; then
COMMIT_TITLE="✨ Minor Release"
else
COMMIT_TITLE="🐛 Patch Release"
fi
# Get the safe base commit (last release tag or fallback)
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -n "$LAST_TAG" ]; then
BASE_COMMIT=$(git rev-list -n 1 $LAST_TAG)
else
# Fallback: get commit from 1 week ago or first commit
BASE_COMMIT=$(git rev-list --since="1 week ago" --reverse HEAD | head -1 || git rev-list --max-parents=0 HEAD)
fi
echo "Base commit for squash: $BASE_COMMIT"
# Safely reset to base (soft reset preserves working directory)
git reset --soft $BASE_COMMIT
# Bump version using our safe Node.js script
VERSION_OUTPUT=$(node bump-version.js $VERSION_TYPE)
CURRENT_VERSION=$(echo $VERSION_OUTPUT | cut -d: -f1)
NEW_VERSION=$(echo $VERSION_OUTPUT | cut -d: -f2)
echo "current-version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
echo "new-version=$NEW_VERSION" >> $GITHUB_OUTPUT
# Synchronize pnpm lockfile if it exists
if [ -f pnpm-lock.yaml ]; then
echo "Synchronizing pnpm lockfile..."
pnpm install --frozen-lockfile --ignore-scripts || echo "Lockfile sync completed with warnings"
fi
# Create single atomic commit with everything
git add -A
COMMIT_MSG="$COMMIT_TITLE
${{ steps.changelog.outputs.changelog }}"
git commit -m "$COMMIT_MSG" || {
echo "Commit failed, checking git status:"
git status
git diff --cached
exit 1
}
# Create git tag
git tag -a "v$NEW_VERSION" -m "Version $NEW_VERSION
${{ steps.changelog.outputs.changelog }}"
echo "Created single atomic commit with version $CURRENT_VERSION → $NEW_VERSION"
# Clean up temporary files
rm -f bump-version.js
- name: Push version changes safely
if: steps.version-type.outputs.type != 'none'
run: |
# Check if we need to force push (if git history was rewritten)
CURRENT_REMOTE_HEAD=$(git ls-remote origin main | cut -f1)
LOCAL_REMOTE_HEAD=$(git rev-parse origin/main)
if [ "$CURRENT_REMOTE_HEAD" != "$LOCAL_REMOTE_HEAD" ]; then
echo "⚠️ Remote main has been updated by another process"
echo "Current remote HEAD: $CURRENT_REMOTE_HEAD"
echo "Local remote HEAD: $LOCAL_REMOTE_HEAD"
echo "❌ ABORTING: Cannot safely force push. Another workflow may be running."
exit 1
fi
# Safe force push with lease (only if remote hasn't changed)
echo "🚀 Pushing squashed commit to main..."
git push --force-with-lease origin main || {
echo "❌ ERROR: Force push failed. This likely means:"
echo "1. Another workflow pushed to main after this one started"
echo "2. Branch protection rules are preventing the push"
echo "3. Insufficient permissions"
exit 1
}
echo "🏷️ Pushing tags..."
git push origin --tags
- name: Publish to NPM
if: steps.version-type.outputs.type != 'none'
run: pnpm publish --access public --no-git-checks
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Create GitHub Release
if: steps.version-type.outputs.type != 'none'
run: |
gh release create "v${{ steps.version-bump.outputs.new-version }}" \
--title "Release v${{ steps.version-bump.outputs.new-version }}" \
--notes "# Release v${{ steps.version-bump.outputs.new-version }}
${{ steps.changelog.outputs.changelog }}
---
**Version Info**: ${{ steps.version-type.outputs.type }} release (v${{ steps.version-bump.outputs.current-version }} → v${{ steps.version-bump.outputs.new-version }})
### Installation
\`\`\`bash
npm install ${{ steps.prerequisites.outputs.package-name }}@${{ steps.version-bump.outputs.new-version }}
\`\`\`
### Documentation
See the [README](https://github.com/${{ github.repository }}#readme) for usage instructions and full documentation."
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
notify-success:
if: github.event_name == 'push' || (github.event.pull_request.merged == true && (contains(github.event.pull_request.head.ref, 'version/major') || contains(github.event.pull_request.head.ref, 'version/minor') || contains(github.event.pull_request.head.ref, 'version/patch')))
needs: version-and-publish
runs-on: ubuntu-latest
steps:
- name: Success notification
if: needs.version-and-publish.outputs.new-version != ''
run: |
echo "🎉 Successfully published version ${{ needs.version-and-publish.outputs.new-version }} to NPM!"
echo "📦 Package: https://www.npmjs.com/package/${{ needs.version-and-publish.outputs.package-name }}"
echo "🏷️ GitHub Release: https://github.com/${{ github.repository }}/releases/tag/v${{ needs.version-and-publish.outputs.new-version }}"
echo "🔄 Version Type: ${{ needs.version-and-publish.outputs.version-type }}"
echo "📈 Version Change: v${{ needs.version-and-publish.outputs.current-version }} → v${{ needs.version-and-publish.outputs.new-version }}"

155
VERSION_WORKFLOW.md Normal file
View File

@@ -0,0 +1,155 @@
# Version Management Workflow
This repository uses automated version management with GitHub Actions. Version bumps are triggered based on which branch changes are merged to `main`.
## Available Branches
- `version/major` - For breaking changes (e.g., 1.0.0 → 2.0.0)
- `version/minor` - For new features (e.g., 1.0.0 → 1.1.0)
- `version/patch` - For bug fixes (e.g., 1.0.0 → 1.0.1)
## How to Use
### For Patch Releases (Bug Fixes)
1. Create a branch from `version/patch`:
```bash
git checkout version/patch
git pull origin version/patch
git checkout -b fix/your-bug-fix
# Make your changes
git commit -m "fix: your bug fix description"
git push origin fix/your-bug-fix
```
2. Create a PR targeting `version/patch`
3. Once approved, merge the PR to `version/patch`
4. Create a PR from `version/patch` to `main`
5. When merged to `main`, the workflow will:
- Bump patch version (e.g., 1.0.0 → 1.0.1)
- Run tests and build
- Publish to NPM
- Create a GitHub release
### For Minor Releases (New Features)
1. Create a branch from `version/minor`:
```bash
git checkout version/minor
git pull origin version/minor
git checkout -b feature/your-feature
# Make your changes
git commit -m "feat: your feature description"
git push origin feature/your-feature
```
2. Create a PR targeting `version/minor`
3. Once approved, merge the PR to `version/minor`
4. Create a PR from `version/minor` to `main`
5. When merged to `main`, the workflow will:
- Bump minor version (e.g., 1.0.0 → 1.1.0)
- Run tests and build
- Publish to NPM
- Create a GitHub release
### For Major Releases (Breaking Changes)
1. Create a branch from `version/major`:
```bash
git checkout version/major
git pull origin version/major
git checkout -b breaking/your-breaking-change
# Make your changes
git commit -m "feat!: your breaking change description"
git push origin breaking/your-breaking-change
```
2. Create a PR targeting `version/major`
3. Once approved, merge the PR to `version/major`
4. Create a PR from `version/major` to `main`
5. When merged to `main`, the workflow will:
- Bump major version (e.g., 1.0.0 → 2.0.0)
- Run tests and build
- Publish to NPM
- Create a GitHub release
## Direct Push to Main
Direct pushes to `main` will trigger a patch version bump by default.
## Required Secrets
Make sure these secrets are configured in your GitHub repository:
- `NPM_TOKEN` - Your NPM authentication token for publishing
- `GITHUB_TOKEN` - Automatically provided by GitHub Actions
## Workflow Features
- ✅ Automatic version bumping based on branch
- ✅ AI-generated changelog using Claude Code CLI
- ✅ Squashes all PR commits into single clean commit
- ✅ Runs tests before publishing
- ✅ Builds the package before publishing
- ✅ Creates git tags with changelog in tag message
- ✅ Publishes to NPM with public access
- ✅ Creates GitHub releases with formatted changelog
- ✅ Prevents publishing if tests fail
## Changelog Generation
The workflow automatically generates a standardized changelog for each release using Claude Code CLI. The changelog analyzes git commits since the last release and categorizes them into:
- 🚀 **Features** - New functionality
- 🐛 **Bug Fixes** - Bug fixes and corrections
- 🔧 **Improvements** - Code improvements and refactoring
- 📚 **Documentation** - Documentation updates
- ⚡ **Performance** - Performance optimizations
The generated changelog is included in:
- The single squashed release commit message
- The git tag message
- The GitHub release notes
## Git History Structure
The workflow creates an ultra-clean git history by squashing all commits from the PR into a single release commit:
**Before Squashing:**
```
abc123 feat: add email scheduling
def456 fix: validation bug
ghi789 docs: update readme
jkl012 test: add unit tests
```
**After Squashing:**
```
abc123 ✨ Minor Release
## Changes
### 🚀 Features
- Add email scheduling feature
### 🐛 Bug Fixes
- Fix validation error handling
### 📚 Documentation
- Update readme with new examples
```
This results in one meaningful commit per release with all changes summarized in the AI-generated changelog.
## Version Branch Maintenance
Keep version branches up to date by periodically merging from main:
```bash
git checkout version/patch
git merge main
git push origin version/patch
git checkout version/minor
git merge main
git push origin version/minor
git checkout version/major
git merge main
git push origin version/major
```
This ensures that all version branches have the latest changes from main before creating new features or fixes.