gitea/.codex-script-notes.md

Codex Script Notes

This file is a fast-reference companion for the large local helper scripts.

.maintain-custom-release.sh

Purpose:

• maintain a custom stable branch such as release/v1.26-custom
• start from BASE_TAG
• fetch and sync upstream compare / release-target refs explicitly
• cherry-pick selected custom work from a local source branch

Current interaction model:

• interactive menu with submenus:
  • Manual Backups >
  • Fetch upstreams >
  • Sync >
  • Rollback >
  • Restore >
• submenu navigation:
  • Enter or b / B => Back
  • 0 => Exit

Persistent runtime state:

• runtime copy: /tmp/.maintain-custom-release.sh
• persisted settings: /tmp/.maintain-custom-release.env
• restore points: .git/.maintain-custom-release-restore-points/
• snapshots: .git/.maintain-custom-release-snapshots/
• active state file: .git/.maintain-custom-release-state

Recommended order:

1. Bootstrap maintenance branch
2. Fetch upstream/main compare ref
3. Fetch upstream release target ref
4. Show import plan
5. Sync actions as needed

Important behavior:

• bootstrap should only create/switch the maintenance branch from BASE_TAG; it should not fetch automatically
• rollback should remove bootstrap-created maintenance branches and clean script-managed refs/artifacts
• deleting a saved exact snapshot should also remove its paired backup/maint-* Git Graph marker

.update-gitea.sh

Purpose:

• safe upstream sync helper for the working tree
• create safety backups before real sync actions
• provide dry-run, rollback, restore-stash, and restore-snapshot

Key safety expectations:

• dry-run must not modify the real repository
• real sync actions must preserve enough state for exact rollback

.import-upstream-cherry-pick.sh

Purpose:

• import upstream commits through git cherry-pick -x
• support commit-by-commit or range-based import

Key safety expectations:

• save backup branch, snapshot, and stash before real import actions
• support continue, rollback, restore-stash, and restore-snapshot