SubMiner/initial-release.md

Initial Release Git History Cleanup Plan

Recommendation

Given the current main history shape (325 commits, heavy refactor churn, and many internal maintenance commits), the best pre-release cleanup path is:

1. Preserve the old main history in remote backup refs.
2. Build a new orphan history from the current project snapshot.
3. Recreate history as 7 curated commits grouped by release-facing domains.
4. Verify tree equality with old main and replace origin/main once.

This avoids fragile rebase -i --root over 300+ commits while still keeping meaningful archaeology for future maintenance.

Why this is best for this repo

• Current history is dominated by refactor/noise commits (refactor: 138, other: 91).
• Commit velocity is very high and bursty (multiple 30-45 commit days), so interactive cleanup is risky/time-expensive.
• Codebase is already mature and release-shaped (Electron app + launcher + plugin + docs + CI), so snapshot regrouping is cleaner.
• You are pre-release and private; a one-time force update is low risk if coordinated.

---

Pre-cutover checklist

Run from repository root.

git checkout main
git pull --ff-only origin main

Coordinate freeze:

• Pause merges/pushes to main.
• Ask teammates to stop rebasing onto main during cutover.

---

Copy/paste command sequence

1) Safety backups (local + remote)

set -euo pipefail

git checkout main
git pull --ff-only origin main

OLD_MAIN_COMMIT="$(git rev-parse main)"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"

echo "Old main commit: ${OLD_MAIN_COMMIT}"
echo "Cutover stamp: ${STAMP}"

git tag "pre-release-history-backup-${STAMP}" "${OLD_MAIN_COMMIT}"
git branch "archive/pre-release-history-${STAMP}" "${OLD_MAIN_COMMIT}"

git push origin "pre-release-history-backup-${STAMP}"
git push origin "archive/pre-release-history-${STAMP}"

2) Handle dirty workspace safely

If git status --short is not empty:

git stash push -u -m "initial-release-history-cleanup-${STAMP}"

3) Build new clean history on orphan branch

git checkout --orphan release/main-clean
git reset

Now create curated commits.

# Commit 1: repository scaffolding and build toolchain
git add .gitignore .gitmodules .npmrc .prettierignore .prettierrc.json AGENTS.md LICENSE Makefile package.json bun.lock tsconfig.json tsconfig.renderer.json build scripts .github
git commit -m "chore: bootstrap repository tooling and release automation"

# Commit 2: core desktop app runtime
git add src
git commit -m "feat(core): add Electron runtime, services, and app composition"

# Commit 3: launcher and mpv plugin integration
git add launcher plugin subminer
git commit -m "feat(integration): add launcher and mpv plugin workflows"

# Commit 4: bundled assets and vendor payloads
git add assets vendor
git commit -m "feat(assets): bundle runtime assets and vendor dependencies"

# Commit 5: test suites and verification harnesses
git add tests
git commit -m "test: add regression suites and harness coverage"

# Commit 6: documentation and examples
git add README.md docs config.example.jsonc
git commit -m "docs: add setup guides, architecture docs, and config examples"

# Commit 7: project/backlog metadata and remaining files (if any)
git add -A
if ! git diff --cached --quiet; then
  git commit -m "chore: add project management metadata and remaining repository files"
fi

4) Validate tree equivalence to old main snapshot

git diff --stat "${OLD_MAIN_COMMIT}^{tree}" HEAD^{tree}
git diff --name-status "${OLD_MAIN_COMMIT}^{tree}" HEAD^{tree}

Expected: no output. If output exists, stop and inspect before pushing.

5) Replace origin/main

git push --force-with-lease origin release/main-clean:main

6) Tag cleaned initial-release baseline

git fetch origin
git checkout main
git reset --hard origin/main
git tag "v0.1.0-initial-clean-history"
git push origin "v0.1.0-initial-clean-history"

7) Restore local stashed work (if stashed earlier)

git stash list
git stash pop

---

Team resync message (send after cutover)

main history was rewritten for initial release cleanup.

If you have no local work:
  git fetch origin
  git checkout main
  git reset --hard origin/main

If you have local work:
  git fetch origin
  git checkout -b backup/<name>-before-main-rewrite
  # then rebase/cherry-pick your feature commits onto new origin/main

---

Notes

• This plan intentionally avoids git rebase -i --root to reduce conflict risk.
• --force-with-lease is mandatory safety rail.
• Keep the backup tag/branch until after public release stabilization.