Library Versioning

This guide is for maintainers of libraries (open source or internal) who support multiple major versions simultaneously.

The Challenge

As a library maintainer, you face these challenges:

• Multiple active versions: Users on v1, v2, v3 all need bug fixes
• Semver compliance: Can't introduce breaking changes in patch releases
• Time pressure: Bug reports come in faster than you can cherry-pick
• Human error: Easy to forget a branch or make mistakes

Example: A Typical Day

You maintain a popular utility library with versions v1, v2, and v3:

1. User reports bug affecting all versions
2. You fix it on main (v3)
3. Now you need to backport to v2 and v1
4. v2 cherry-pick works fine
5. v1 has conflicts due to refactoring
6. Another bug report comes in...
7. Repeat forever

The Solution

With recommit, your workflow becomes:

1. User reports bug
2. Fix it on main
3. Merge the PR
4. ✅ recommit backports to v2 and v1 automatically

Setup Guide

Step 1: Understand Your Branch Strategy

Common patterns for libraries:

Pattern A: Main + Version Branches

main (latest development, becomes v4)
├── v3 (current stable)
├── v2 (previous stable)
└── v1 (legacy/LTS)

Pattern B: Version Branches Only

v3 (current stable)
├── v2 (previous stable)
└── v1 (legacy/LTS)

Step 2: Create Your Roadmap

For Pattern A (with main):

Name: Library Releases
Branches: main; v3; v2; v1
Cherry-pick to Default Branch: Enabled

For Pattern B (version only):

Name: Version Branches
Branches: v3; v2; v1
Cherry-pick to Default Branch: Disabled

Step 3: Configure Repository

1. Link repository to roadmap
2. Enable auto cherry-pick
3. Test with a small PR

Real-World Example

Scenario: axios-like HTTP library

You maintain http-client with these active versions:

Roadmap Configuration:

Name: http-client releases
Branches: main; v3; v2; v1

Workflow:

1. Security vulnerability discovered

2. Fix merged to main

3. recommit creates PRs:

   • main → v3 ✅
   • main → v2 ✅
   • main → v1 ✅

4. Review and merge each PR

5. Release patch versions: v3.2.1, v2.9.5, v1.15.3

Handling Version-Specific Code

Sometimes code differs significantly between versions:

When Cherry-Pick Works

• Bug fixes in stable code
• Documentation updates
• Dependency updates (same versions)
• Test improvements

When Manual Intervention Needed

• API changed between versions
• Dependencies differ
• Code was refactored

Best Practices for Library Maintainers

1. Keep Version Branches Updated

Periodically merge forward:

# Merge v1 fixes into v2
git checkout v2
git merge v1
 
# Merge v2 fixes into v3
git checkout v3
git merge v2

This reduces divergence and conflicts.

2. Use Conventional Commits

Mark commits that shouldn't be backported:

feat!: redesign API (v3 only)
fix: resolve memory leak (backport to all)

3. Document Version Support

Be clear about which versions receive updates:

4. Batch Releases

Accumulate cherry-picks, then release:

• Review all auto-created PRs
• Merge them together
• Release new patch versions

Workflow Example

Day-to-Day Operation

Monday:
- 3 bug reports fixed
- 3 PRs merged to main
- 9 cherry-pick PRs created automatically

Tuesday Morning:
- Review cherry-pick PRs
- 7 merged without issues
- 2 need conflict resolution

Tuesday Afternoon:
- Resolve conflicts
- Merge remaining PRs
- Release v3.1.1, v2.8.3, v1.12.7

Time Saved

FAQs for Library Maintainers

Q: What if a fix doesn't apply to older versions?

Close the auto-created PR. It's fine - not every change needs to go everywhere.

Q: How do I handle breaking changes?

Breaking changes should only go to main/latest. When you release a new major version:

1. Update your roadmap to add the new branch
2. Remove deprecated versions as they reach end-of-life

Q: Can I automate the final merge too?

Currently, recommit creates PRs but doesn't auto-merge. This is intentional - you should review before merging to ensure quality.

Related

• Create Roadmap
• Conflict Resolution
• Security Patches