Subject: Re: [GSoC] git-refs proposal draft

From: Patrick Steinhardt <[email-masked]>
Date: Wed, 2 Apr 2025 10:02:35 +0200

On Tue, Apr 01, 2025 at 09:37:50PM +0800, Yuting Zheng wrote:
> Hi Patrick,
> 
> Thanks for your feedback! Here are some adjustments based on your
> suggestions:
> 
> > In any case, I don't think the naming and how exactly each of these
> > commands should look and work like needs to be hashed out in this
> > document. It's nice to scope out _what_ we want to achieve and propose
> > how this could look like, but ultimately I think that most of the design
> > should happen during the project itself.
> 
> OK! I may have misunderstood it. I will remove it.
> 
> > This one is something that is up for debate. While I do expect that most
> > of the commands should remain current semantics and options, we could
> > also use this as an opportunity to think whether there are any issues
> > with the current design and improve upon it.
> 
> So, discussing the specific implementation of the command should also
> be included in the proposal, right?

At least the general direction should become clear, yes. The intent is
that we want to double check that the candidate has indeed invested a
bit of time to understand the problem space and what is being asked of
them. So you don't have to provide all the nitty-gritty details of how
exactly you plan on doing the conversion, but provide a bit of an
overview of what the project would entail.

> >> - git-refs exists
> >>   Replaces git-show-ref --exists, providing reference existence checks
> >>   with positive (<ref>) and exclusion-based (--exclude-existing)
> >>   verification.
> >
> > I'm not quite clear what exclusion-based existence checks is. How do you
> > check whether something exists when you exclude it? I don't think that
> > this option is relevant in the context of `git refs exists`.
> 
> Sorry, I made a mistake. I meant to convey that the `--exclude-existing`
> option should be included in `git-refs list` (replacing
> `git-show-ref --exclude-existing`), which then lists refs within a certain
> scope.

No need to be sorry, we all do mistakes.

[snip]
> >> - git-refs update
> >>   Replaces git-update-ref, providing transactional reference updates
> >>   with batch processing (--stdin) and atomic guarantees.
> >> - git-refs delete
> >>   Separates the delete functionality from git-update-ref, ensuring
> >>   explicit handling of reference removals with safety checks and batch
> >>   operations (--stdin).
> >
> > It's up for debate whether we should even have something like `git refs
> > delete`. As you rightfully notice `git refs update` already handles the
> > usecase, so it feels like needless duplication.
> >
> 
> I think maybe separate `update` and `delete` can be more direct. Separating
> these commands can enhance clarity in their usage, although I'm open to
> further discussion if the community prefers a unified command.

`update` will have to support deletions regardless as you won't be able
to do atomic updates of many refs at once if that update would include a
deletion. So let's start with that, and then we can still figure out
whether `delete` would be desirable.

> > You probably underestimate the time to review and land a specific change
> > quite significantly. Landing new features in ~2 weeks is thus not quite
> > realistic and you should allocate a lot more time for each of the
> > specific subcommands.
> >
> > That of course raises the question of how to squeeze all of the
> > subcommands into a single GSoC. And the answer is that you don't: it's
> > perfectly fine to implement only a subset of the new proposed
> > subcommands. I'd rather you spend more time thinking about how to
> > improve upon the status quo for each of the subcommands and thus spend
> > more time on it than trying to do everything in a hurry.
> >
> 
> Thanks for your reminder! I plan to focus on implementing `git-refs list` and
> `git-refs update` first. These will form the foundation of the new design, and
> once stable, I will consider addressing `git-refs resolve` and additional
> commands if time permits.
> 
> So, I need to update my proposal to reduce the number of subcommands so
> that I can complete this project with high quality. I also need to
> further discuss
> the implications of these commands. By reducing the number of subcommands,
> I can dedicate more time to refining each one and ensuring they integrate well
> with the existing system. I will also detail the implications of each command in
> my updated proposal.

Great, thanks!

Patrick