Developer Release Rebase

Release Rebase — Prepare New Minor Alpha Release

Prepare a new minor alpha release of Earth2Studio by rebasing the release

candidate branch onto main, bumping the version, updating the changelog,

updating the README latest-news highlights, stripping pinned version tags

from examples, and pushing a PR branch.

Follow every step below in order. Each step that requires user input is

marked with a confirmation gate — wait for explicit approval before proceeding.

Step 1 — Determine the Next Version

• Read earth2studio/__init__.py to get the current __version__ string.
• Compute the next minor alpha: if current is X.Y.*-rc* (or X.Y.0rcN),

the next version is X.(Y+1).0a0.

• If the branch has already been rebased in a prior session, the version may

already reflect the new alpha — note this.

[CONFIRM — Version]

Print both versions (current and target) and ask the user to confirm before

proceeding.

Step 2 — Verify Remotes and Rebase

2a — Check remotes

Confirm:

• origin points to the user's fork of Earth2Studio.
• upstream points to https://github.com/NVIDIA/earth2studio.git (or the SSH equivalent).

If either is wrong, stop and ask the user to fix it.

2b — Create or verify the rebase branch

If the repo is already on a branch named X.Y.0-rebase, confirm with the user

that it was created from the X.Y.*-rc branch and skip the checkout commands.

Otherwise, create the rebase branch:

git fetch upstream X.Y.*-rc
git checkout X.Y.*-rc
git checkout -b X.Y.0-rebase

(Replace X.Y.*-rc with the actual tag/branch name matching the current

release candidate.)

2c — Rebase onto main (if needed)

Check whether the rebase branch already has main as an ancestor:

git merge-base --is-ancestor main HEAD && echo "Already rebased" || echo "Needs rebase"

If a rebase is needed:

git checkout main
git pull upstream main
git checkout X.Y.0-rebase
git rebase main

If the branch is already rebased, skip this and proceed.

Step 3 — Update CHANGELOG.md

Read CHANGELOG.md and insert a new blank section above the most recent

version entry. Use YYYY-MM-xx as the date placeholder where YYYY-MM is the

month after the released version's date (e.g., if releasing 0.17.0 on

2026-07-30, the next dev section gets 2026-08-xx).

The new section must look exactly like this (substituting the version number):

## [X.(Y+1).0a0] - YYYY-MM-xx

### Added

### Changed

### Deprecated

### Removed

### Fixed

### Security

### Dependencies

Also ensure the released version section (the one just below):

• Has unused (empty) subsections removed.
• Does not have the alpha/rc extension in its version (e.g., [0.14.0] not

[0.14.0a0]).

• Has a release date set in YYYY-MM-DD format.

[CONFIRM — Release Date]

If the released section does not already have a date set, ask the user what date

to use before proceeding.

Step 4 — Bump the Package Version

Run these two commands in sequence:

uv run hatch version minor
uv run hatch version alpha

After running, read earth2studio/__init__.py and confirm it now contains

X.(Y+1).0a0.

If the pre-commit hook pyupgrade fails due to a Python version incompatibility

(a known issue with Python 3.14), it is safe to skip with

SKIP=pyupgrade on the subsequent commit step — note this to the user.

Step 5 — Strip Version Tags from Examples

Remove pinned @X.Y.Z git tags from all example install blocks:

find examples/ -type f -exec sed -i 's/@[0-9]\+\.[0-9]\+\.[0-9]\+[a-z0-9]*//g' {} \;

Show a git diff --stat examples/ summary so the user can verify the changes

look correct.

Step 6 — Update Install Guide Version Tag

Update docs/userguide/about/install.md to reference the new released version tag.

• Replace all occurrences of the previous release tag (e.g., @0.14.0) with

the new release tag (e.g., @0.15.0) in the install guide.

• Update the Docker container tag (e.g., nvcr.io/nvidia/pytorch:XX.YY-py3) to

the latest recommended container version if it has changed.

• Show a git diff docs/userguide/about/install.md summary so the user can

verify the changes look correct.

Step 7 — Update Documentation Version Switcher

Update docs/_static/switcher.json to include the new released version.

• Read docs/_static/switcher.json.
• Add a new entry for the released version (e.g., X.Y.0) immediately after

the main entry (which should remain at the top with "preferred": true).

• The new version entry should not have "preferred": true — only main

should be preferred.

Show the diff to the user for review.

Step 8 — Update README Latest News

Update the "Latest News" section in README.md with highlights from the

released version's CHANGELOG entry (the section just below the new blank

development section added in Step 3).

• Read CHANGELOG.md and identify the 3–5 most notable items from the

released version's ### Added subsection. Prefer items that introduce new

model classes, new data sources, or significant new capabilities.

• Read the current ## Latest News section in README.md.
• Replace the existing bullet points (between the > [!NOTE] block and the

"For a complete list…" line) with new bullets summarising the highlights.

Follow the existing style:

• Each bullet starts with a bold linked feature name (where a docs link

exists) followed by a comma and a short description.

• Keep the > [!NOTE] version callout and update it to reference the new

released version number if it changed.

• Show the diff to the user for review.

[CONFIRM — README]

Print the updated Latest News section and ask the user to confirm before

proceeding.

Step 9 — Update Skill Versions

Skip this step. Skill versions are managed separately and should NOT

be updated during the release rebase process.

Step 10 — Update GitHub Issue Templates

Update the suggested version placeholder in the bug report template to

reference the new released version.

• Open .github/ISSUE_TEMPLATE/bug_report.yml.
• Replace the placeholder: value (e.g., "example: 0.14.0") with

"example: X.Y.0" (the new released version).

• Show the diff to the user for review.

Step 11 — Commit and Push

Stage only the expected files and commit:

git add CHANGELOG.md
git add earth2studio/__init__.py
git add examples/
git add README.md
git add docs/_static/switcher.json
git add docs/userguide/about/install.md
git add skills/
git add .github/
git commit -m "Update version to X.(Y+1).0a0"

If pre-commit hooks fail due to a tool incompatibility (not a code issue), use

SKIP=<hook-id> to bypass the broken hook and retry.

Push the branch to origin:

git push origin X.Y.0-rebase

[REMIND — Merge Strategy]

After pushing, remind the user:

> Use Rebase merge, not Squash, when merging the PR.