git 4.3.2 → 5.0.0.beta.1

data/.github/skills/refactor-command-to-commandlineresult/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: refactor-command-to-commandlineresult
+description: "Migrates a command class that still performs parsing or custom execution logic to return raw Git::CommandLineResult, moving parsing to facade/parser layers. Use during architectural redesign refactoring."
+---
+
+# Refactor Command to CommandLineResult
+
+Migrate a command that still performs parsing or custom execution logic to the
+`Git::Commands::Base` pattern, so command classes return raw
+`Git::CommandLineResult` and parsing moves to facade/parser layers.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Prerequisites](#prerequisites)
+- [Related skills](#related-skills)
+- [Target end state](#target-end-state)
+- [Refactor steps](#refactor-steps)
+- [What to remove from command classes](#what-to-remove-from-command-classes)
+- [What to update in tests](#what-to-update-in-tests)
+- [YARD updates](#yard-updates)
+- [Migration process and internal compatibility](#migration-process-and-internal-compatibility)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context, then invoke it with the command
+class or source file to migrate. Examples:
+
+```text
+Using the Refactor Command to CommandLineResult skill, migrate
+Git::Commands::Stash::Pop to the Base pattern.
+```
+
+```text
+Refactor Command to CommandLineResult: lib/git/commands/branch/delete.rb
+```
+
+The invocation needs the command class name or file path of the command to
+refactor.
+
+## Prerequisites
+
+Before starting, you **MUST** load the following skill(s) in their entirety:
+
+- [YARD Documentation](../yard-documentation/SKILL.md) — authoritative
+  source for YARD formatting rules and writing standards;
+
+## Related skills
+
+- [Command Implementation](../command-implementation/SKILL.md) — 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
+- [Review Backward Compatibility](../review-backward-compatibility/SKILL.md) — preserving `Git::Lib` return-value contracts
+
+## Target end state
+
+```ruby
+class SomeCommand < Git::Commands::Base
+  arguments do
+    ...
+  end
+
+  # optional for non-zero successful exits
+  # rationale comment
+  # allow_exit_status 0..1
+
+  # @!method call(*, **)
+  #
+  #   @overload call(**options)
+  #
+  #     Execute the git ... command.
+  #
+  #     @return [Git::CommandLineResult]
+end
+```
+
+## Refactor steps
+
+1. Move parsing/transforming logic out of command class into caller/facade/parser.
+2. Replace legacy `ARGS` constant + custom `initialize` with `arguments do` +
+   inheritance from `Base`.
+3. Remove custom `#call` body and add `# @!method call(*, **)` YARD directive.
+4. If command requires non-default success exits, add `allow_exit_status` with
+   rationale comment.
+5. Update callers to consume `CommandLineResult` and parse `result.stdout` where
+   needed.
+
+## What to remove from command classes
+
+- parser invocations
+- output transformation logic
+- `literal` entries for policy/output-control flags (e.g. `literal '--no-edit'`,
+  `literal '--verbose'`, `literal '--no-progress'`, `literal '--no-color'`) —
+  command classes are neutral, faithful representations of the git CLI; convert to
+  `flag_option` / `value_option` so the facade can pass the policy value. See
+  "Command-layer neutrality" in CONTRIBUTING.md.
+- manual `raise_on_failure` / manual exit-code checks (unless temporarily needed in
+  an unmigrated class)
+- duplicated bind/execute logic
+
+## What to update in tests
+
+- unit specs should assert CLI args and `CommandLineResult` behavior
+- remove parsed-object assertions from command unit specs
+- move parsing expectations to parser/facade tests
+- include `raise_on_failure: false` in mocked command expectations
+
+## YARD updates
+
+- update `@return` to `Git::CommandLineResult`
+- keep command-specific `@overload` docs nested under `# @!method call(*, **)` directive
+- ensure `@raise` wording reflects allowed range behavior
+- tag short descriptions must not end with punctuation (no trailing period, comma,
+  or colon)
+- multi-paragraph tag descriptions must have a blank comment line (`#`) between the
+  short description and each continuation paragraph
+
+## Migration process and internal compatibility
+
+See [Command Implementation](../command-implementation/SKILL.md) for the canonical phased rollout checklist
+and internal compatibility contract. In summary:
+
+- **always work on a feature branch** — never commit or push directly to `main`;
+  create a branch before starting (`git checkout -b <feature-branch-name>`) and
+  open a pull request when the slice is ready
+- perform refactor in phased slices (pilot/family)
+- keep each slice independently revertible
+- do not mix unrelated behavior changes with refactor-only changes
+- pass slice gates: `bundle exec rspec`, `bundle exec rake test`,
+  `bundle exec rubocop`, `bundle exec rake yard`

data/.github/skills/release-management/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: release-management
+description: "Prepares and publishes new releases of the ruby-git gem including version bumps, changelog updates, tagging, and gem publishing. Use when preparing a release or checking release readiness."
+---
+
+# Release Management Workflow
+
+This workflow describes how releases are managed for the ruby-git gem.
+
+## Contents
+
+- [How to use this skill](#how-to-use-this-skill)
+- [Related skills](#related-skills)
+- [How Releases Work](#how-releases-work)
+- [Developer Responsibilities](#developer-responsibilities)
+- [Checking Release Readiness](#checking-release-readiness)
+- [What NOT to Do](#what-not-to-do)
+- [Useful Commands](#useful-commands)
+
+## How to use this skill
+
+Attach this file to your Copilot Chat context when preparing a release, verifying
+release readiness, or answering questions about versioning and publishing flow.
+
+## Related skills
+
+- [Dependency Management](../dependency-management/SKILL.md) — dependency updates
+   that affect release content and risk
+- [PR Readiness Review](../pr-readiness-review/SKILL.md) — ensure changes are
+   release-ready before merge
+- [Breaking Change Analysis](../breaking-change-analysis/SKILL.md) — evaluate and
+   communicate major-version impact
+
+## How Releases Work
+
+Releases are **fully automated** via
+[release-please](https://github.com/googleapis/release-please) and the
+`.github/workflows/release.yml` workflow:
+
+1. Developers merge PRs with **conventional commit** messages into `main`
+2. release-please automatically opens (and keeps updated) a **release PR** that
+   bumps `lib/git/version.rb` and regenerates `CHANGELOG.md`
+3. When a maintainer merges the release PR, release-please creates a **GitHub
+   release** with a tag
+4. The workflow then **publishes the gem** to RubyGems.org via `rubygems/release-gem`
+
+Key config files:
+
+| File | Purpose |
+| ---- | ------- |
+| `.release-please-config.json` | Release-please settings (release type, changelog sections, versioning strategy) |
+| `.release-please-manifest.json` | Tracks the current released version |
+| `lib/git/version.rb` | Version constant (updated automatically by release-please) |
+| `CHANGELOG.md` | Release history (updated automatically by release-please) |
+
+The versioning strategy is `prerelease` with `beta` as the prerelease type. The
+config also sets `bump-minor-pre-major: true` and `bump-patch-for-minor-pre-major: true`.
+
+## Developer Responsibilities
+
+The only thing developers need to do for releases is **use conventional commit
+messages**. release-please determines the version bump from commit types:
+
+- `fix:` → **patch** bump
+- `feat:` → **minor** bump
+- `feat!:` or `BREAKING CHANGE:` footer → **major** bump
+
+Everything else (version bump, changelog, tag, gem push) is automated. Do **not**
+manually edit `lib/git/version.rb` or `CHANGELOG.md`.
+
+## Checking Release Readiness
+
+Before a maintainer merges a release PR:
+
+1. **Ensure CI passes on `main`:**
+
+   ```bash
+   bundle exec rake default
+   ```
+
+2. **Review unreleased changes since last tag:**
+
+   ```bash
+   git log $(git describe --tags --abbrev=0)..HEAD --oneline
+   ```
+
+3. **Check for open blockers:**
+
+   ```bash
+   gh issue list --label "bug" --state open
+   ```
+
+4. **Review the release PR** — verify the auto-generated changelog and version
+   bump look correct.
+
+## What NOT to Do
+
+- Do **not** manually bump `lib/git/version.rb` — release-please does this
+- Do **not** manually edit `CHANGELOG.md` — it is auto-generated from commits
+- Do **not** manually create tags — release-please creates them on merge
+- Do **not** manually `gem push` — the workflow handles publishing
+- Do **not** force-push or rebase the release PR — release-please manages it
+
+## Useful Commands
+
+```bash
+# View recent tags
+git tag -l --sort=-v:refname | head -10
+
+# List commits since last release
+git log $(git describe --tags --abbrev=0)..HEAD --oneline
+
+# Compare with previous release
+git diff $(git describe --tags --abbrev=0)..HEAD
+
+# Check current version
+ruby -e "require_relative 'lib/git/version'; puts Git::VERSION"
+
+# View release-please config
+cat .release-please-config.json | jq .
+
+# Build gem locally (for testing only)
+bundle exec rake build
+gem install pkg/git-*.gem
+```