git 5.0.0.beta.3 → 5.0.0.beta.4

data/.github/skills/yard-documentation/element-rules.md

@@ -0,0 +1,162 @@
+# YARD Element-Specific Rules
+
+Per-element YARD requirements for classes, modules, constants, attributes,
+dynamically defined methods, and value objects
+(`Data.define` / `Struct.new`).
+
+Consult this file when documenting one of those elements. Rules that apply to
+**every** doc comment (formatting, length limits, tag order) and to **methods**
+live in [SKILL.md](SKILL.md).
+
+## Contents
+
+- [Contents](#contents)
+- [Classes](#classes)
+- [Modules](#modules)
+- [Constants](#constants)
+- [Attributes](#attributes)
+- [Dynamically defined methods (`@!method`)](#dynamically-defined-methods-method)
+- [`Data.define` classes](#datadefine-classes)
+- [`Struct.new` classes](#structnew-classes)
+
+## Classes
+
+- One-sentence class description as a **noun phrase** (or starting with "Represents…") — the description should pass
+  the "This class is a…" litmus test (i.e. you should be able to prefix "This class
+  is a" and produce a grammatical sentence). "Represents…" is an accepted convention.
+  Do not start descriptions with "This class is…", "Provides…", or "Encapsulates…".
+  - Good: `Wrapper around the git binary`, `Immutable value object for a branch
+    delete result`, `Represents a git branch`
+  - Bad: `This class wraps the git binary`, `Provides branch deletion`,
+    `Encapsulates branch state`
+- `@api public` or `@api private` tag to declare visibility — use `@api public` for
+  stable user-facing classes; use `@api private` for internal implementation classes
+  (e.g., `Git::ExecutionContext::*`, `Git::Commands::*`, parsers)
+- At least one `@example` showing typical instantiation or primary usage — this
+  applies to all classes including `@api private` classes
+- Error/exception classes must also state when the error is raised in class-level
+  prose, using caller-facing wording such as `Raised when branch deletion fails`
+- Deprecated classes must include `@deprecated` explaining the migration path
+- When present, class-level tags must appear in this order: `@example`, `@note`,
+  `@deprecated`, `@see`, `@api`, `@abstract`
+
+## Modules
+
+- One-sentence description — "Namespace for…", "Provides helpers for…", or
+  "Mixin that adds…"
+- `@api public` or `@api private` — use `@api public` for stable user-facing modules;
+  use `@api private` for internal implementation modules
+- No `@example` required unless the module provides standalone methods
+- Deprecated modules must include `@deprecated` explaining the migration path
+- When present, module-level tags must appear in the same order as class-level
+  tags: `@example`, `@note`, `@deprecated`, `@see`, `@api`
+
+## Constants
+
+- A comment immediately above the constant describing its purpose and valid values
+- No special YARD tag is needed; YARD picks up the preceding comment automatically
+- Add `# @return [Type]` when the constant holds a collection, frozen structure, or
+  domain-specific type whose shape is not immediately obvious from the value
+
+## Attributes
+
+- For explicitly written `attr_reader`, `attr_accessor`, and `attr_writer` declarations,
+  place the documentation directly above the attribute; do **not** use the `@!attribute`
+  directive
+- For dynamically created attributes, `Data.define` members, or `Struct.new`
+  members, you **must** use a `# @!attribute [r/rw/w] name` YARD directive
+- Must include `@return [Type] description` explaining the value and its units or
+  constraints if relevant
+- For explicit `attr_reader`/`attr_accessor`/`attr_writer`, include a short
+  description paragraph above the attribute in addition to `@return`
+- For `@!attribute` directives (in `Data.define` / `Struct.new`), the `@return`
+  tag inside the directive block serves as the sole documentation — no separate
+  short description is needed
+- Tags inside `@!attribute` (and `@!method`) directive blocks must be indented
+  two extra spaces relative to the directive itself
+- Must be defined at the class level, not inside method bodies
+
+## Dynamically defined methods (`@!method`)
+
+Use the `# @!method name(params)` directive for methods created via
+metaprogramming (`define_method`, method-generating DSLs, etc.) that have no
+literal `def`. Place the directive and its doc comment where the method would
+logically appear in the class body. Tags inside the directive block follow the
+same indentation rule as `@!attribute` — indented two extra spaces relative to
+the directive.
+
+If an `@!method` block uses `@overload`, follow overload tag-placement rules in
+[SKILL.md](SKILL.md): keep `@return` inside each overload, keep shared
+`@raise` at top level, and keep `@api` at top level.
+
+## `Data.define` classes
+
+Immutable value objects defined with `Data.define` use the following conventions
+(see `Git::BranchDeleteFailure` for a canonical example):
+
+- Class-level doc: noun-phrase short description, `@example`, `@see`, `@api`
+- One `@!attribute [r]` directive per member with `@return [Type] description`
+- Attribute directives are placed after class-level tags and before the
+  `Data.define` line
+- Custom methods defined inside the `Data.define` block follow standard method
+  rules
+
+```ruby
+# Immutable value object for a failed branch delete
+#
+# @example Create a failure object
+#   failure = BranchDeleteFailure.new(
+#     name: 'nonexistent',
+#     error_message: "branch 'nonexistent' not found."
+#   )
+#   failure.name          #=> 'nonexistent'
+#   failure.error_message #=> "branch 'nonexistent' not found."
+#
+# @see Git::BranchDeleteResult
+#
+# @api public
+#
+# @!attribute [r] name
+#
+#   @return [String] the branch name that failed to delete
+#
+# @!attribute [r] error_message
+#
+#   @return [String] the git error message explaining the failure
+#
+BranchDeleteFailure = Data.define(:name, :error_message)
+```
+
+## `Struct.new` classes
+
+Document `Struct.new` classes using the same conventions as `Data.define` classes:
+class-level doc with a noun-phrase short description, `@example`, `@see`, `@api`,
+and one `@!attribute` directive per member with `@return [Type] description`.
+
+Unlike `Data.define`, a `Struct.new` class is **mutable** — it generates
+read-write accessors — so use `@!attribute [rw]` (not `[r]`) for its members and
+do not describe it as immutable.
+
+```ruby
+# Value object for a diff hunk's location within a file
+#
+# @example Create and update a hunk location
+#   loc = HunkLocation.new(start_line: 10, line_count: 3)
+#   loc.start_line #=> 10
+#   loc.line_count = 4
+#   loc.line_count #=> 4
+#
+# @see Git::DiffInfo
+#
+# @api public
+#
+# @!attribute [rw] start_line
+#
+#   @return [Integer] the 1-based line where the hunk begins
+#
+# @!attribute [rw] line_count
+#
+#   @return [Integer] the number of lines the hunk spans
+#
+HunkLocation = Struct.new(:start_line, :line_count, keyword_init: true)
+```

data/.github/skills-deprecated/README.md

@@ -0,0 +1,21 @@
+# Deprecated skills
+
+This directory holds skills that have been **retired** from active use. They are
+kept on disk for historical reference only — they are intentionally located outside
+`.github/skills/` so they are not auto-discovered or loaded into agent context.
+
+## Retired skills
+
+- **`extract-command-from-lib/`** — guided migrating a `Git::Lib` `#command` call
+  into a `Git::Commands::*` class during the v5.0.0 architectural redesign.
+- **`extract-facade-from-base-lib/`** — guided migrating a public method from
+  `Git::Base` / `Git::Lib` into a `Git::Repository::*` facade method during the same
+  redesign.
+- **`review-backward-compatibility/`** — audited `Git::Lib` methods for backward
+  compatibility during the migration to `Git::Commands::*`. `Git::Lib` was deleted in
+  PR #1456 as part of Phase 4 Step A; this workflow no longer applies.
+
+The extract-* skills describe migration work that is now complete: `Git::Base` and
+`Git::Lib` have been removed from the codebase, so there is nothing left to extract.
+All three skills remain here as a record of the workflow used during the migration,
+in case similar work is needed again in the future.

data/.github/{skills → skills-deprecated}/extract-command-from-lib/SKILL.md

@@ -55,22 +55,22 @@ from the `#command` call (or both).
 
 Before starting, you **MUST** load the following skill(s) in their entirety:
 
-- [YARD Documentation](../yard-documentation/SKILL.md) — authoritative
+- [YARD Documentation](../../skills/yard-documentation/SKILL.md) — authoritative
   source for YARD formatting rules and writing standards;
 
 ## Related skills
 
 Run or reference these skills during the workflow:
 
-- [Command Implementation](../command-implementation/SKILL.md) — generates and reviews `Git::Commands::*`
+- [Command Implementation](../../skills/command-implementation/SKILL.md) — generates and reviews `Git::Commands::*`
   classes, unit tests, integration tests, and YARD docs (used in Step 4 if the
   command class does not exist yet); also the canonical class-shape checklist,
   phased rollout gates, and internal compatibility contracts
-- [Review Arguments DSL](../review-arguments-dsl/SKILL.md) — verifying DSL entries match git CLI
-- [Command Test Conventions](../command-test-conventions/SKILL.md) — unit/integration test conventions for command classes
-- [Command YARD Documentation](../command-yard-documentation/SKILL.md) — documentation completeness for command classes
-- [Review Cross-Command Consistency](../review-cross-command-consistency/SKILL.md) — sibling consistency within a command family
-- [Review Backward Compatibility](../review-backward-compatibility/SKILL.md) — preserving `Git::Lib` return-value contracts
+- [Review Arguments DSL](../../skills/review-arguments-dsl/SKILL.md) — verifying DSL entries match git CLI
+- [Command Test Conventions](../../skills/command-test-conventions/SKILL.md) — unit/integration test conventions for command classes
+- [Command YARD Documentation](../../skills/command-yard-documentation/SKILL.md) — documentation completeness for command classes
+- [Review Cross-Command Consistency](../../skills/review-cross-command-consistency/SKILL.md) — sibling consistency within a command family
+- [Review Backward Compatibility](../../skills/review-backward-compatibility/SKILL.md) — preserving `Git::Lib` return-value contracts
 - [Extract Facade from Base/Lib](../extract-facade-from-base-lib/SKILL.md) — the
   follow-on extraction that moves the public method from `Git::Base` /
   `Git::Lib` into a `Git::Repository::*` facade method (Phase 4 deletes both
@@ -192,7 +192,7 @@ Before making any changes, verify that `tests/units/` has adequate tests for the
 2. **If the command class already exists**, skip to Step 5.
 
 3. **If the command class does not exist**, scaffold it using the
-  [Command Implementation](../command-implementation/SKILL.md) skill. This produces:
+  [Command Implementation](../../skills/command-implementation/SKILL.md) skill. This produces:
 
    - `lib/git/commands/<command>.rb` (or `lib/git/commands/<family>/<action>.rb`)
    - `spec/unit/git/commands/<command>_spec.rb`
@@ -292,7 +292,7 @@ changes were needed for that step):
 
 During implementation, you may use multiple task-level commits. Before opening a
 PR, follow the repository finalize workflow (see
-[Development Workflow](../development-workflow/SKILL.md)) and squash commits as
+[Development Workflow](../../skills/development-workflow/SKILL.md)) and squash commits as
 required.
 
 **Issue and PR references in commit bodies:** Do not use `#<number>` in the

data/.github/{skills → skills-deprecated}/extract-facade-from-base-lib/SKILL.md

@@ -67,24 +67,24 @@ Extract Facade: Git::Lib#branches_all (called publicly via g.lib.branches_all)
 
 Before starting, you **MUST** load the following skill(s):
 
-- [Facade Implementation](../facade-implementation/SKILL.md) — drives the actual
+- [Facade Implementation](../../skills/facade-implementation/SKILL.md) — drives the actual
   scaffolding of the new facade method
-- [YARD Documentation](../yard-documentation/SKILL.md) — baseline YARD rules
+- [YARD Documentation](../../skills/yard-documentation/SKILL.md) — baseline YARD rules
 
 ## Related skills
 
-- [Facade Implementation](../facade-implementation/SKILL.md) — used in Step 5 to
+- [Facade Implementation](../../skills/facade-implementation/SKILL.md) — used in Step 5 to
   scaffold the new facade method
-- [Facade Test Conventions](../facade-test-conventions/SKILL.md) — unit and
+- [Facade Test Conventions](../../skills/facade-test-conventions/SKILL.md) — unit and
   integration test conventions for the new facade method
-- [Facade YARD Documentation](../facade-yard-documentation/SKILL.md) — YARD docs
+- [Facade YARD Documentation](../../skills/facade-yard-documentation/SKILL.md) — YARD docs
   for the new facade module/method
 - [Extract Command from Lib](../extract-command-from-lib/SKILL.md) — sibling
   extraction skill that moves the underlying CLI call into a
   `Git::Commands::*` class. **Run first** when no command class exists yet.
-- [Command Implementation](../command-implementation/SKILL.md) — used in Step 4
+- [Command Implementation](../../skills/command-implementation/SKILL.md) — used in Step 4
   if a new `Git::Commands::*` class needs to be scaffolded
-- [Project Context](../project-context/SKILL.md) — three-layer architecture and
+- [Project Context](../../skills/project-context/SKILL.md) — three-layer architecture and
   Phase 4 deletion plan
 
 ## Input
@@ -126,7 +126,7 @@ implementation.
 > When migrating, the facade method **must** preserve this signature exactly
 > (e.g. `commit(message, opts = {})`) — even though greenfield facade methods
 > would prefer `**options` per
-> [facade-implementation REFERENCE.md — Choosing the method signature](../facade-implementation/REFERENCE.md#choosing-the-method-signature).
+> [facade-implementation REFERENCE.md — Choosing the method signature](../../skills/facade-implementation/REFERENCE.md#choosing-the-method-signature).
 > The legacy public contract wins during migration.
 
 ### Pattern B — `Git::Lib`-only (public-by-exposure)
@@ -286,11 +286,11 @@ Also state:
 - For `legacy-contract` methods, confirm the exact 4.x call shape is preserved
   verbatim (including rare `**opts` signatures).
 - Whether a new topic module is required (justify per
-  [facade-implementation REFERENCE.md](../facade-implementation/REFERENCE.md#decision-rules-for-adding-a-new-module)).
+  [facade-implementation REFERENCE.md](../../skills/facade-implementation/REFERENCE.md#decision-rules-for-adding-a-new-module)).
   When extracting one method at a time, scan `Git::Base` / `Git::Lib` for
   siblings on the same git topic and check
   `redesign/3_architecture_implementation.md` before deciding — see
-  [One-at-a-time extraction](../facade-implementation/REFERENCE.md#one-at-a-time-extraction-from-gitbase--gitlib).
+  [One-at-a-time extraction](../../skills/facade-implementation/REFERENCE.md#one-at-a-time-extraction-from-gitbase--gitlib).
 - The delegation strategy for `Git::Base` and/or `Git::Lib` (Step 6) — both
   remain in place during the migration window and delegate to the new facade.
 - For Pattern B: explicit note that `g.lib.foo` callers will need to migrate
@@ -338,7 +338,7 @@ preserves backward compatibility.
 The facade method calls one or more `Git::Commands::*` classes. If any required
 command class does not exist yet, scaffold it first using
 [Extract Command from Lib](../extract-command-from-lib/SKILL.md) (which in turn
-uses [Command Implementation](../command-implementation/SKILL.md)).
+uses [Command Implementation](../../skills/command-implementation/SKILL.md)).
 
 For Pattern C migrations, the source `Git::Base` method may not currently call
 through a `Git::Commands::*` class at all (it uses `command(...)` directly or
@@ -349,7 +349,7 @@ Skip this step when every required command class already exists.
 
 ### Step 5 — Implement the facade method
 
-Delegate to the [Facade Implementation](../facade-implementation/SKILL.md) skill
+Delegate to the [Facade Implementation](../../skills/facade-implementation/SKILL.md) skill
 in **Scaffold** or **Update** mode. That skill handles:
 
 - topic module selection

data/.github/workflows/continuous_integration.yml

@@ -21,15 +21,16 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Only the latest versions of JRuby and TruffleRuby are tested
+        # Only the minimum required versions of JRuby and TruffleRuby are tested
         ruby: ["3.2", "3.4", "4.0", "truffleruby-24.2.1", "jruby-10.0.0.1"]
         operating-system: [ubuntu-latest]
         experimental: [No]
         java_version: [""]
         include:
-          - ruby: 3.2
+          - ruby: "3.2"
             operating-system: windows-latest
             experimental: No
+            java_version: ""
 
     steps:
       - name: Checkout Code

data/.rubocop.yml

@@ -7,53 +7,21 @@ inherit_mode:
   merge:
     - Exclude
 
-# Don't care about complexity offenses in the TestUnit tests This exclusions
-# will be removed when we switch to RSpec.
-Metrics/CyclomaticComplexity:
-  Exclude:
-    - "tests/test_helper.rb"
-    - "tests/units/**/*"
-
-Metrics/ClassLength:
-  Exclude:
-    - "tests/test_helper.rb"
-    - "tests/units/**/*"
-
-Metrics/AbcSize:
-  Exclude:
-    - "tests/test_helper.rb"
-    - "tests/units/**/*"
-
-# Don't care so much about length of methods in tests
-Metrics/MethodLength:
-  Exclude:
-    - "tests/test_helper.rb"
-    - "tests/units/**/*"
-
-# Allow test data to have long lines
-Layout/LineLength:
+# lib/git.rb is the gem's main entry-point module and is expected to be long
+Metrics/ModuleLength:
   Exclude:
-    - "tests/test_helper.rb"
-    - "tests/units/**/*"
-    - "*.gemspec"
+    - "lib/git.rb"
 
-# Testing, gemspec, and command DSL blocks are intentionally long
+# gemspec and command DSL blocks are intentionally long
 Metrics/BlockLength:
   Exclude:
-    - "tests/test_helper.rb"
-    - "tests/units/**/*"
     - "*.gemspec"
     - "lib/git/commands/**/*.rb"
 
-# lib/git.rb is the gem's main entry-point module and is expected to be long
-Metrics/ModuleLength:
-  Exclude:
-    - "lib/git.rb"
-
-# Don't force every test class to be described
-Style/Documentation:
+# Allow gemspec to have long lines
+Layout/LineLength:
   Exclude:
-    - "tests/units/**/*"
+    - "*.gemspec"
 
 Style/OneClassPerFile:
   Enabled: false

data/.yard-lint.yml

@@ -0,0 +1,75 @@
+# Configuration for yard-lint (https://github.com/mensfeld/yard-lint)
+#
+# This config enforces the project's YARD documentation standards as described
+# in .github/skills/yard-documentation/SKILL.md. It replaces the retired
+# yardstick audit/coverage tooling.
+
+AllValidators:
+  # Lint private and protected objects too: the yard-documentation skill
+  # requires YARD docs on all objects, including Ruby-private methods.
+  YardOptions:
+    - --private
+    - --protected
+
+  Exclude:
+    - 'spec/**/*'
+    - 'vendor/**/*'
+
+  # Fail the run on any offense at convention severity or higher so that tag
+  # ordering, collection style, and other convention-level skill rules gate CI.
+  FailOnSeverity: convention
+
+  # Replaces the retired yardstick coverage threshold (was 75).
+  MinCoverage: 75.0
+
+# --- Overrides where yard-lint defaults conflict with the skill ---------------
+
+# The skill's templates end every doc block with a trailing blank comment line
+# (`#`) before the definition, so the default EmptyCommentLine validator would
+# flag the entire codebase. Disabled to preserve the project's house style.
+Documentation/EmptyCommentLine:
+  Enabled: false
+
+# The skill uses angle-bracket parametrized collection types
+# (e.g. `Array<String>`, `Hash<Symbol, String>`). This validator enforces the
+# `Hash{K => V}` form instead, which conflicts with the documented convention.
+Tags/CollectionType:
+  Enabled: false
+
+# Match the tag order documented in the skill's standard and overload templates.
+# Tags not listed here are left unordered (e.g. `overload`, `abstract`).
+Tags/Order:
+  Enabled: true
+  Severity: convention
+  EnforcedOrder:
+    - example
+    - param
+    - option
+    - return
+    - raise
+    - yield
+    - yieldparam
+    - yieldreturn
+    - note
+    - deprecated
+    - see
+    - api
+
+# --- Opt-in validators that enforce the skill's house style ------------------
+
+# The skill's templates put a blank comment line between the description and the
+# first tag and between every tag, so that the source formatter keeps each tag
+# visually separated. The built-in Tags/TagGroupSeparator can only separate
+# different tag *groups* (it can never split two sibling @param tags), so this
+# project uses Tags/TagSeparator, which requires a blank line between every
+# consecutive tag. @option is exempt so it can cluster directly beneath the
+# @param hash it documents.
+#
+# Tags/TagSeparator is not yet part of a released yard-lint; it is sourced from a
+# fork branch via the Gemfile until it is merged upstream and published.
+Tags/TagSeparator:
+  Enabled: true
+  Severity: convention
+  RequireAfterDescription: true
+  Exempt:
+    - option