MAPL3 Transition Plan - GEOS-ESM/MAPL GitHub Wiki

MAPL v3 Transition Plan

This page documents the strategy for transitioning MAPL's mainline development from MAPL v2 (main/develop) to MAPL v3 (release/MAPL-v3).

Background

As of the time of writing, the branch structure is:

Branch Content
main MAPL v2 — stable releases
develop MAPL v2 — integration branch for new features
release/MAPL-v3 MAPL v3 — active v3 development

The goal is to make develop and eventually main the home of MAPL v3, while preserving a long-term support branch for MAPL v2.

Target Branch Structure (post-transition)

Branch Content
main MAPL v3 — stable releases (once v3.0.0 is declared stable)
develop MAPL v3 — active development, pre-release tags cut here
release/v2 MAPL v2 — long-term support, ad hoc patches only
release/MAPL-v3 Retired after CI migration is complete

Pre-release Tagging Strategy (Option A)

During the alpha/beta/rc period, main will remain at the last stable MAPL v2 release. Pre-release tags (v3.0.0-alpha.0, v3.0.0-beta.0, etc.) will be cut from develop. Only when the team declares v3 stable will develop be merged into main and tagged v3.0.0.

This preserves the invariant that main = stable and trustworthy.

develop  →  v3.0.0-alpha.0, v3.0.0-alpha.1, ...
            v3.0.0-beta.0, v3.0.0-beta.1, ...
            v3.0.0-rc.0, ...
main     →  v3.0.0  (first stable v3 tag, when team declares ready)

release/v2  →  v2.x.y patches (ad hoc, gatekept by @mathomp4)

CHANGELOG.md pre-release entries should use standard dated Keep-a-Changelog version blocks, e.g. ## [3.0.0-alpha.0] - YYYY-MM-DD.

Phase 0 — Pre-Transition

Goal: Get MAPL v2 into a clean final state before any branch changes.

  • Cut the final MAPL v2 release (e.g., v2.69.0) from develop/main
  • Create release/v2 branch from main at that final v2 tag
  • Notify downstream users that develop and main are about to become MAPL v3, and that release/v2 is where v2 patches will live going forward
  • Update components.yaml in all downstream fixtures that pin MAPL — any entry with develop: develop must be changed to develop: release/v2 so that mepo develop continues to track the MAPL v2 line until those fixtures are ready to migrate to MAPL v3. For example:
      # Before
      MAPL:
        local: ./src/Shared/@MAPL
        remote: ../MAPL.git
        tag: v2.68.0
        develop: develop

      # After (for fixtures staying on v2)
      MAPL:
        local: ./src/Shared/@MAPL
        remote: ../MAPL.git
        tag: v2.68.0
        develop: release/v2

  **Note:** Once a fixture is ready to migrate to MAPL v3, update the `tag` to the
  appropriate v3 pre-release and change `develop` back to `develop`.
  • Before removing v2 history from CHANGELOG.md: ensure the MAPL2→MAPL3 differences document is finalized and merged. This document is currently in draft PR #4555 (docs/mapl3/diffs-from-mapl2.md). It also has outstanding peer review items from @atrayano and @bena-nasa that need to be resolved before the PR can be merged. > TODO: Once PR #4555 is merged, update the CHANGELOG pointer and any wiki links to > reference the final document location (docs/mapl3/diffs-from-mapl2.md).

Phase 1 — The Merge

Goal: Bring MAPL v3 into develop.

