[RFC] [GSoC] Draft of Proposal for GSoC

[RFC] [GSoC] Draft of Proposal for GSoC

[Brian Bourn]

Hi all,

This is a first draft of my Proposal for GSoC, I'd love feedback about
what I might be missing and any other files I should read regarding
this, so far I have read most of tag.c, branch.c,
builtin/for-each-ref.c, parse-options.c. once again I hope I can get
the same amount of helpful feedback as when I submitted my
Microproject.

My name is Brian Bourn, I'm currently a computer engineering student
at Columbia university in the city of New York.  I've used git since
my freshman year however this past week has been my first time
attempting to contribute to the project, and I loved it. I'd
particularly like to tackle Unifying git branch -l, git tag -l, and
git for-each-ref.  This functionality seems like an important update
to me as it will simplify usage of git throughout three different
commands, a noble pursuit which is not contained in any other project.

Going through the annals of the listserve thus far I've found a few
discussions which provide some insight towards this process as well as
some experimental patches that never seem to have made it
through[1][2][3][4]

I would start by beginning a deprecation plan for git branch -l very
similar to the one Junio presents in [5], moving -create-reflog to -g,

Following this I would begin the real work of the project which would
involve moving the following flag operations into a standard library
say 'list-options.h'

--contains [6]
--merged [7]
--no-merged[8]
--format
This Library would build these options for later interpretation by parse_options

Next I would implement these flags in the three files so that they are
uniform and the same formatting and list capabilities can be used on
all three. The formatting option will be especially useful for branch
and tag as it will allow users to better understand what is in each
ref that they grab.

For the most part I haven't finalized my weekly schedule but a basic
breakdown would be

Start-Midterm
Begin deprecation of -l
Spend some time reading *.c files even deeper
Build Library(dedicate Minimum one week per function moved)

Midterm-finish
Implement the list flags
Implement the format flags
(if time is left over, add some formatting)

Additionally I am thinking about adding some more formatting tools
such as numbering outputs. What do you all think of this?


[1]http://git.661346.n2.nabble.com/More-formatting-with-git-tag-l-tt6739049.html

[2]http://git.661346.n2.nabble.com/RFC-branch-list-branches-by-single-remote-tt6645679.html#a6725483

[3]http://git.661346.n2.nabble.com/RFC-PATCH-tag-make-list-exclude-lt-pattern-gt-tt7270451.html#a7338712

 [4]http://git.661346.n2.nabble.com/RFC-branch-list-branches-by-single-remote-tt6645679.html#a6728878

[5]http://git.661346.n2.nabble.com/RFC-PATCH-0-2-RFC-POC-patterns-for-branch-list-tt6309233.html

[6]https://github.com/git/git/blob/master/builtin/branch.c#L817

[7] https://github.com/git/git/blob/master/builtin/branch.c#L849

[8] https://github.com/git/git/blob/master/builtin/branch.c#L843

Regards,
Brian Bourn

Re: [RFC] [GSoC] Draft of Proposal for GSoC

[Brian Bourn]

Hello again,

Please it would be very helpful for me to get some comments on this
proposal I would be very grateful towards anyone who could take some
time to look at it, even if it's just the wording.
Regards,
Brian Bourn


