Add next branch for major version development

Update branch policy documentation to introduce a three-tier branching
strategy where the next branch is used for major version updates, main
for minor updates, and x.y-maintenance branches for patch releases.

This change clarifies the development workflow by providing separate
branches for breaking changes (next) and new features (main), while
maintaining backward compatibility through the existing maintenance
branch structure.

Co-Authored-By: Claude <[email protected]>

Author: dahlia

AGENTS.md

@@ -196,13 +196,15 @@ maintenance:
 
 ### Branch Types
 
-1. **main**: Contains unreleased development for the next major/minor version
-2. **x.y-maintenance**: Maintenance branches for released major/minor versions
+1. **next**: Contains unreleased development for the next major version
+2. **main**: Contains unreleased development for the next minor version
+3. **x.y-maintenance**: Maintenance branches for released major/minor versions
    (e.g., `1.5-maintenance`, `1.6-maintenance`)
 
 ### Development Workflow
 
-- **New features**: Always target the `main` branch
+- **Breaking changes**: Target the `next` branch
+- **New features**: Target the `main` branch
 - **Bug fixes**: Target the oldest applicable maintenance branch that contains
   the bug
 
@@ -215,9 +217,10 @@ When a bug is fixed in a maintenance branch:
 3. Merge the fix into the next maintenance branch (e.g., `1.6-maintenance`)
 4. Create a new patch release tag for that branch (e.g., `1.6.1`)
 5. Continue merging forward through all subsequent maintenance branches
-6. Finally merge into `main`
+6. Merge into `main`
+7. Finally merge into `next`
 
-This ensures that all maintenance branches and the main development branch
+This ensures that all maintenance branches and the development branches
 include the fix.
 
 
@@ -242,7 +245,7 @@ When adding features:
 3. Update documentation for API changes
 4. Verify examples work with the change
 5. Update CHANGES.md with details
-6. Target the main branch
+6. Target the main branch for non-breaking changes, or the next branch for breaking changes
 
 
 Build and Distribution

CONTRIBUTING.md

@@ -94,13 +94,15 @@ maintenance:
 
 #### Branch types
 
- -  **main**: Contains unreleased development for the next major/minor version.
+ -  **next**: Contains unreleased development for the next major version.
+ -  **main**: Contains unreleased development for the next minor version.
  -  **x.y-maintenance**: Maintenance branches for released major/minor versions
     (e.g., *1.5-maintenance*, *1.6-maintenance*).
 
 #### Target branches
 
- -  **New features**: Always target the *main* branch.
+ -  **Breaking changes**: Target the *next* branch.
+ -  **New features**: Target the *main* branch.
  -  **Bug fixes**: Target the oldest applicable maintenance branch that contains
     the bug.
 
@@ -114,9 +116,10 @@ When a bug is fixed in a maintenance branch:
  3. Merge the fix into the next maintenance branch (e.g., *1.6-maintenance*).
  4. Create a new patch release tag for that branch (e.g., `1.6.1`).
  5. Continue merging forward through all subsequent maintenance branches.
- 6. Finally merge into *main*.
+ 6. Merge into *main*.
+ 7. Finally merge into *next*.
 
-This ensures that all maintenance branches and the main development branch
+This ensures that all maintenance branches and the development branches
 include the fix.
 
 ### Bug fix
@@ -161,7 +164,8 @@ A patch set should include the following:
  -  The *CHANGES.md* entry.  The entry should include the issue number,
     the pull request number, and your name (unless you want to be anonymous).
 
-Feature pull requests should target the *main* branch.
+Feature pull requests should target the *main* branch for non-breaking changes,
+or the *next* branch for breaking changes.
 
 ### Pull request builds