Since all commits in main and develop have already been merged up into release/MAPL-v3, the merge should be clean with no conflicts expected.

  • Open PR: release/MAPL-v3 → develop
  • As part of that PR (or immediately after), trim CHANGELOG.md:
    • Remove all v2 history
    • Keep only the [v3.0.0 - Development] section and forward
    • Add a note at the top pointing readers to the MAPL2→MAPL3 differences document (currently draft PR #4555; update the link to the final docs/mapl3/diffs-from-mapl2.md once merged)
  • Bump CMakeLists.txt version to 3.0.0-alpha.0 (or agreed pre-release identifier) on develop
  • Tag develop as v3.0.0-alpha.0
  • Do not merge to main yet — main stays at v2 until v3 is declared stable (see Phase 4)

Phase 2 — GitHub Branch Protection

  • Add branch protection rules to release/v2 (mirror what develop currently has)
  • Leave release/MAPL-v3 protected for now — do not delete or unprotect until all CI and Discover nightly tests are migrated (see Phase 3)
  • Once release/MAPL-v3 is fully retired: delete the branch (protection rules go away with it)

Phase 3 — CI/CD Migration

Keep release/MAPL-v3 alive until every item in this phase is completed.

GitHub Actions

File Change needed
push-to-develop.yml Delete — no longer needed (its purpose was auto-backflow from develop → release/MAPL-v3)
push-to-main.yml No change — main → develop auto-PR remains correct
scheduled_workflows.yml Replace release/MAPL-v3 with release/v2
cdash-nightly.yml Change default branch from release/MAPL-v3 to develop
mapl3docs.yml Change trigger branch from release/MAPL-v3 to develop
labeler.yml Change auto-label trigger from PRs targeting release/MAPL-v3 to release/v2
changelog-enforcer.yml Change skip condition from release/MAPL-v3 base to release/v2 base
dependabot.yml No change — already targets develop
docs.yml No change — triggers on main and v* tags; will naturally serve v3 docs once main is v3
  • Delete push-to-develop.yml
  • Update scheduled_workflows.yml: release/MAPL-v3 → release/v2
  • Update cdash-nightly.yml: default branch → develop
  • Update mapl3docs.yml: trigger branch → develop
  • Update labeler.yml: target branch → release/v2
  • Update changelog-enforcer.yml: skip base → release/v2

Ford Documentation

Two separate workflows handle Ford docs and this separation should be maintained:

  • docs.yml (stable docs): continues to deploy from main and v* tags — no change needed. During the alpha/beta period it will serve v2 docs, which is correct since main is still v2. Once main becomes v3 (Phase 4), it will automatically serve v3 stable docs.
  • mapl3docs.yml (dev docs): change trigger to develop so v3 development docs are always up to date. This is separate from the stable docs intentionally.

NASA Discover Nightly Tests

  • Update all nightly test scripts/configs on Discover that reference release/MAPL-v3
  • Point v3 nightly runs at develop
  • Point v2 nightly runs (if retained) at release/v2

Note: This is a manual step that is easy to forget — make sure it is done before retiring release/MAPL-v3.

CircleCI

  • Verify that no CircleCI config or orb invocation hardcodes release/MAPL-v3 (CircleCI is currently only triggered on releases for Docker image builds, so this may be a no-op)

Retire release/MAPL-v3

Once all of the above are done:

  • Delete release/MAPL-v3 branch

Phase 4 — Completing the Transition (when v3 is stable)

When the team is ready to declare v3 stable:

  • Merge develop → main
  • Tag main as v3.0.0
  • docs.yml will now automatically deploy v3 stable Ford docs from main — no action needed

Phase 5 — Documentation & Wiki

  • Update README.md in the main repo — branch descriptions, badges, any v2 references
  • Update Home — add section describing the new branch structure
  • Flesh out MAPL-V3 — currently a placeholder
  • Flesh out MAPL3---changes-from-MAPL2 — do this in Phase 0, before trimming CHANGELOG; note that a comprehensive in-repo version exists as docs/mapl3/diffs-from-mapl2.md in draft PR #4555 — confirm whether the wiki page is still needed once that PR merges
  • Write new wiki page: Branch-and-Release-Strategy — documents main/develop/release/v2 model, pre-release tagging, and gatekeeping
  • Write new wiki page: Migrating-from-MAPL2-to-MAPL3 — guide for downstream consumers

Master Checklist

A condensed view of all action items across all phases.

Phase 0 — Pre-Transition

  • Cut final MAPL v2 release from main
  • Create release/v2 branch at that tag
  • Notify downstream users
  • Update components.yaml in all downstream fixtures: change develop: develop → develop: release/v2 for fixtures staying on MAPL v2
  • Flesh out MAPL3---changes-from-MAPL2.md wiki page from existing CHANGELOG v2 history (or confirm that PR #4555 — docs/mapl3/diffs-from-mapl2.md — supersedes this)

Phase 1 — The Merge

  • Open PR: release/MAPL-v3 → develop
  • Trim CHANGELOG.md — remove v2 history, add pointer to differences wiki page
  • Bump CMakeLists.txt version to 3.0.0-alpha.0 on develop
  • Tag v3.0.0-alpha.0 on develop

Phase 2 — Branch Protection

  • Add branch protection to release/v2
  • (After Phase 3) Delete release/MAPL-v3

Phase 3 — CI/CD Migration

  • Delete push-to-develop.yml
  • Update scheduled_workflows.yml: release/MAPL-v3 → release/v2
  • Update cdash-nightly.yml: default branch → develop
  • Update mapl3docs.yml: trigger branch → develop
  • Update labeler.yml: target branch → release/v2
  • Update changelog-enforcer.yml: skip base → release/v2
  • Update Discover nightly test configs: release/MAPL-v3 → develop
  • Verify CircleCI has no hardcoded release/MAPL-v3 references
  • Delete release/MAPL-v3 branch

Phase 4 — Stable Release (future)

  • Merge develop → main
  • Tag v3.0.0 on main

Phase 5 — Documentation

  • Update README.md
  • Update Home.md
  • Flesh out MAPL-V3.md
  • Write Branch-and-Release-Strategy.md
  • Write Migrating-from-MAPL2-to-MAPL3.md