git 4.3.2 → 5.0.0.beta.1

data/.github/skills/tdd-refactor-step/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: tdd-refactor-step
+description: 'Guides the REFACTOR step of the TDD cycle — identifying code smells, applying safe refactoring techniques, cleaning test code, and verifying with rubocop. Use during RED-GREEN-REFACTOR when deciding what and how to refactor after making a test pass.'
+---
+
+# TDD Refactor Step
+
+Concrete guidance for the REFACTOR step of the RED-GREEN-REFACTOR cycle. Covers
+code smells to look for, safe refactoring techniques, test code cleanup,
+rubocop integration, and verification.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Decision: refactor or skip](#decision-refactor-or-skip)
+- [Code smells checklist](#code-smells-checklist)
+- [Refactoring techniques](#refactoring-techniques)
+- [Test code refactoring](#test-code-refactoring)
+- [Rubocop integration](#rubocop-integration)
+- [Verification](#verification)
+- [Project-specific patterns](#project-specific-patterns)
+- [Boundaries](#boundaries)
+
+## How to use this skill
+
+Invoke this skill during the REFACTOR step of the TDD cycle, after GREEN
+(all tests pass). This skill expands the guidance in the
+[Development Workflow](../development-workflow/SKILL.md) REFACTOR step.
+
+Typical invocation:
+
+```text
+I just got to green. Walk me through the REFACTOR step using
+the TDD Refactor Step skill.
+```
+
+## Related skills
+
+- [Development Workflow](../development-workflow/SKILL.md) — parent TDD workflow;
+  this skill supplements its REFACTOR step
+- [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — test
+  conventions that refactored tests must follow
+- [PR Readiness Review](../pr-readiness-review/SKILL.md) — final quality gate
+  that catches remaining quality issues
+
+## Decision: refactor or skip
+
+Not every GREEN step needs refactoring. Skip when **all** of the following are true:
+
+- No hardcoded values from the GREEN step remain
+- No duplication was introduced between new and existing code
+- No method exceeds ~10 lines
+- No parameter list exceeds 3 positional parameters
+- Rubocop reports no new offenses on changed files
+- Test setup is not duplicated across examples
+
+If any condition is false, proceed with the relevant technique below.
+
+## Code smells checklist
+
+Check the code written or modified in this task for these smells, in priority order:
+
+|  #  | Smell | Threshold | Action |
+| --- | ----- | --------- | ------ |
+| 1 | **Hardcoded values** from GREEN step | Any | Generalize to actual logic |
+| 2 | **Duplication** between new code and existing code | ≥ 3 similar lines | Extract shared method or constant |
+| 3 | **Long method** | > 10 lines (body) | Extract private helper |
+| 4 | **Long parameter list** | > 3 positional params | Convert trailing params to keyword arguments |
+| 5 | **Inconsistent naming** | Deviates from file/module conventions | Rename to match existing patterns |
+| 6 | **Deeply nested conditionals** | > 2 levels | Extract guard clause or helper |
+| 7 | **Feature envy** | Method uses another object's data more than its own | Move method or extract delegator |
+| 8 | **Dead code** | Unreachable branches, unused variables | Remove |
+
+Limit yourself to smells **in files you touched this task**. Broader cleanup belongs
+in a separate task (add it during REPLAN).
+
+## Refactoring techniques
+
+Apply the simplest technique that resolves the smell:
+
+### Extract method
+
+Split a long method into a public method and one or more private helpers. Name
+the helper after **what** it does, not **how**:
+
+```ruby
+# Before
+def call(*, **)
+  bound = args_definition.bind(*, **)
+  objects = Array(bound.objects).map { |o| "#{o}\n" }.join
+  with_stdin(objects) { |r| run_batch(bound, r) }
+end
+
+# After
+def call(*, **)
+  bound = args_definition.bind(*, **)
+  with_stdin(stdin_content(bound)) { |r| run_batch(bound, r) }
+end
+
+private
+
+def stdin_content(bound)
+  Array(bound.objects).map { |o| "#{o}\n" }.join
+end
+```
+
+### Convert positional to keyword arguments
+
+When a method accumulates optional trailing positional parameters:
+
+```ruby
+# Before
+def initialize(args, options, positionals, exec_names = [], flags = [])
+
+# After
+def initialize(args, options, positionals, exec_names: [], flags: [])
+```
+
+Update the single call site at the same time.
+
+### Replace conditional with guard clause
+
+```ruby
+# Before
+def validate(value)
+  if value
+    if value.is_a?(String)
+      process(value)
+    end
+  end
+end
+
+# After
+def validate(value)
+  return unless value
+  return unless value.is_a?(String)
+
+  process(value)
+end
+```
+
+### Introduce constant
+
+When a magic value appears in logic:
+
+```ruby
+# Before
+raise error if version < Git::Version.parse('2.28.0')
+
+# After
+MINIMUM_GIT_VERSION = Git::Version.parse('2.28.0')
+raise error if version < MINIMUM_GIT_VERSION
+```
+
+### Eliminate duplication with shared setup
+
+When two methods share identical preamble or teardown, extract the shared part.
+If the duplication is in tests, see Test Code Refactoring below.
+
+## Test code refactoring
+
+Test code deserves the same refactoring attention as production code:
+
+| Smell | Technique |
+| ----- | --------- |
+| Duplicated `let`/`before` across contexts | Move to nearest shared `describe` or `context` |
+| Long example bodies (> 5 lines of setup) | Extract to `let` declarations or `before` block |
+| Repeated literal values | Extract to `let` or constant at top of file |
+| Identical examples across files | Extract to shared example group (`shared_examples`) |
+| Unclear example descriptions | Rewrite to state expected behavior, not implementation |
+
+Follow the [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md)
+for the resulting test structure.
+
+## Rubocop integration
+
+Run rubocop on changed files after refactoring:
+
+```bash
+bundle exec rubocop $(git diff --name-only HEAD)
+```
+
+Focus on:
+- `Metrics/MethodLength` — methods over the configured limit
+- `Metrics/ParameterLists` — too many parameters
+- `Metrics/AbcSize` — complexity threshold
+- `Style` cops — naming, formatting consistency
+
+Auto-correct safe offenses when appropriate:
+
+```bash
+bundle exec rubocop -a $(git diff --name-only HEAD)
+```
+
+Do not auto-correct `Metrics` cops — those require structural changes (extract
+method, split class), not formatting fixes.
+
+## Verification
+
+After refactoring, confirm:
+
+1. **Tests still pass:** `bundle exec rspec <spec_file>` for the current task's
+   test file(s)
+2. **No new rubocop offenses:** `bundle exec rubocop $(git diff --name-only HEAD)`
+3. **Behavior unchanged:** No new test was added during REFACTOR — if you need
+   a new test, you skipped a RED step
+
+If any test fails after refactoring, the refactoring changed behavior. Revert
+and try a smaller change.
+
+## Project-specific patterns
+
+Patterns specific to this codebase that the REFACTOR step should enforce:
+
+- **Command classes** should not contain parsing logic — if refactoring reveals
+  parsing in a command class, flag it for extraction (separate task)
+- **Arguments DSL** `Bound` metadata uses keyword arguments — if adding new
+  metadata fields, follow the keyword argument pattern
+- **Error classes** inherit from `Git::Error` — ensure new errors follow the
+  hierarchy in `lib/git/errors.rb`
+- **`freeze` constants** — all new constants should be frozen
+  (`CONSTANT = value.freeze`)
+- **Private methods** go below a single `private` keyword, not inline
+  `private def`
+
+## Boundaries
+
+Things the REFACTOR step must **not** do:
+
+- **Add new behavior** — no new features, no new test cases
+- **Change public API** — method signatures visible to users stay the same
+- **Touch unrelated files** — scope to files modified in this task; add broader
+  refactoring to the task list during REPLAN
+- **Optimize prematurely** — clarity over performance unless profiling data exists
+- **Over-abstract** — do not create a helper for something used exactly once

data/.github/skills/test-debugging/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: test-debugging
+description: "Debugs failing or flaky tests and improves test coverage. Use when tests fail consistently, exhibit intermittent behavior, or when adding missing test coverage."
+---
+
+# Test Debugging & Maintenance Workflow
+
+When asked to debug tests or improve test coverage, follow this workflow to identify
+problems, determine root causes, and apply appropriate fixes.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Step 1: Run and Observe the Test](#step-1-run-and-observe-the-test)
+- [Step 2: Investigate Root Cause](#step-2-investigate-root-cause)
+- [Step 3: Report Findings](#step-3-report-findings)
+- [Step 4: Determine Fix Strategy](#step-4-determine-fix-strategy)
+- [Step 5: Verify Test Fix](#step-5-verify-test-fix)
+- [Project-Specific Considerations](#project-specific-considerations)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with the failing
+test file, test name, or flakiness symptom. Stop at Step 3 for diagnosis-only
+requests unless the user asks for implementation.
+
+## Related skills
+
+- [RSpec Unit Testing Standards](../rspec-unit-testing-standards/SKILL.md) — rules
+  governing test isolation, determinism, and order independence (Rules 25–28); consult
+  when flakiness is caused by a test design violation rather than a production bug
+- [Development Workflow](../development-workflow/SKILL.md) — required TDD process
+   when fixes involve production code
+- [CI/CD Troubleshooting](../ci-cd-troubleshooting/SKILL.md) — investigate
+   failures that appear only in CI
+
+## Step 1: Run and Observe the Test
+
+1. **Run the failing test:**
+
+   ```bash
+   # TestUnit (legacy tests in tests/units/)
+   bundle exec bin/test <test_file_name>
+
+   # RSpec unit test
+   bundle exec rspec spec/unit/git/commands/<command>_spec.rb
+
+   # RSpec integration test
+   bundle exec rspec spec/integration/git/commands/<command>_spec.rb
+
+   # Specific test method (TestUnit)
+   bundle exec ruby -I lib:tests tests/units/test_base.rb -n test_method_name
+   ```
+
+2. **For suspected flaky tests, run multiple times:**
+
+   ```bash
+   for i in {1..20}; do
+     echo "Run $i"
+     bundle exec bin/test <test_file> || break
+   done
+   ```
+
+3. **Check test isolation** — run the test alone vs. within the full suite:
+
+   ```bash
+   bundle exec bin/test <test_file>   # alone
+   bundle exec rake default           # full suite
+   ```
+
+## Step 2: Investigate Root Cause
+
+1. **Read the full error** including stack trace. Identify exact failing line and
+   expected vs. actual values.
+
+2. **Check recent changes** with `git log` and `git blame` on the test file and
+   related production code.
+
+3. **For flaky tests**, look for:
+   - Shared state between tests (global/class variables, shared filesystem resources)
+   - Timing dependencies or race conditions
+   - Non-deterministic behavior (time-dependent logic, unordered iteration)
+   - Test execution order dependencies
+
+4. **For environment issues**, check:
+   - Platform differences (paths, line endings, permissions)
+   - Git version differences (use `git --version`)
+   - Ruby version differences
+
+## Step 3: Report Findings
+
+Present diagnostic findings to the user:
+
+```markdown
+# Test Failure Diagnosis: <test_name>
+
+**Failure Type:** [Consistent / Flaky / Coverage Gap]
+**Test File:** <path/to/test_file.rb>
+
+## Error
+<error message and relevant stack trace>
+
+## Root Cause
+<Explanation of why the test is failing>
+
+## Recommended Fix
+<Specific recommendation>
+
+**Would you like me to implement this fix?**
+```
+
+**STOP here** unless the user asks you to proceed with the fix.
+
+## Step 4: Determine Fix Strategy
+
+| Scenario | Strategy | Commit Type |
+| --- | --- | --- |
+| **Production code bug** (test caught a real bug) | Fix production code using the development-workflow TDD process. The failing test is the RED step. | `fix(component): <description>` |
+| **Test needs updating** (intentional API change) | Get user confirmation first. Update test assertions. | `test(component): update test for <change>` |
+| **Flaky test** (non-determinism) | Make test deterministic. Run 20+ times to verify. | `test(component): fix flaky test in <test_name>` |
+| **Missing test coverage** | Add tests using the development-workflow TDD process. | `test(component): add tests for <feature>` |
+| **Test refactoring** | Improve readability/reduce duplication. Keep tests green. | `refactor(test): improve <test_name>` |
+| **Environment/setup issue** | Fix environment, document requirements. No code commit needed. | — |
+
+**CRITICAL:** Get user confirmation before modifying existing tests.
+
+## Step 5: Verify Test Fix
+
+```bash
+# Run the specific test
+bundle exec bin/test <test_file>        # TestUnit
+bundle exec rspec <spec_file>           # RSpec
+
+# For flaky test fixes, run many times
+for i in {1..50}; do
+  echo "Run $i"
+  bundle exec bin/test <test_file> || break
+done
+
+# Run full suite
+bundle exec rake default
+```
+
+## Project-Specific Considerations
+
+**Test frameworks:** This project uses both TestUnit (legacy tests in `tests/units/`)
+and RSpec (new tests in `spec/`). Run both when verifying changes.
+
+**Test helpers:** Use `clone_working_repo`, `create_temp_repo`, `in_temp_dir` from
+test helpers for TestUnit. Use `include_context` shared contexts for RSpec.
+
+**Mocking:** The project uses Mocha for TestUnit mocking and RSpec doubles for RSpec.
+Be careful with stubs — they can mask real issues.
+
+**Test data:** Fixtures are in `tests/files/`. Use test helpers to create temporary
+repos. Clean up in teardown.
+
+**CI vs. local differences:** If tests pass locally but fail in CI, use the
+ci-cd-troubleshooting skill.