On Thu, Mar 20, 2014 at 2:15 PM, Brian Bourn <ba.bourn@gmail.com> wrote:
> Hi all,
>
> This is a first draft of my Proposal for GSoC, I'd love feedback about
> what I might be missing and any other files I should read regarding
> this, so far I have read most of tag.c, branch.c,
> builtin/for-each-ref.c, parse-options.c. once again I hope I can get
> the same amount of helpful feedback as when I submitted my
> Microproject.
>
> My name is Brian Bourn, I'm currently a computer engineering student
> at Columbia university in the city of New York.  I've used git since
> my freshman year however this past week has been my first time
> attempting to contribute to the project, and I loved it. I'd
> particularly like to tackle Unifying git branch -l, git tag -l, and
> git for-each-ref.  This functionality seems like an important update
> to me as it will simplify usage of git throughout three different
> commands, a noble pursuit which is not contained in any other project.
>
> Going through the annals of the listserve thus far I've found a few
> discussions which provide some insight towards this process as well as
> some experimental patches that never seem to have made it
> through[1][2][3][4]
>
> I would start by beginning a deprecation plan for git branch -l very
> similar to the one Junio presents in [5], moving -create-reflog to -g,
>
> Following this I would begin the real work of the project which would
> involve moving the following flag operations into a standard library
> say 'list-options.h'
>
> --contains [6]
> --merged [7]
> --no-merged[8]
> --format
> This Library would build these options for later interpretation by parse_options
>
> Next I would implement these flags in the three files so that they are
> uniform and the same formatting and list capabilities can be used on
> all three. The formatting option will be especially useful for branch
> and tag as it will allow users to better understand what is in each
> ref that they grab.
>
> For the most part I haven't finalized my weekly schedule but a basic
> breakdown would be
>
> Start-Midterm
> Begin deprecation of -l
> Spend some time reading *.c files even deeper
> Build Library(dedicate Minimum one week per function moved)
>
> Midterm-finish
> Implement the list flags
> Implement the format flags
> (if time is left over, add some formatting)
>
> Additionally I am thinking about adding some more formatting tools
> such as numbering outputs. What do you all think of this?
>
>
> [1]http://git.661346.n2.nabble.com/More-formatting-with-git-tag-l-tt6739049.html
>
> [2]http://git.661346.n2.nabble.com/RFC-branch-list-branches-by-single-remote-tt6645679.html#a6725483
>
> [3]http://git.661346.n2.nabble.com/RFC-PATCH-tag-make-list-exclude-lt-pattern-gt-tt7270451.html#a7338712
>
>  [4]http://git.661346.n2.nabble.com/RFC-branch-list-branches-by-single-remote-tt6645679.html#a6728878
>
> [5]http://git.661346.n2.nabble.com/RFC-PATCH-0-2-RFC-POC-patterns-for-branch-list-tt6309233.html
>
> [6]https://github.com/git/git/blob/master/builtin/branch.c#L817
>
> [7] https://github.com/git/git/blob/master/builtin/branch.c#L849
>
> [8] https://github.com/git/git/blob/master/builtin/branch.c#L843
>
> Regards,
> Brian Bourn

Re: [RFC] [GSoC] Draft of Proposal for GSoC

[Jeff King]

On Thu, Mar 20, 2014 at 02:15:29PM -0400, Brian Bourn wrote:

> Going through the annals of the listserve thus far I've found a few
> discussions which provide some insight towards this process as well as
> some experimental patches that never seem to have made it
> through[1][2][3][4]

Reading the past work in this area is a good way to get familiar with
it. It looks like most of the features discussed in the threads you link
have been implemented. The one exception seems to be negative patterns.
I think that would be a good feature to build on top of the unified
implementation, once all three commands are using it.

> I would start by beginning a deprecation plan for git branch -l very
> similar to the one Junio presents in [5], moving -create-reflog to -g,

That makes sense. I hadn't really considered "-l" as another point of
inconsistency between the commands, but it definitely is.

> Following this I would begin the real work of the project which would
> involve moving the following flag operations into a standard library
> say 'list-options.h'
> 
> --contains [6]
> --merged [7]
> --no-merged[8]
> --format
> This Library would build these options for later interpretation by parse_options

Can you sketch out what the API would look like for this unified
library? What calls would the 3 programs need to make into it?

> For the most part I haven't finalized my weekly schedule but a basic
> breakdown would be

Can you go into more detail here? Remember that writing code is only one
part of the project. You'll need to be submitting your work, getting
review and feedback, and iterating on it.

One problem that students have is queuing up a large amount of work to
send to the list. Then they twiddle their thumbs waiting for review to
come back (which takes a long time, because they just dumped a large
body of work on the reviewers). If you want to make effective use of
your time, it helps to try to break tasks down into smaller chunks, and
think about the dependencies between the chunks. When one chunk is in
review, you can be designing and coding on another.

