Subject: Re: [GSoC] Proposal Discussion: git-refs Project

From: shejialuo <[email-masked]>
Date: Fri, 28 Mar 2025 21:45:36 +0800

On Thu, Mar 27, 2025 at 10:26:49AM +0800, Yuting Zheng wrote:
> Thanks for your reply!
> 
> I have reviewed the changelog and noted that Git version 2.23
> introduced similar work through the addition of the git-switch and
> git-restore commands, which replace some legacy commands and incorporate
> various functional modifications.
> 
> After examining the updates, I have summarized the proposed work as
> follows and would appreciate confirmation on whether these tasks are to be
> included in the current project:
> 
> 1. Code Modifications for Command Implementation:
> 
> - Implementation of new commands.
> - Necessary modifications to existing commands to support these changes.

I think "modifications to existing commands" may not be accurate. I
think what we need to do is we should try to reuse the original logic as
much as possible which requires:

1. Understand the behavior of the existing commands.
2. Find good design to expose the common interfaces for the new commands
and existing commands.

> 
> 2. Test Modifications:
> 
> - Addition of tests for the new features (including help tests, basic
> functionality tests, and extended feature tests).
> - Updating tests for old commands to execute tests on the new commands
> (for example, changing the command in git-checkout tests to git-restore).

I don't think that we should update tests for old commands. We want to
keep the original command not broken, right? So, we should use the
original test to exercise your changed code to make sure that everything
is OK.

> 
> 3. Documentation Updates:
> 
> - Creating documentation for the new commands.
> Updating and unifying existing documentation (including git.txt,
> git-cli.txt, and git-commit.txt).
> 
> Additionally, I have a few points that require further discussion:
> 
> 1. Command Migration:
> 
> Upon reviewing the commands slated for replacement (e.g., git-update-ref(1),
> git-for-each-ref(1), git-show-ref(1), git-pack-refs(1), and
> git-symbolic-ref), it seems that migrating their functionality into a
> subcommand of git-refs could be sufficient. Could you please confirm if
> this approach meets our project requirements without introducing
> additional functionality?
> 

>From my own understanding, we just want to use "git-refs(1)" as an entry
point about all operations for refs. So, we don't need to add new
functionality in this project.

> 2. Function Call Integration:
> 
> Regarding migration, is it acceptable to directly invoke the legacy command
> functions by passing parameters from the new command functions?
> 

So, you want to say that could we use a subprocess to just invoke the
legacy command? I don't think we should use subprocess. If we could use
subprocess, should this project be called as a project?

I somehow think that you may first look at "git-pack-refs(1)" or
something like which is not so complicated to think about a solution.
And when writing the proposal, you may need to talk about how many
commands you want to migrate and how do you plan to migrate.

> 3. Test Retention:
> 
> Lastly, should we retain the original tests for the legacy commands, or
> should they be fully replaced with tests for the new implementations?
> 

This is a good question. From my view, we should not change the original
tests. And this would introduce another question, if we add the new test
for the new command, we'd introduce repetition. I cannot give your
answer here because I don't have experience about this.

> I appreciate your guidance and look forward to your feedback on these points.
> 
> Best regards,
> Zheng Yuting

Thanks,
Jialuo