git 5.0.0.beta.1 → 5.0.0.beta.3

data/redesign/Phase 4 - Step A.md

@@ -0,0 +1,366 @@
+# Phase 4 / Step A — Remove Old Code: Execution Plan
+
+> **✅ Status: Complete.** All PRs in this plan (1a–1d, 2a–2c, 3a–3d, and the
+> atomic removal PR 4) have merged. The final removal landed in
+> [PR #1456](https://github.com/ruby-git/ruby-git/pull/1456) (commit `c1c53999`),
+> deleting `Git::Base`, `Git::Lib`, and the `base_object` / `from_base` bridge.
+> This document is retained as a historical record of how Step A was executed.
+
+## Goal
+
+Delete `Git::Base`, `Git::Lib`, and the `from_base`/`base_object` bridge in a
+single atomic breaking PR. The preceding PRs are strictly preparatory and
+backward-compatible — each is releasable independently unless a dependency is
+noted.
+
+---
+
+## Done-When Criteria
+
+- `lib/git/lib.rb` and `lib/git/base.rb` are deleted.
+- `Git::ExecutionContext::Repository` has no `base_object:` param, no
+  `attr_reader :base_object`, no `.from_base` factory, and no propagation of
+  `@base_object` in `dup_with`.
+- `grep -rEn 'Git::Lib|Git::Base' lib/` returns only YARD history comments,
+  no runtime references.
+- Entry-point behavior (`Git.open`, `.clone`, `.init`, `.bare`,
+  `.default_branch`, `.git_version`) still works entirely through
+  `Git::Repository` / command / parser paths.
+- Full CI pipeline (RSpec + Test::Unit + linters) is green after all removals.
+
+---
+
+## Sequencing
+
+PRs with no incoming edges may be merged in any order or in parallel. PR 4
+cannot begin until every other PR has merged.
+
+```mermaid
+graph TD
+    PR1a["PR 1a"]
+    PR1b["PR 1b"]
+    PR1c["PR 1c"]
+    PR1d["PR 1d"]
+    PR2a["PR 2a"]
+    PR2b["PR 2b"]
+    PR2c["PR 2c"]
+    PR3a["PR 3a"]
+    PR3b["PR 3b"]
+    PR3c["PR 3c"]
+    PR3d["PR 3d"]
+    PR4["PR 4"]
+
+    PR1a --> PR4
+    PR1b --> PR4
+    PR1c --> PR4
+    PR1d --> PR4
+    PR2a --> PR4
+    PR2b --> PR4
+    PR2c --> PR4
+    PR3a --> PR4
+    PR3b --> PR4
+    PR3c --> PR4
+    PR3d --> PR4
+```
+
+---
+
+## PR 1a — Rewire `Git.default_branch`
+
+**Releasable independently. No breaking changes.**
+
+In `lib/git.rb`, replace `Git.default_branch`'s delegation to
+`Base.repository_default_branch` with the direct
+`Git::Commands::LsRemote` + `Git::Parsers::LsRemote.parse_default_branch`
+flow.
+
+**Co-merge the spec that asserts the old delegation** — this rewire breaks an
+existing expectation, so its update must ship in this PR to keep CI green:
+
+- `spec/unit/git/git_remote_utilities_spec.rb` — the `.default_branch` example
+  asserts `expect(Git::Base).to receive(:repository_default_branch)`. Replace
+  it with a test against the direct `LsRemote` + parser path.
+
+(The `.repository_default_branch` example in `spec/unit/git/base_spec.rb` tests
+`Git::Base` directly, still passes, and is deleted by PR 3c — leave it alone
+here.)
+
+**Gate:** `Git.default_branch` works; full CI green.
+
+---
+
+## PR 1b — Rewire `Git.git_version`
+
+**Releasable independently. No breaking changes.**
+
+Move the git-version cache out of `Git::Lib` to a module-level cache on `Git`
+(in `lib/git.rb`) so that `Git.git_version` no longer routes through
+`Git::Lib`.
+
+- **Relocate the cache state.** Move the cache initialization currently in
+  `Git::Lib` (`@git_version_cache = {}` and `@git_version_cache_mutex =
+  Mutex.new`) to module-level instance variables on `Git` in `lib/git.rb`.
+  Keep the mutex — it guards parallelism on JRuby/TruffleRuby.
+- **Relocate the cache API.** Add `Git.cached_git_version(binary_path,
+  &block)` (memoize per binary path) and `Git.clear_git_version_cache`
+  (used by tests) as class methods on `Git`. Mark both `@api private`.
+- **Rewire the caller.** In `lib/git.rb`, change `Git.git_version` to call
+  `Git.cached_git_version` instead of `Git::Lib.cached_git_version`
+  ([lib/git.rb#L512](../lib/git.rb#L512)).
+- The instance method `Git::Lib#git_version` and the class methods on
+  `Git::Lib` are deleted wholesale in PR 4, so they need no rewiring here; do
+  not leave a second live cache behind.
+
+**Co-merge the specs that assert the old cache owner** — this rewire breaks
+existing expectations, so their updates must ship in this PR to keep CI green:
+
+- `spec/unit/git/git_configure_spec.rb` — replace the
+  `Git::Lib.clear_git_version_cache` setup and the
+  `expect(Git::Lib).to have_received(:cached_git_version)` assertion with
+  `Git.clear_git_version_cache` / `Git.cached_git_version`.
+- `spec/unit/git/git_version_spec.rb` — replace the
+  `before { Git::Lib.clear_git_version_cache }` setup with
+  `Git.clear_git_version_cache`; otherwise it clears the now-unused cache and
+  the new `Git` cache leaks across examples (flaky/failing per-binary-path
+  tests).
+
+**Gate:** `Git.git_version` works and caches per binary path; full CI green.
+
+---
+
+## PR 1c — Remove `require 'git/base'` from Domain Object Files
+
+**Releasable independently. No breaking changes.**
+
+Remove `require 'git/base'` from each of these files:
+`branch.rb`, `branches.rb`, `remote.rb`, `object.rb`, `log.rb`,
+`stash.rb`, `stashes.rb`, `worktree.rb`, `worktrees.rb`.
+
+This is safe because `lib/git.rb` still requires `git/base` and `git/lib`
+directly, so both constants remain loaded. The only effect is that `base.rb`
+is no longer force-loaded early (out of order) by the domain-object files;
+load order then depends entirely on `lib/git.rb`, which the CI gate verifies.
+Doing this early is beneficial — it shrinks PR 4 and exercises the
+`lib/git.rb` load order under CI ahead of the breaking change.
+
+> The removal of the `require 'git/lib'` / `require 'git/base'` lines from
+> `lib/git.rb` itself is **not** done here — that is the breaking change and is
+> folded into [PR 4](#pr-4--atomic-removal).
+
+**Gate:** full CI green; no `require 'git/base'` in domain object files.
+
+---
+
+## PR 1d — Update `{Git::Base}`/`{Git::Lib}` YARD Cross-References in Domain Object and Command Files
+
+**Releasable independently. Documentation only.**
+
+`.yardopts` sets `--fail-on-warning`, so any `{Git::Base#…}` or `{Git::Lib#…}` YARD
+cross-reference link that survives into PR 4 becomes a CI failure the moment
+`Git::Base` and `Git::Lib` are deleted. PRs 2a–2c cover the command layer,
+repository layer, and diff/status domain types, but five additional files have
+unresolved cross-references that are not covered by those PRs.
+
+### `lib/git/branch.rb`
+
+Replace two class-doc and one method-param cross-references:
+
+- Class docstring (lines 9–10): `{Git::Base#branch}` and `{Git::Base#branches}`
+  → `{Git::Repository#branch}` and `{Git::Repository#branches}`.
+- `attr_accessor :full` docstring (line 26): `{Git::Base#branches}`
+  → `{Git::Repository#branches}`.
+- `archive` method `@param opts` (line 149): `{Git::Base#archive}`
+  → `{Git::Repository#archive}`.
+
+### `lib/git/remote.rb`
+
+Replace two cross-references:
+
+- Class docstring (line 10): `{Git::Base#remote}` → `{Git::Repository#remote}`.
+- `fetch` method `@param opts` (line 63): `{Git::Base#fetch}`
+  → `{Git::Repository#fetch}`.
+
+### `lib/git/object.rb`
+
+- `archive` method `@param opts` (line 105): `{Git::Lib#archive}`
+  → `{Git::Repository#archive}`.
+
+### `lib/git/commands/base.rb`
+
+- `#initialize` `@param execution_context` (lines 176–177): change type from
+  `[Git::ExecutionContext, Git::Lib]` to `[Git::ExecutionContext]`; replace
+  `{Git::Lib#command_capturing}` / `{Git::Lib#command_streaming}` with
+  `{Git::ExecutionContext#command_capturing}` /
+  `{Git::ExecutionContext#command_streaming}`.
+- `with_stdin_pipe` inline doc (line 354): `{Git::Lib#command_capturing}`
+  → `{Git::ExecutionContext#command_capturing}`.
+
+### `lib/git/version.rb`
+
+- `to_a` docstring (line 103): demote `{Git::Lib#current_command_version}` from a
+  YARD cross-reference link to a code literal
+  (`Git::Lib#current_command_version`), since `Git::Lib` will not exist
+  after PR 4.
+
+**Gate:** linters and YARD doc build pass (`bundle exec rake rubocop yard build`);
+no behavior changes.
+
+---
+
+## PR 2a — Update Command-Layer YARD
+
+**Releasable independently. Documentation only.**
+
+- `lib/git/commands.rb` — update architecture diagram to reference
+  `Git::Repository` instead of `Git::Base`/`Git::Lib`.
+- `lib/git/command_line.rb` — update factory helper references.
+- `lib/git/command_line/capturing.rb`, `streaming.rb` — update
+  `@see Git::Lib#…` tags.
+
+**Gate:** linters and YARD doc build pass; no behavior changes.
+
+---
+
+## PR 2b — Update Repository-Layer YARD
+
+**Releasable independently. Documentation only.**
+
+- `lib/git/repository/path_resolver.rb` — update `Git::Base.config.binary_path`
+  reference.
+- `lib/git/repository/factories.rb` — update or remove deprecation message
+  strings mentioning `Git::Lib#clone`.
+
+**Gate:** linters and YARD doc build pass; no behavior changes.
+
+---
+
+## PR 2c — Update Domain Object `@param base` YARD Types
+
+**Releasable independently. Documentation only.**
+
+In `diff.rb`, `status.rb`, `diff_path_status.rb`, update `@param base`
+YARD type from `[Git::Base, Git::Repository]` → `[Git::Repository]`.
+
+**Gate:** linters and YARD doc build pass; no behavior changes.
+
+---
+
+## PR 3a — Delete Confirmed-Removable Test::Unit Files
+
+**Releasable independently. No production behavior changes.**
+
+Delete these files, which test removed API only and have no surviving
+behavioral value:
+
+| File | Reason |
+| --- | --- |
+| `tests/units/test_base.rb` | Tests `Git::Base` directly |
+| `tests/units/test_lib.rb` | Tests `Git::Lib` directly |
+| `tests/units/test_lib_repository_default_branch.rb` | Tests `Git::Lib` default-branch path |
+| `tests/units/test_lib_meets_required_version.rb` | Tests `Git::Lib` version deprecation shim |
+| `tests/units/test_git_base_root_of_worktree.rb` | Tests `Git::Base.root_of_worktree` |
+
+**Gate:** full CI green.
+
+---
+
+## PR 3b — Patch Incidental Test::Unit References
+
+**Releasable independently. No production behavior changes.**
+
+Audit all remaining `tests/units/` files for incidental `Git::Base`/`Git::Lib`
+references and patch them to use `Git::Repository` / `Git.open` entry points.
+Port any still-valuable behavioral coverage to RSpec before removing a file.
+
+**Gate:** full CI green; no `tests/units/` file references `Git::Base`
+or `Git::Lib` at runtime.
+
+---
+
+## PR 3c — Delete RSpec Specs Testing Only Removed API
+
+**Releasable independently. No production behavior changes.**
+
+| File | Reason |
+| --- | --- |
+| `spec/unit/git/base_spec.rb` | Tests `Git::Base` |
+| `spec/unit/git/lib_command_spec.rb` | Tests `Git::Lib` |
+| `spec/unit/git/lib_version_deprecations_spec.rb` | Tests `Git::Lib` version deprecation shims |
+| `spec/unit/git/lib/git_version_spec.rb` | Tests `Git::Lib` version cache |
+| `spec/integration/git/base/` (all files) | Tests `Git::Base` delegators |
+
+**Gate:** full CI green.
+
+---
+
+## PR 3d — Migrate RSpec Bridge and `from_base` References
+
+**Releasable independently. No production behavior changes.**
+
+- `spec/integration/git/repository/*_spec.rb` — replace `from_base` setup
+  with `Git::Repository.open(…)` or `ExecutionContext::Repository.from_hash`.
+- `spec/unit/git/execution_context/repository_spec.rb` — remove `from_base`
+  and `base_object` test contexts; keep all other execution context coverage.
+- `spec/unit/git/repository/remote_operations_spec.rb` — remove the
+  `base_object:` instance double.
+- `spec/integration/git/branches_spec.rb`, `worktrees_spec.rb` — two changes
+  each:
+  1. Remove the "initialized via `Git::Base`" context block entirely.
+  2. In the surviving "initialized via `Git::Repository`" context, replace the
+     `let(:execution_context) { Git::ExecutionContext::Repository.from_base(repo) }`
+     setup with `ExecutionContext::Repository.from_hash` or
+     `Git::Repository.open`.
+- `spec/integration/git/commands/init_spec.rb`, `clone_spec.rb` — replace
+  `Git::Lib.new(nil)` with a proper `ExecutionContext::Global` or
+  `ExecutionContext::Repository`.
+
+**Gate:** full CI green; no spec references `from_base` or `base_object`.
+
+---
+
+## PR 4 — Atomic Removal
+
+**Breaking change. Targets `main` (v5.x only). Cannot be further decomposed.**
+
+With all callers rewired (1a–1c), docs updated (2a–2c), and tests migrated
+(3a–3d), this PR is the single deletion event. Unloading `Git::Base` /
+`Git::Lib` is itself the breaking change, so it must happen here — after every
+test that references those constants (3a–3d) has been migrated.
+
+**Remove the legacy `require` lines from `lib/git.rb`**
+
+File: `lib/git.rb`
+- Remove `require 'git/lib'`.
+- Remove `require 'git/base'`.
+
+After this, `Git::Base` and `Git::Lib` are no longer loaded at runtime.
+
+**Remove the `ExecutionContext::Repository` bridge**
+
+File: `lib/git/execution_context/repository.rb`
+- Remove `base_object:` keyword and `@base_object = base_object` from `#initialize`.
+- Remove `attr_reader :base_object`.
+- Remove `base_object: @base_object` from `dup_with`.
+- Delete the `.from_base` class method.
+- Update `#initialize` YARD docs to drop the `base_object` param entry.
+
+**Delete legacy class files**
+- Delete `lib/git/lib.rb`.
+- Delete `lib/git/base.rb`.
+
+---
+
+## Done-Gates (All Must Pass Before PR 4 Merges)
+
+| Gate | How to verify |
+| --- | --- |
+| `lib/git/lib.rb` deleted | `ls lib/git/lib.rb` → not found |
+| `lib/git/base.rb` deleted | `ls lib/git/base.rb` → not found |
+| No `base_object` / `from_base` in `ExecutionContext::Repository` | Read file |
+| No `require 'git/lib'` / `require 'git/base'` anywhere in `lib/` | `grep -rEn "require 'git/(lib|base)'" lib/` returns nothing |
+| No runtime `Git::Lib` / `Git::Base` references in `lib/` | `grep -rEn 'Git::Lib|Git::Base' lib/` returns no code lines |
+| `Git.open`, `.clone`, `.init`, `.bare` return `Git::Repository` and work | Existing RSpec integration suite |
+| `Git.default_branch`, `Git.git_version` work without `Git::Lib` | Existing unit + integration specs |
+| Full RSpec suite green | `bundle exec rake spec:parallel` |
+| Full Test::Unit suite green | `bundle exec rake test:parallel` |
+| Linters pass | `bundle exec rake rubocop yard build` |

data/redesign/beta_release.md

@@ -0,0 +1,107 @@
+# Beta Release Process
+
+## Why This Is a Manual Process
+
+Pre-releases of the `git` gem (e.g., `5.0.0.beta.1`) are published manually rather
+than through the normal release-please automation. This is necessary because:
+
+- **release-please does not support Ruby pre-release version formats** such as
+  `5.0.0.beta.1`. release-please follows SemVer prerelease formatting and produces
+  versions with a dash separator (e.g., `5.0.0-beta.0`), which is incompatible with
+  RubyGems' dotted prerelease format (`5.0.0.beta.X`). For this reason,
+  `.release-please-config.json` explicitly sets `"prerelease": false` — there is no
+  configuration that makes release-please produce the right format.
+- **We want release-please to keep accumulating commits toward the final `5.0.0`
+  release.** If we merged a release-please PR for a beta version, it would update
+  `.release-please-manifest.json` and lose the record of changes that should appear
+  in the `5.0.0` changelog. By managing betas manually and leaving the manifest
+  untouched, release-please continues to build the `5.0.0` release PR in the
+  background.
+- **Beta tags use a `pre/` prefix** (e.g., `pre/v5.0.0.beta.1`) so that
+  release-please does not match them when searching for the last release SHA. This
+  keeps the change accumulation correct.
+
+---
+
+## Beta Release Checklist
+
+### 0. Set the beta number
+
+Set `BETA` once at the start of each session. All commands below use it.
+
+```bash
+BETA=2  # replace with the actual beta number
+```
+
+> **Note:** Steps 1–3 are done before merging the release PR; steps 4–6 are done
+> after. You will need to re-set `BETA` if you start a new shell session between
+> the two phases.
+
+### 1. Prepare the release branch
+
+```bash
+git switch main && git pull
+git switch -c release/5.0.0.beta.${BETA}
+```
+
+### 2. Update files
+
+- [ ] Bump `lib/git/version.rb`:
+
+  ```bash
+  sed -i "" "s/VERSION = '.*'/VERSION = '5.0.0.beta.${BETA}'/" lib/git/version.rb
+  ```
+
+- [ ] Update the announcement in `README.md`:
+  - Change the heading date and version number
+  - Update the % complete estimate
+  - Update the RubyGems link to point to the new version
+
+### 3. Commit and open a PR
+
+```bash
+git add lib/git/version.rb README.md
+git commit -m "chore: release v5.0.0.beta.${BETA}"
+git push -u origin release/5.0.0.beta.${BETA}
+```
+
+Open a PR targeting `main` and merge it once CI passes.
+
+> **Important:** Do **not** update `.release-please-manifest.json`. Leaving it at
+> the last stable 4.x release version is what allows release-please to keep
+> accumulating changes toward `5.0.0`.
+
+### 4. Tag the release commit
+
+Tag before building to ensure the gem and the GitHub release are pinned to the
+exact same commit. If `main` advances after the PR merges, building first and
+tagging later would cause the published gem and tag to diverge.
+
+```bash
+BETA=2  # re-set if this is a new shell session
+git switch main && git pull
+git tag pre/v5.0.0.beta.${BETA}
+git push origin pre/v5.0.0.beta.${BETA}
+```
+
+### 5. Build, publish, and create a GitHub release
+
+Check out the tag before building to guarantee the gem is built from the exact
+tagged commit, not from whatever `main` happens to be at build time.
+
+```bash
+git checkout pre/v5.0.0.beta.${BETA}
+bundle exec rake build
+gem push pkg/git-5.0.0.beta.${BETA}.gem
+
+gh release create pre/v5.0.0.beta.${BETA} \
+  pkg/git-5.0.0.beta.${BETA}.gem \
+  --title "v5.0.0.beta.${BETA}" \
+  --notes "Beta ${BETA} pre-release of v5.0.0. See the README for details." \
+  --prerelease
+```
+
+### 6. Verify
+
+- [ ] RubyGems: `https://rubygems.org/gems/git/versions/5.0.0.beta.${BETA}`
+- [ ] GitHub release: `https://github.com/ruby-git/ruby-git/releases/tag/pre/v5.0.0.beta.${BETA}`