> Additionally I am thinking about adding some more formatting tools
> such as numbering outputs. What do you all think of this?

Something like numbering might make sense as part of the formatting code
(e.g., a new placeholder that expands to "n" for the nth line of
output). I think that would be fairly straightforward, but again, it
makes sense to me to unify the implementations first, and then we can
build new features on top.

-Peff

Re: [RFC] [GSoC] Draft of Proposal for GSoC

[Brian Bourn]

Parts of v2, once again, i'd love some more comments on what I've
rewritten


On Fri, Mar 21, 2014 at 1:42 AM, Jeff King <peff@peff.net> wrote:
> On Thu, Mar 20, 2014 at 02:15:29PM -0400, Brian Bourn wrote:
>
>> Going through the annals of the listserve thus far I've found a few
>> discussions which provide some insight towards this process as well as
>> some experimental patches that never seem to have made it
>> through[1][2][3][4]
>
> Reading the past work in this area is a good way to get familiar with
> it. It looks like most of the features discussed in the threads you link
> have been implemented. The one exception seems to be negative patterns.
> I think that would be a good feature to build on top of the unified
> implementation, once all three commands are using it.
>
>> I would start by beginning a deprecation plan for git branch -l very
>> similar to the one Junio presents in [5], moving -create-reflog to -g,
>
> That makes sense. I hadn't really considered "-l" as another point of
> inconsistency between the commands, but it definitely is.
>
>> Following this I would begin the real work of the project which would
>> involve moving the following flag operations into a standard library
>> say 'list-options.h'
>>
>> --contains [6]
>> --merged [7]
>> --no-merged[8]
>> --format
>> This Library would build these options for later interpretation by parse_options
> Can you sketch out what the API would look like for this unified
> library? What calls would the 3 programs need to make into it?
>

Something like this?

Sample api calls
Add_Opt_Group()
Parse_with_contains()
Parse_with_merged()
Parse_with_no_merged()
Parse_with_formatting()
(each of the 4 calls above may have internal calls within the library
in order to parse the option for each of the different function which
may call these functions)


>> For the most part I haven't finalized my weekly schedule but a basic
>> breakdown would be
>
> Can you go into more detail here? Remember that writing code is only one
> part of the project. You'll need to be submitting your work, getting
> review and feedback, and iterating on it.
>
> One problem that students have is queuing up a large amount of work to
> send to the list. Then they twiddle their thumbs waiting for review to
> come back (which takes a long time, because they just dumped a large
> body of work on the reviewers). If you want to make effective use of
> your time, it helps to try to break tasks down into smaller chunks, and
> think about the dependencies between the chunks. When one chunk is in
> review, you can be designing and coding on another.

This one I can absolutely understand, I tried to break this part down into very
managable parts and give myself a little time at the end of each coding period
to clean up each previous section.  this slop time also allows for me
to hopefully
add some of the extra features that have been thought of. I'm thinking something
like this makes it a little better,

Weekly Schedule

Start-Midterm
Week 1- Begin deprecation of -l in git branch/establish exactly how
long each stage of the deprecation should take.  Spend some time
reading *.c files even deeper while getting to know any current
patches occurring in any area near my work files.  Lastly, this week
will be spent going through the Mailing-list finding previous work
done in this area and any other experimental patches
Week 2- Move Opt_Group callbacks for the functions  into Library
Week 3-Make a Contains Function in the library which will work for all
three functions
Week 4-Add Merge function in library
Week 5-Add a No Merge function in library
Weeks 7-8 spend time polishing the library and cleaning up the patches
for final submission of library to the project

Deliverables for midterm- Library finished pending polish and
acceptance into the git repository

Midterm

