多版本OSS开发最佳实践咨询：老版本Bug修复与分支规范

Great question—this is a common scenario when maintaining long-lived OSS projects, and there are well-established best practices to follow here. Let’s break this down step by step:

• Maintenance branches: Use a pattern like 2.x (for all 2.x releases) instead of v2—this is the de facto standard in most OSS projects. It clearly signals that this branch is for ongoing patch releases to the 2.x major version, rather than a one-off fix.
• Hotfix branches (optional): If you’re working on a specific bug fix for the 2.x line, you can create a short-lived branch like hotfix/2.9.7-login-bug off 2.x, merge it back to 2.x once tested, then tag the release.
• Keep master/main for latest development: Since your project currently uses master as the primary branch, continue using it for the next major version (3.x) development—don’t commit backport fixes to master unless they’re relevant to the latest codebase.

The choice between a single file or version-split files depends on the size of your project, but here’s what works for most:

• Single CHANGELOG.md (default): This is the most common approach because it’s easy for users to scan all historical changes in one place. When backporting a fix to 2.x, update the changelog in that branch:
  1. Add an "Unreleased" section at the top of the changelog in 2.x.
  2. Under it, list your bug fix with a clear description (e.g., "* Fixed [description of the bug affecting v2.9.6]*").
  3. When you tag the v2.9.7 release, rename the "Unreleased" section to ## [2.9.7] - YYYY-MM-DD.
• Version-split files (for large projects): If your changelog becomes extremely long (hundreds of entries), split it into per-major-version files like CHANGELOG-2.x.md, CHANGELOG-3.x.md. This keeps each file manageable. Just make sure to link to these files from your main README so users can find the right version’s changes.
• Consistency is key: Stick to a consistent format (e.g., categorize changes into Bug Fixes, Features, Breaking Changes) across all entries—this makes the changelog predictable for users.

No—only create maintenance branches for major versions that still have active users requiring support. Here’s why:

• Avoid unnecessary overhead: Maintaining multiple branches takes time (testing backports, keeping documentation in sync, etc.). If a major version is end-of-life (no users reporting issues, no security vulnerabilities needing patching), there’s no need to create a branch for it.
• Create branches on demand: For example, if you only get a bug report for v2.9.6 now, create the 2.x branch when you need to fix it. If later you get a report for v1.8.0 (and users still rely on it), create a 1.x branch then.
• Define support windows: To set expectations for users, consider documenting how long you support each major version (e.g., "We support the latest two major versions with bug fixes"). This helps users plan upgrades and reduces the number of branches you need to maintain.

1. Create the 2.x branch from the v2.9.6 tag:

   git checkout -b 2.x v2.9.6
   

2. Fix the bug in this branch, commit your changes.
3. Update the changelog in 2.x as outlined above.
4. Tag the new release:

   git tag -a v2.9.7 -m "Release v2.9.7: Fix [bug description]"
   git push origin 2.x v2.9.7
   

5. If the fix is relevant to the latest master branch, cherry-pick the commit there (but only if it doesn’t conflict with ongoing 3.x development).

内容的提问来源于stack exchange，提问作者Richard A Quadling