Re: [GSOC] [PROPOSAL v2] Draft of proposal for "Unify ref-filter formats with other pretty formats"

[Christian Couder <christian.couder@gmail.com>]

On Fri, Mar 31, 2023 at 5:22 AM Zhang Yi <18994118902@163.com> wrote:
>
> I have changed my proposal according to the comments by Hariom Verma.
>
> Improvement vs v1:
> 1. Put more effort into related work and grasp a lot from them.
> 2. More details about timeline.
> 3. More details about my plan.
> 4. Some tiny changes in other content.
>
> Open to more guidances. Thanks for suggestions.

Thanks for improving your proposal based on our feedback!

[...]

> Aim to unify the different implementations to format output for different
> commands, we want to transform pretty into ref-filter formatting logic. According
> to the present situation, I need to add more ref-filter atoms to replace
> pretty.

Could you explain a bit more what that means and why you need to do
that? (You might already do that in a different section below, but it
still feels a bit strange to see this last sentence without much
explanation.)

> ** Previous Work
>
>   - `git for-each-ref`, `git branch` and `git tag` formats into the
> ref-filter formats:
>
> done by Karthik Nayak (GSoC 2015)
>
>   -  `git cat-file` formats and the ref-filter formats:
>
> started by Olga Telezhnaya (Outreachy 2017-2018),
> continued by ZheNing Hu (GSoC 2021),
>     There are a lot of patches which are concluded in his final blog [1]
> but still not finished due to tricky performance issues
>
>   - ref-filter formats and pretty formats:
>
> started by Hariom Verma (GSoC 2020)
>     There are also a lot of patches which are concluded in his final blog [2]
> continued a bit by Jaydeep Das (GSoC 2022)
>     Patch: gpg-interface: add function for converting trust level to string [3]
> and continued by Nsengiyumva Wilberforce and his  work on the "signature" atoms
> should be mostly over when the GSoC starts. (Outreachy 2022-2023)

Yeah except Wilberforce has actually been working outside of Outreachy
as he didn't satisfy the requirements for being accepted, but still
wanted to work on this.

>     Patch: ref-filter: add new atom "signature" atom [4]
>
> ps: There seems no conclusion articles of Karthik Nayak's and Olga Telezhnava's
> works.

Karthik's blog posts might have disappeared for some reason. I have
Cc-ed him and he might tell us.

Olga's blog posts seem to still be available on
https://medium.com/@olyatelezhnaya. Medium seems to require signing in
these days though.

> ** What is left
>
> Since the work of "signature" atoms will be finished by Nsengiyumva Wilberforce,
> There may be some other atoms left for ref-filter formats and pretty formats.
> But I still need to check.
>
> If there is no work left for for ref-filter formats and pretty formats, then

s/for for/for/

> there may be another command which has a different format implement with

Maybe: s/implement/implemented/

> ref-filter.

I am not sure what your last sentence here means. If a command already
uses ref-filter formats, then there is no more work to do as that's
the end state we would like.

> ** Steps
>
> In my mind, there are 4 steps logically:
> 1. Check and find a pretty atom which has no substitute in ref-filter.
>    This step is to decide the whole direction of the next work.

So you might want to take a look at this step soon. It might not be
difficult to find out, as the implemented atoms are described in the
docs.

They are called "field names" in the git for-each-ref documentation
(Documentation/git-for-each-ref.txt) and "placeholders" in the pretty
formats documentation (Documentation/pretty-formats.txt).

>    Christian Couder informed me that I can do things like the following:
>    - making sure that all the atoms in the pretty formats have similar
>    atoms implemented in the ref-filter formats
>    - find a way to convert any string containing pretty format atoms to
>    a string containing only ref-filter format atoms
>    - find a way to plug-in the ref-filter code into the pretty code, so
>    that callers of the pretty code would not need to be changed much.

Yeah I suggested these as possible steps to split the work, hoping
that you would dig a bit more what they meant, and how you could
perform them.

> 2. Add reasonable test scripts and maybe documents in advance.
>    In my opinion, making a draft of test scripts and documents in advance can
>    help me have a deep understanding of the behavior that I need to code. I learn
>    this development mode from book. And I have really met problems rising from
>    the misunderstanding of needed behavior which will result in a lot of reworks.

I agree that it's a good approach when developing new features. Here
the features and associated high level tests and documentation already
exist. We "just" want to replace the internal implementation of the
pretty formats using the ref-filter formats. So the approach could be
a bit different.

> 3. Change code.
>    Inspired by Hariom Verma's proposal, I can  start by first looking at what
>    actually needed to be replaced (for example by studying the PRETTY FORMATS
>    section in 'man git-log', what which verbs you can use in the ref-filter
>    ('man git-for-each-ref') to achieve the same thing.

Yeah and this shouldn't take a lot of time. I think Hariom already
wrote a correspondence table between the different "verbs" (also
called "atoms", "placeholders" or "field names") in the pretty and
ref-filter formats.

> Then I can research how
>    one format is implemented in 'pretty.c', and see how a similar thing using
>    the ref-filter is implemented in 'ref-filter.c'.

What will you learn from that and how will it help you for the next steps?

You call this section "Change code" but it looks like it's only about
researching things.

> 4. Recheck documents and run test scripts.
>    Necessary step to check the behavior of code.

We ask for tests and documentation to be part of the patches that are
sent, so writing documentation and tests and running tests should be
part of each coding step.

> * Benefits to Community
>
> I'm willing to stay around after the project. By that time, I will be in my
> second year without classes. And my tutor has an open mind about my request to
> involve in an open source project by now. Considering the subjective and
> objective conditions, I think there is a high possibility that I will stay
> around.
>
> Particularly, I wish to be a co-mentor if I have the ability. There may be some
> difficulties. But what I learn from my finite experience is that you should not
> refuse something positive just because of the difficulties in the mind. A
> fresh new job may be difficult, but it can show me the possibilities of the
> world, which means changing my mind.

Great!

[...]

> * Microproject
>
> t9700: modernize test scripts [5]
>
> The microproject patches have been merged. The merge info is as below:
>
> commit 8760a2b3c63478e8766b7ff45d798bd1be47f52d
> Merge: a2d2b5229e 509d3f5103
> Author: Junio C Hamano <gitster@pobox.com>
> Date:   Tue Feb 28 16:38:47 2023 -0800
>
>     Merge branch 'zy/t9700-style'
>
>     Test style fixes.
>
>     * zy/t9700-style:
>       t9700: modernize test scripts

Thanks for your work on that!

> * Plan

It's difficult to understand how this section is different from the
"Steps" section above. Maybe these two sections could be merged.

> ** Timeline and deliverables
>
> The official GSOC code time start from 05-29 to 08-28, which is 13 weeks.
> The period from 06-05 to 06~30 is near the end of the semester. There are many
> classes for me. So I guess I may be not productive during this period.

Thanks for telling us about this in advance!

> I think it is a bit time-limited if I follow the official timeline. It seems
> necessary to do some work in advance.

[...]

> 2. Write draft of documents and test scripts.
>  Period:
>   05-29 ~ 06-02
>   week 1
>  Tasks:
>   Based on the preparatory work, write drafts of doc and test.
>  Deliverables:
>   Drafts of documents and test scripts

See what I said above about the fact that a big part of this project
might not be about developing new features.

[...]

Best,
Christian.