Week 9- refactor all files to use the contains flag from the file.
Week 10- use Merge from library in all relevant files
Week 11-use no-merge from library in all relevant files
Week 11-12- implement the format flags in all relevant files (this
will be slightly harder as I think this might involve calling
for-each-ref in the code for tag and branch. Ultimately there is a
chance that part of the code for doing for-each-ref will end up in
this library as well), additionally add in the code for formatting the
relevant opt_Groups into the necessary files.
Week 13-14 Polish patches via mailing-list and clean up all the
refactoring of the files that has occurred.(optionally, add more
formatting changes such as negative patterns and numbering each output
into the library).

Deliverables for Final- working library hopefully added into the code,
and all of the relevant patches for using the library mostly polished
and, minimally, pending peer review for submission into the code base.

I do wonder if this plan might be a little on the conservative side,
if anything, I think
this could take a slightly shorter time than planned, but In that case
I can always
work on other additions to format.


>
>> Additionally I am thinking about adding some more formatting tools
>> such as numbering outputs. What do you all think of this?
>
> Something like numbering might make sense as part of the formatting code
> (e.g., a new placeholder that expands to "n" for the nth line of
> output). I think that would be fairly straightforward, but again, it
> makes sense to me to unify the implementations first, and then we can
> build new features on top.
>
> -Peff

Re: [RFC] [GSoC] Draft of Proposal for GSoC

[Junio C Hamano]

Brian Bourn <ba.bourn@gmail.com> writes:

> Something like this?
>
> Sample api calls
> Add_Opt_Group()
> Parse_with_contains()
> Parse_with_merged()
> Parse_with_no_merged()
> Parse_with_formatting()
> (each of the 4 calls above may have internal calls within the library
> in order to parse the option for each of the different function which
> may call these functions)

This list is a bit too sketchy to be called "sample api calls", at
least to me.  Can you elaborate a bit more?

What do they do, what does the caller expect to see (do they get
something as return values?  do they expect some side effects?)?

Re: [RFC] [GSoC] Draft of Proposal for GSoC

[Brian Bourn]

On Fri, Mar 21, 2014 at 1:45 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Brian Bourn <ba.bourn@gmail.com> writes:
>
>> Something like this?
>>
>> Sample api calls
>> Add_Opt_Group()
>> Parse_with_contains()
>> Parse_with_merged()
>> Parse_with_no_merged()
>> Parse_with_formatting()
>> (each of the 4 calls above may have internal calls within the library
>> in order to parse the option for each of the different function which
>> may call these functions)
>
> This list is a bit too sketchy to be called "sample api calls", at
> least to me.  Can you elaborate a bit more?
>
> What do they do, what does the caller expect to see (do they get
> something as return values?  do they expect some side effects?)?

so something like this would be better I'm assuming?

Some basic sample API calls are found below, each of these would hold
code to complete parsing and/or formatting the flags.
Add_Opt_Group() - returns an OPT_CALLBACK with contains, merged,
no-merged, or formatting which can be used in a commands options list.

Execute_list()-the main call into the library and would pass into the
library all of the necessary flags and arguments for parsing the
request and executing it. This would accept the flags like
-contain, with arguments such as the commit or pattern that is being
searched for.

The next four commands would be called by execute_list() to execute
the original command with respect to the flags that are passed into
this library.
Parse_with_contains()
Parse_with_merged()
Parse_with_no_merged()
Parse_with_formatting()

Re: [RFC] [GSoC] Draft of Proposal for GSoC

[Jeff King]

On Fri, Mar 21, 2014 at 02:03:41PM -0400, Brian Bourn wrote:

> > What do they do, what does the caller expect to see (do they get
> > something as return values?  do they expect some side effects?)?
> 
> so something like this would be better I'm assuming?
> 
> Some basic sample API calls are found below, each of these would hold
> code to complete parsing and/or formatting the flags.
> Add_Opt_Group() - returns an OPT_CALLBACK with contains, merged,
> no-merged, or formatting which can be used in a commands options list.
> 
> Execute_list()-the main call into the library and would pass into the
> library all of the necessary flags and arguments for parsing the
> request and executing it. This would accept the flags like
> -contain, with arguments such as the commit or pattern that is being
> searched for.
> 
> The next four commands would be called by execute_list() to execute
> the original command with respect to the flags that are passed into
> this library.
> Parse_with_contains()
> Parse_with_merged()
> Parse_with_no_merged()
> Parse_with_formatting()

