git 4.3.2 → 5.0.0.beta.1

data/.github/pull_request_template.md

@@ -13,5 +13,7 @@ Review our [guidelines for contributing](https://github.com/ruby-git/ruby-git/bl
 - [ ] I reviewed and applied the project's [AI Policy](../AI_POLICY.md). I understand
   and verify any AI-assisted changes included in this PR and ensured they meet
   quality, security, and licensing standards.
-- [ ] Tests added/updated as needed and `rake` passes locally.
+- [ ] I ran `bundle exec rake` locally on this branch and it passed (see
+  [Local development setup](../CONTRIBUTING.md#local-development-setup)).
+- [ ] Tests added/updated as needed.
 - [ ] Documentation updated where applicable (README and/or YARD).

data/.github/skills/breaking-change-analysis/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: breaking-change-analysis
+description: "Assesses the impact of API changes before implementation to understand what code would break and plan appropriate migration paths. Use when removing methods, changing interfaces, or planning deprecations."
+---
+
+# Breaking Change Analysis Workflow
+
+Assess the impact of API changes before implementation. Use when removing methods,
+changing method signatures, altering return types/values, changing exception types,
+or modifying default behavior.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Step 1: Identify the Change Scope](#step-1-identify-the-change-scope)
+- [Step 2: Find All Usages](#step-2-find-all-usages)
+- [Step 3: Assess and Document Impact](#step-3-assess-and-document-impact)
+- [Step 4: Plan Migration Path](#step-4-plan-migration-path)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with the specific
+API/method change you are considering. Use this workflow before coding to assess
+impact and plan migration.
+
+## Related skills
+
+- [Review Backward Compatibility](../review-backward-compatibility/SKILL.md) —
+   verify backward compatibility after command migrations
+- [Development Workflow](../development-workflow/SKILL.md) — implement required
+   changes using strict TDD
+
+## Step 1: Identify the Change Scope
+
+1. Determine which classes and methods are affected.
+2. Check API visibility (`@api public` vs `@api private` in YARD docs).
+3. Check if the change affects `Git::Lib` (facade layer used by most callers).
+
+## Step 2: Find All Usages
+
+1. **Internal usages:**
+
+   ```bash
+   grep -rn "method_name" lib/ tests/ spec/
+   ```
+
+2. **External usage (if applicable):**
+
+   ```bash
+   gh search code "Git::Base#method_name language:ruby"
+   ```
+
+## Step 3: Assess and Document Impact
+
+Produce an impact assessment:
+
+```markdown
+## Breaking Change Impact Assessment
+
+### Change Description
+[What is being changed]
+
+### Affected API
+- Class: `Git::SomeClass`
+- Method: `#some_method`
+- Current signature: `def some_method(arg, opts = {})`
+- Proposed signature: `def some_method(arg, force: false)`
+
+### Internal Impact
+- Files affected: X
+- Tests to update: Y
+
+### External Impact
+- Severity: [High/Medium/Low]
+- Migration difficulty: [Easy/Medium/Hard]
+
+### Migration Path
+[How users should update their code]
+```
+
+## Step 4: Plan Migration Path
+
+**Project versioning policy:**
+- Current release line: v4.x (heading to v5.0.0)
+- Breaking changes are batched for major releases (v5.0.0)
+- Use deprecation warnings in the current release line before removal in the next major
+
+**Deprecation approach:**
+
+```ruby
+# @deprecated Use {#new_method} instead. Will be removed in v5.0.
+def old_method(*args)
+  warn "[DEPRECATION] `old_method` is deprecated. Use `new_method` instead."
+  new_method(*args)
+end
+```
+
+**Documentation requirements:**
+- Add `@deprecated` YARD tag with migration guidance
+- Mark commits with `!` for breaking changes and include `BREAKING CHANGE:` footer
+- DO NOT update CHANGELOG.md — it is auto-generated from commit messages

data/.github/skills/ci-cd-troubleshooting/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: ci-cd-troubleshooting
+description: "Diagnoses and fixes CI/CD failures in GitHub Actions workflows. Use when CI is failing on a PR, builds are broken, or tests pass locally but fail in CI."
+---
+
+# CI/CD Troubleshooting Workflow
+
+When asked to diagnose or fix CI/CD failures (e.g., "Why is CI failing on PR #999?",
+"Fix the failing build"), follow this workflow to identify the root cause and
+optionally implement fixes.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [Step 1: Identify the Failure](#step-1-identify-the-failure)
+- [Step 2: Fetch Relevant Logs](#step-2-fetch-relevant-logs)
+- [Step 3: Diagnose Root Cause](#step-3-diagnose-root-cause)
+- [Step 4: Reproduce Locally (if applicable)](#step-4-reproduce-locally-if-applicable)
+- [Step 5: Report Findings or Fix](#step-5-report-findings-or-fix)
+  - [Option A: Diagnostic Report ("Why is CI failing?")](#option-a-diagnostic-report-why-is-ci-failing)
+  - [Option B: Implement Fix ("Fix the failing build")](#option-b-implement-fix-fix-the-failing-build)
+- [Step 6: Verify Fix](#step-6-verify-fix)
+- [Special Troubleshooting Considerations](#special-troubleshooting-considerations)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with a failing PR
+number, branch, or CI run context. Use Option A for diagnosis-only requests and
+Option B when the user explicitly asks for a fix.
+
+## Related skills
+
+- [Test Debugging](../test-debugging/SKILL.md) — deep-dive test failure analysis
+   and flakiness fixes
+- [Development Workflow](../development-workflow/SKILL.md) — full TDD execution
+   when implementing CI fixes
+- [PR Readiness Review](../pr-readiness-review/SKILL.md) — final validation
+   before opening or updating a PR
+
+## Step 1: Identify the Failure
+
+1. **Get CI Status:**
+   - For PRs: `gh pr checks #999`
+   - For branches: `gh run list --branch <branch-name> --limit 5`
+   - Note which jobs passed and which failed
+
+2. **Categorize the Failure Type:**
+   - **Test failures** - Unit tests, integration tests failing
+   - **Linter failures** - Rubocop, YARD documentation issues
+   - **Build failures** - Dependency installation, compilation errors
+   - **Timeout failures** - Jobs exceeding time limits
+   - **Platform-specific failures** - Failing on specific Ruby version or OS
+
+3. **Identify Specific Failing Steps:**
+   - Note the exact job name and step that failed
+   - Record the Ruby version, OS, and other environment details
+
+## Step 2: Fetch Relevant Logs
+
+**CRITICAL: CI logs can be massive (100K+ lines) and exceed token limits.**
+
+1. **Get the Run ID:**
+
+   ```bash
+   gh run list --branch <branch> --limit 1 --json databaseId --jq '.[0].databaseId'
+   ```
+
+2. **Fetch Failed Job Logs Only:**
+
+   ```bash
+   gh run view <run-id> --log-failed
+   ```
+
+   This limits output to only failed jobs, making it manageable.
+
+3. **Extract Key Error Information:**
+
+   - For test failures: Look for stack traces, assertion errors, specific test names
+   - For linter failures: Extract file names, line numbers, and violation types
+   - For build failures: Find dependency errors or missing packages
+   - Use `grep` to filter logs if still too large:
+
+     ```bash
+     gh run view <run-id> --log-failed | grep -A 10 -B 5 "Error\|FAILED\|Failure"
+     ```
+
+4. **Avoid Full Log Downloads:**
+
+   - Do NOT use `--log` without `--log-failed` unless specifically requested
+   - If logs are still too large, focus on the most recent or critical failure
+
+## Step 3: Diagnose Root Cause
+
+Based on the failure type, investigate:
+
+**For Test Failures:**
+
+- Check if the test exists and what it's testing
+- Look for recent changes that might have broken the test
+- Consider environment differences (local vs. CI)
+- Check for flaky tests (intermittent failures)
+
+**For Linter Failures:**
+
+- Run linters locally: `bundle exec rubocop` and `bundle exec rake yard`
+- Identify specific violations from the log
+- Check if violations are in files related to recent changes
+
+**For Build Failures:**
+
+- Check dependency versions in `Gemfile` and `git.gemspec`
+- Look for platform-specific dependency issues
+- Verify Ruby version compatibility
+
+**For Timeout Failures:**
+
+- Identify which test or step is timing out
+- Check for infinite loops or performance regressions
+- Consider if it's a resource limitation in CI environment
+
+## Step 4: Reproduce Locally (if applicable)
+
+**For PR Failures:**
+
+1. Fetch the PR branch:
+
+   ```bash
+   gh pr checkout #999
+   ```
+
+2. Run the failing tests locally:
+
+   ```bash
+   bundle exec bin/test <test-name>
+   ```
+
+3. Run linters:
+
+   ```bash
+   bundle exec rubocop
+   bundle exec rake yard
+   ```
+
+**For Branch Failures:**
+
+1. Checkout the branch.
+2. Run full CI workflow:
+
+   ```bash
+   bundle exec rake default
+   ```
+
+## Step 5: Report Findings or Fix
+
+Determine the appropriate action based on the user's request:
+
+### Option A: Diagnostic Report ("Why is CI failing?")
+
+Present findings to the user:
+
+````markdown
+# CI Failure Diagnosis: <Branch/PR>
+
+**Status:** <X of Y jobs failed>
+
+## Failed Jobs
+1. **<Job Name>** (<Ruby version>, <OS>)
+   - **Step:** <failing step name>
+   - **Failure Type:** <test/linter/build/timeout>
+
+## Root Cause
+<Explanation of what's causing the failure>
+
+## Error Details
+```
+<Relevant error messages and stack traces>
+```
+
+## Recommendations
+- <Specific fix suggestion 1>
+- <Specific fix suggestion 2>
+
+**Would you like me to implement a fix, or do you need more information?**
+````
+
+**STOP here** unless the user asks you to proceed with fixes.
+
+### Option B: Implement Fix ("Fix the failing build")
+
+Proceed based on failure type:
+
+- **Test Failures:** Use the full TDD workflow (Phase 1-3) to fix the failing tests
+- **Linter Failures:** Fix violations directly, commit with appropriate message
+  (e.g., `style: fix rubocop violations in lib/git/base.rb`)
+- **Build Failures:** Update dependencies or configuration as needed
+- **Timeout Failures:** Investigate performance issues, may require user guidance
+
+**For PR Failures on Someone Else's PR:**
+
+- You may not have push access to their branch
+- Present the fix and ask user to either:
+  - Push to the PR branch (if they have access)
+  - Comment on the PR with suggested changes
+  - Create a new PR with fixes
+
+## Step 6: Verify Fix
+
+After implementing fixes:
+
+1. **Run Affected Tests Locally:**
+
+   ```bash
+   bundle exec bin/test <test-name>
+   ```
+
+2. **Run Full CI Suite:**
+
+   ```bash
+   bundle exec rake default
+   ```
+
+3. **Push and Monitor:**
+
+   - Push the fixes
+   - Monitor CI to confirm the fix worked:
+
+     ```bash
+     gh run watch
+     ```
+
+4. **Confirm Resolution:**
+
+   ```text
+   Fix implemented and pushed. Monitoring CI run...
+   CI Status: <link to run>
+   ```
+
+## Special Troubleshooting Considerations
+
+**Platform-Specific Failures:**
+
+- If tests pass on macOS but fail on Linux/Windows, document the difference
+- Check for path separator issues (`/` vs. `\`)
+- Look for encoding differences
+- Consider file system case sensitivity
+
+**Flaky Tests:**
+
+- If a test fails intermittently, note this in your diagnosis
+- Run the test multiple times locally to confirm flakiness
+- Suggest fixes for race conditions or timing issues
+
+**Permission Issues:**
+
+- If you can't push to a PR branch, clearly communicate this limitation
+- Provide the exact commands or changes needed for the user to apply
+
+**Token Limit Management:**
+
+- Always use `--log-failed` to limit output
+- If logs are still too large, use `grep` to extract errors
+- Focus on the first failure if multiple failures exist
+- Consider running tests locally instead of relying on full CI logs