developer-release-rebase

name	developer-release-rebase
version	0.16.0
license	Apache-2.0
metadata	{"author":"NVIDIA Earth-2 Team","tags":["earth2studio","earth2","python","release","versioning","changelog"]}
description	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 example version tags, and pushing for PR. Use when releasing, cutting a release, preparing a release branch, rebasing a release, or bumping the version for a new development cycle.

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

1. Read earth2studio/__init__.py to get the current __version__ string.
2. Compute the next minor alpha: if current is X.Y.*-rc* (or X.Y.0rcN), the next version is X.(Y+1).0a0.
3. 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):

1. Has unused (empty) subsections removed.
2. Does not have the alpha/rc extension in its version (e.g., [0.14.0] not [0.14.0a0]).
3. 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.

1. 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.
2. Update the Docker container tag (e.g., nvcr.io/nvidia/pytorch:XX.YY-py3) to the latest recommended container version if it has changed.
3. 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.

1. Read docs/_static/switcher.json.
2. 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).
3. 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).

1. 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.
2. Read the current ## Latest News section in README.md.
3. 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.
4. 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.

1. Open .github/ISSUE_TEMPLATE/bug_report.yml.
2. Replace the placeholder: value (e.g., "example: 0.14.0") with "example: X.Y.0" (the new released version).
3. 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.