Think about how the callers would use them. Will git-branch just call
Parse_with_contains? If so, where would that call go? What arguments
would it take, and what would it do?

I don't think those calls are enough. We probably need:

  1. Some structure to represent a "list of refs" and store its
     intermediate state.

  2. Some mechanism for telling that structure about the various
     filters, sorters, and formatters we want to use (and this needs to
     be hooked into the option-parsing somehow).

  3. Some mechanism for getting the listed refs out of that structure,
     formatting them, etc.

-Peff

Re: [RFC] [GSoC] Draft of Proposal for GSoC

[Brian Bourn]

On Fri, Mar 21, 2014 at 2:07 PM, Jeff King <peff@peff.net> wrote:
> On Fri, Mar 21, 2014 at 02:03:41PM -0400, Brian Bourn wrote:
>
>> > What do they do, what does the caller expect to see (do they get
>> > something as return values?  do they expect some side effects?)?
>>
>> so something like this would be better I'm assuming?
>>
>> Some basic sample API calls are found below, each of these would hold
>> code to complete parsing and/or formatting the flags.
>> Add_Opt_Group() - returns an OPT_CALLBACK with contains, merged,
>> no-merged, or formatting which can be used in a commands options list.
>>
>> Execute_list()-the main call into the library and would pass into the
>> library all of the necessary flags and arguments for parsing the
>> request and executing it. This would accept the flags like
>> -contain, with arguments such as the commit or pattern that is being
>> searched for.
>>
>> The next four commands would be called by execute_list() to execute
>> the original command with respect to the flags that are passed into
>> this library.
>> Parse_with_contains()
>> Parse_with_merged()
>> Parse_with_no_merged()
>> Parse_with_formatting()
>
> Think about how the callers would use them. Will git-branch just call
> Parse_with_contains? If so, where would that call go? What arguments
> would it take, and what would it do?
>
> I don't think those calls are enough. We probably need:
>
>   1. Some structure to represent a "list of refs" and store its
>      intermediate state.
>
>   2. Some mechanism for telling that structure about the various
>      filters, sorters, and formatters we want to use (and this needs to
>      be hooked into the option-parsing somehow).
>
>   3. Some mechanism for getting the listed refs out of that structure,
>      formatting them, etc.

keeping some of my function calls to do the actual work I think I
settled on this

A possible API is given below, each of these would hold code to
complete parsing and/or formatting the flags.

There will be a struct in the library called refs_list() which when
initialized will iterate through all the refs in a repository and add
them to this list.

 there would be a function which would retrieve ref structs from that function.

Get_ref_from_list()- which would return a single ref from the list.

Add_Opt_Group() - returns an OPT_CALLBACK with contains, merged,
no-merged, or formatting which can be used in a commands options list.

Execute_list()-the main call into the library and would pass into the
library all of the necessary flags and arguments for parsing the
request and executing it. This would accept the flags like contain,
with arguments such as the commit or pattern that is being searched
for. This will then parse the refs_list using the four commands below
to make, sort, filter, and format an output list which will then be
printed or returned by this function.

Any Call into the API from an outside source would call one of the
previous two functions, all other commands in the API would be for
internal use only, in order to simplify the process of calling into
this library.

The next four commands would be called by execute_list() to further
format the refs_list with respect to the flags that are passed into
this library. These would also take the additional arguments from
execute_list() such as patterns to parse or which commit to filter
out. these calls would modify the refs_list for eventual printing.

Parse_list _with_contains()

Parse_list_with_merged()

Parse_list_with_no_merged()

Format_list()

of course this would still depend on deciding whether or not we want
to return to the original command to print or if printing can be
handled by the library itself.


> -Peff