bentopdf/RELEASE.md

🚀 Release Process - Real-World Scenarios

📋 Common Release Scenarios

Scenario 1: I Just Finished a Feature and Want to Release

Situation: You've completed a new feature, tested it locally, and want to release it.

Current State:

$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  modified:   src/js/new-feature.js
  modified:   src/css/styles.css
  modified:   README.md

Untracked files:
  src/js/feature-helper.js

Steps:

# 1. Commit your feature changes
git add .
git commit -m "Add new PDF watermark feature"

# 2. Choose your release type and run
npm run release        # Patch: 1.0.0 → 1.0.1 (bug fixes, small improvements)
npm run release:minor  # Minor: 1.0.0 → 1.1.0 (new features, backward compatible)
npm run release:major  # Major: 1.0.0 → 2.0.0 (breaking changes)

What Happens:

• ✅ Your feature commit stays as-is
• ✅ Version gets bumped in package.json
• ✅ New release commit is created
• ✅ Git tag is created (e.g., v1.0.1)
• ✅ Everything gets pushed to GitHub
• ✅ Docker image gets built and published

---

Scenario 2: I Have Uncommitted Changes and Want to Release

Situation: You have local changes but haven't committed them yet.

Current State:

$ git status
Changes not staged for commit:
  modified:   package.json
  modified:   src/js/main.js
  modified:   README.md

❌ This Will Fail:

npm run release
# Error: Your local changes would be overwritten by merge

✅ Solution Options:

Option A: Commit Everything First (Recommended)

git add .
git commit -m "Add new features and improvements"
npm run release

Option B: Stash Changes Temporarily

git stash
npm run release
git stash pop  # Restore your changes after release

Option C: Commit Only What's Needed

git add package.json src/js/main.js
git commit -m "Add core improvements"
npm run release
git add README.md
git commit -m "Update documentation"

---

Scenario 3: I Want to Release a Hotfix

Situation: There's a critical bug in production that needs immediate fixing.

Steps:

# 1. Fix the bug
git add src/js/bug-fix.js
git commit -m "Fix critical PDF rendering issue"

# 2. Release as patch (bug fix)
npm run release
# This creates: 1.0.0 → 1.0.1

Result:

• ✅ Bug fix gets released immediately
• ✅ Docker image with fix is available
• ✅ Users can pull the fixed version

---

Scenario 4: I Want to Release a Major Update

Situation: You've added significant new features that might break existing functionality.

Steps:

# 1. Commit all your changes
git add .
git commit -m "Add major PDF editing features and API changes"

# 2. Release as major version
npm run release:major
# This creates: 1.0.0 → 2.0.0

Result:

• ✅ Major version bump indicates breaking changes
• ✅ Users know to check compatibility
• ✅ Both old and new versions available

---

Scenario 5: I Want to Release Multiple Features at Once

Situation: You've been working on multiple features and want to release them together.

Steps:

# 1. Commit all features
git add .
git commit -m "Add multiple PDF tools: watermark, encryption, and compression"

# 2. Choose appropriate release type
npm run release:minor  # For new features (1.0.0 → 1.1.0)
# OR
npm run release:major  # For breaking changes (1.0.0 → 2.0.0)

---

Scenario 6: I Want to Test the Release Process

Situation: You want to test the release system without affecting production.

Steps:

# 1. Make a small test change
echo "// Test comment" >> src/js/main.js
git add src/js/main.js
git commit -m "Test release process"

# 2. Run patch release
npm run release
# This creates: 1.0.0 → 1.0.1

# 3. Verify everything works
# Check GitHub Actions, Docker Hub, etc.

# 4. If you want to undo the test release
git tag -d v1.0.1
git push origin :refs/tags/v1.0.1
git reset --hard HEAD~1

---

🎯 Release Type Guidelines

Scenario	Command	Version Change	When to Use
Bug Fix	npm run release	1.0.0 → 1.0.1	Fixing bugs, small improvements
New Feature	npm run release:minor	1.0.0 → 1.1.0	Adding features, backward compatible
Breaking Change	npm run release:major	1.0.0 → 2.0.0	API changes, major rewrites

---

🔄 What Happens After You Run a Release Command

Immediate Actions (Local):

1. Version Update: package.json version gets bumped
2. Git Commit: New commit created with "Release vX.X.X"
3. Git Tag: Tag created (e.g., v1.0.1)
4. Git Push: Everything pushed to GitHub

Automatic Actions (GitHub):

1. GitHub Actions Triggered: Workflow starts building Docker image
2. Docker Build: Multi-architecture image created
3. Docker Push: Images pushed to Docker Hub with tags:
   • bentopdf/bentopdf:latest
   • bentopdf/bentopdf:1.0.1
   • bentopdf/bentopdf:v1.0.1

End Result:

Users can immediately pull your new version:

docker pull bentopdf/bentopdf:1.0.1

---

🚨 Before You Release - Prerequisites

1. Docker Hub Credentials Setup

You need to add these secrets to your GitHub repository:

1. Go to Settings → Secrets and variables → Actions
2. Add these secrets:
   • DOCKER_USERNAME: Your Docker Hub username
   • DOCKER_TOKEN: Your Docker Hub access token

2. Get Docker Hub Token

1. Go to Docker Hub
2. Account Settings → Security → New Access Token
3. Set permissions to "Read, Write, Delete"
4. Copy the token and add it to GitHub Secrets

---

🔧 Troubleshooting Common Issues

❌ "Your local changes would be overwritten by merge"

Problem: You have uncommitted changes Solution:

git add .
git commit -m "Your commit message"
npm run release

❌ "Permission denied" in GitHub Actions

Problem: Missing Docker Hub credentials Solution: Add DOCKER_USERNAME and DOCKER_TOKEN to GitHub Secrets

❌ "Tag already exists"

Problem: You've run the same release before Solution: This is normal! The script will skip creating duplicate tags

❌ GitHub Actions fails

Problem: Various build issues Solution:

1. Check Actions tab for detailed logs
2. Verify Docker Hub credentials
3. Check Dockerfile for syntax errors

---

🧪 Testing Your Release System

Quick Test:

# Make a small change
echo "// Test" >> src/js/main.js
git add src/js/main.js
git commit -m "Test release"
npm run release

Verify Results:

1. GitHub Actions: Check Actions tab for successful build
2. Docker Hub: Verify images are published
3. Git Tags: git tag --list should show new tag
4. Version: cat package.json | grep version should show updated version

Undo Test Release:

git tag -d v1.0.1
git push origin :refs/tags/v1.0.1
git reset --hard HEAD~1

---

🎉 That's It!

Your release system is now ready! Just follow the scenarios above based on your situation and run the appropriate npm run release command.