Review Backward Compatibility

Review Backward Compatibility

Review Git::Lib methods for backward compatibility after commands are moved to Git::Commands::* classes. This skill guides the process of restoring backward compatibility for a specific set of git commands while maintaining the benefits of the new command infrastructure.

Contents

• How to use this skill
• Related skills
• Objective
• Current Command Architecture Note
• Instructions
  • Branch setup
  • Step 1: Identify Methods Added Since v4.3.0
  • Step 2: Remove New Methods
  • Step 3: Restore Backward-Compatible Implementations
  • Step 4: Add Required Dependencies
  • Step 5: Verify the Changes
• Example: Stash Commands
  • Legacy Methods (v4.3.0)
  • New Methods (removed)
  • Implementation Pattern
• Key Principles
• Validation Checklist
• Usage

How to use this skill

Attach this file to your Copilot Chat context, then invoke it with the git command name(s) to audit. Example:

Remove methods added to Git::Lib since v4.3.0 for the `branch` git command
and ensure the remaining methods are backward compatible.

Replace branch with the specific git command(s) you want to audit (e.g., worktree, tag, merge, reset).

Related skills

• Refactor Command to CommandLineResult — migrating command classes to Base; the counterpart to this skill's Git::Lib facade focus
• Command Implementation — class structure, phased rollout gates, and internal compatibility contracts

Objective

For the specified git command(s), remove methods added to Git::Lib since v4.3.0 and ensure that remaining methods (which existed in v4.3.0) are backward compatible.

Current Command Architecture Note

When auditing modern implementations, assume command classes follow Git::Commands::Base:

• classes use class < Git::Commands::Base with arguments do ... end
• command entrypoint is call(*, **) (inherited from Base)
• exit-status behavior is centralized via allow_exit_status declarations on the class

Because of this, backward-compatibility adaptation should happen in Git::Lib methods (facade/adapter layer), not by reintroducing legacy execution logic inside command classes.

Instructions

Branch setup

All work must be done on a feature branch. Never commit or push directly to main.

Before starting, create a new branch:

git checkout -b <feature-branch-name>

All commits in this workflow go on the feature branch. When work is complete, open a pull request — do not merge or push directly into main.

Step 1: Identify Methods Added Since v4.3.0

1. Check out the v4.3.0 tag to examine the historical state:

   Warning: git checkout modifies the working tree. Stash or commit any uncommitted changes first (git stash).

   git checkout v4.3.0

2. Search lib/git/lib.rb for all methods related to the specified git command(s):

   grep -n "def <command_name>" lib/git/lib.rb

3. Document each method found, including:

   • Method name and signature
   • Return value type (String, Array, Hash, Boolean, etc.)
   • Exact return value format (e.g., Array<[Integer, String]>, String with specific content)

4. Return to your feature branch:

   git checkout -

5. Search for the same command methods in the current version:

   grep -n "def <command_name>" lib/git/lib.rb

6. Create two lists:

   • Legacy methods: Methods that existed in v4.3.0 (must be preserved and made compatible)
   • New methods: Methods that don't exist in v4.3.0 (should be removed)

Step 2: Remove New Methods

1. Identify all new methods that were added after v4.3.0
2. Remove these methods entirely from lib/git/lib.rb
3. Remove any require statements that are only used by the removed methods

Step 3: Restore Backward-Compatible Implementations

For each legacy method that needs to be preserved:

1. Use modern command infrastructure internally:

   • Call the appropriate Git::Commands::<Command>::* class
   • Ensure all necessary command classes are required at the top of the file

2. Convert return values to match v4.3.0 exactly:

   • Compare the return type from the modern command with the v4.3.0 return type
   • If they differ, add conversion logic to transform the result
   • Modern commands typically return CommandLineResult objects with .stdout, .stderr, and .status
   • Legacy methods may have returned raw strings, arrays, or other types

3. Create helper methods if needed:

   • For complex conversions (e.g., parsing output into specific formats), create private helper methods
   • Name helpers clearly (e.g., <command>_info_to_legacy)
   • Place helpers near the bottom of the file in the private section