feat: release next major as beta by default

[aripalo]

Derive a ${majorVersion + 1}.x release branch that publishes prereleases under the beta npm dist-tag, so work on the next major can ship without moving latest. Downstream releaseBranches are merged on top, keyed by branch name, so an entry for the next major branch replaces the default.

Summary by CodeRabbit

• New Features

  • Automatically generates a next-major beta release branch.
  • Supports customizing, replacing, or extending generated release branches.
  • Keeps release branch configuration synchronized with the selected major version.

• Documentation

  • Added guidance for release branch behavior, configuration, and downstream migration.
  • Clarified major version and release branch options.

• Bug Fixes

  • Improved release task configuration to apply the correct branch settings.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds automatic ${majorVersion + 1}.x beta release branch generation. Custom release branches merge with the generated configuration and can replace it by name. Construct integration, tests, API documentation, and README guidance were updated.

Changes

Release branch generation

Layer / File(s)	Summary
Release branch helper behavior src/releaseBranches.ts, test/releaseBranches.test.ts	Added helpers for next-major branch names, beta options, branch merging, replacement, immutability, and fresh results.
Construct option integration src/AlmaCdkConstructLibrary.ts, test/AlmaCdkConstructLibrary.test.ts	Construct options now generate release branches from majorVersion and validate downstream overrides. Tests cover workflow variables and synchronization with majorVersion.
Option and migration documentation src/schemas/almaCdkConstructLibraryOptions.ts, API.md, README.md	Documented generated branches, custom branch merging, replacement behavior, and downstream migration guidance.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AlmaCdkConstructLibraryOptions
  participant buildAwsCdkConstructLibraryOptions
  participant buildReleaseBranches
  participant ReleaseTasks
  AlmaCdkConstructLibraryOptions->>buildAwsCdkConstructLibraryOptions: provide majorVersion and releaseBranches
  buildAwsCdkConstructLibraryOptions->>buildReleaseBranches: build validated branch configuration
  buildReleaseBranches-->>buildAwsCdkConstructLibraryOptions: return generated and overridden branches
  buildAwsCdkConstructLibraryOptions->>ReleaseTasks: configure release task environment variables

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly summarizes the next-major beta branch behavior and downstream override rules, but it does not include the template's issue reference.
Title check	✅ Passed	The title clearly and concisely describes the main change: publishing the next major release as beta by default.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch release-beta-by-default

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@README.md`:
- Line 95: Update the README migration note to recommend removing a manually
declared next-major branch only when it exactly matches the generated beta
configuration; otherwise, instruct users to retain it, including when its
dist-tag, prerelease, or branch options differ.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1d624fcd-2900-441b-880a-7a15d942b187

📥 Commits

Reviewing files that changed from the base of the PR and between e996fdc and fe7cf1b.

⛔ Files ignored due to path filters (1)

• test/__snapshots__/AlmaCdkConstructLibrary.test.ts.snap is excluded by !**/*.snap

📒 Files selected for processing (7)

• API.md
• README.md
• src/AlmaCdkConstructLibrary.ts
• src/releaseBranches.ts
• src/schemas/almaCdkConstructLibraryOptions.ts
• test/AlmaCdkConstructLibrary.test.ts
• test/releaseBranches.test.ts

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Limit the migration advice to matching configurations.

A manual next-major entry is not always identical to the generated entry. It can use another dist-tag, prerelease, or branch option. Removing it can change publishing behavior or discard configuration. State that users can remove the entry only when it exactly matches the generated beta configuration.

Proposed fix

-Note: downstream projects that previously declared the `${MAJOR_VERSION + 1}.x` branch by hand can now drop it – the generated default is identical.
+Note: downstream projects can remove a manual `${MAJOR_VERSION + 1}.x` entry only when it matches the generated beta configuration and has no additional branch options.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	Note: downstream projects that previously declared the `${MAJOR_VERSION + 1}.x` branch by hand can now drop it – the generated default is identical.
	Note: downstream projects can remove a manual `${MAJOR_VERSION + 1}.x` entry only when it matches the generated beta configuration and has no additional branch options.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` at line 95, Update the README migration note to recommend removing
a manually declared next-major branch only when it exactly matches the generated
beta configuration; otherwise, instruct users to retain it, including when its
dist-tag, prerelease, or branch options differ.