Subject: Re: [GSOC/RFC] GSoC Proposal Draft | Git Beginner

From: Sidhant Sharma <[email-masked]>
Date: Tue, 22 Mar 2016 14:35:13 +0530

On Tuesday 22 March 2016 02:08 PM, Lars Schneider wrote:
> On 21 Mar 2016, at 11:19, Sidhant Sharma <[email-masked]> wrote:
>
>> Hi,
>> I updated the draft with links, ggit usage examples and some changes to the
>> timeline. I placed the links with reference here, but in the Google Doc, they're
>> inline.
>>
>> Thanks and regards,
>> Sidhant Sharma
>>
>> ---
>>
>> Implement a beginner mode for Git.
>>
>> Abstract
>>
>> Git is a very powerful version control system, with an array of features
>> that lend the user with great capabilities. But it often so happens that some
>> beginners are overwhelmed by its complexity and are unable to fully understand
>> and thus, utilize Git. Moreover, often beginners do not fully understand
>> the command they are using and end up making destructive (and occasionally,
>> irreversible) changes to the repository.
>>
>> The beginner mode will assist such  users in using Git by warning them
>> before making possibly destructive changes. It will also display tips and
>> short snippets of documentation for better understanding the Git model.
>>
>> Google summer of code Idea suggested here:
>> http://git.github.io/SoC-2016-Ideas/#git-beginner
>>
>> About Me
>>
>> Name : Sidhant Sharma
>> Email [1] : Sidhant.Sharma1208 <at> gmail.com
>> Email [2] : Tigerkid001 <at>  gmail.com
>> College : Delhi Technological University
>> Studying : Software Engineering
>> IRC : tk001 (or _tk_)
>> Phone : 91-9990-606-081
>> Country : India
>> Interests : Computers, Books, Photography
>> Github : Tigerkid001
>> LinkedIn : https://in.linkedin.com/in/sidhantsharma12
>>
>> Technical Experience
>>
>> Authored several Mozilla Firefox and Google Chrome extensions:
>> Firefox: Owl [1], Blink [2], Spoiler Jedi [3]
>> Chrome: Blink [4]
>>
>> Developed a robust Plugin framework for Android [5] for a startup.
>> Learning Linux kernel programming via the Eudyptula Challenge [6]
>> (currently level 6).
>> Developed natural language processor for sarcasm detection [7] in tweets.
>> Developed hand gesture detection module [8] as a college minor project.
>> Active Firefox Add-ons Editor at AMO [9].
>> Currently working on a restaurant image classification project as second college
>> minor project.
>>
>> Why I chose Git
>>
>> I have been using Git for about two years now, and it has become an
>> indispensable daily-use tool for me. Getting a chance to participate in GSoC
>> for the first time under Git is very exciting. It will give me an opportunity
>> to intimately know the system and a chance to help in making it better and more
>> powerful.
>>
>> Proposal
>>
>> Ideas Page: Git Beginner [10]
>>
>> The following tasks summarize the project:
>>
>> Implement a wrapper around Git
>>
>> A wrapper is to be implemented around (currently called 'ggit'), which will
>> provide the following user interface:
>> `ggit <git-command> <options>`
>> For example, `ggit add --all`
>> The wrapper will assess the arguments passed to it, and if they are detected to
>> be safe, it will simply pass them through to 'git'. This approach is favorable as the existing
>> users of git will not be affected by the wrapper.
>>
>> Warning for potentially destructive commands
>>
>> For every command that is entered, the wrapper will assess the subcommand and
>> its options. In that, it will first check if the subcommand (eg. add,
>> commit, rebase) is present in a list of predefined 'potentially destructive'
>> commands. This can be done by searching through a radix tree for the subcommand.
>> If found, then the arguments to the subcommand will be checked for specific
>> flags. The graylisted flags for the destructive commands will be stored as an
>> array of regular expressions, and the current command's arguments will be
>> checked against them. If matches are found, a warning is displayed. 'ggit'
>> for the warning would be
>> "You are about to do X, which will permanently destroy Y. Are you sure you wish
>> to continue? [Y/n] "
>> If the user enters Y[es], the command will be executed as is (by passing it
>> unaltered to git). In the case of Y[es], 'ggit' will also give tips for undoing
>> the changes made by this command (by referring the user to correct commands and
>> reflog),  if the command can be undone. In case the command cannot be undone,
>> 'ggit' will display an additional line in the warning like
>> "The changes made by this command cannot be undone. Please proceed cautiously".
>> In the case of n[o], 'ggit' will exit without executing the command.
>>
>> Currently, the list consists of commands like:
>>
>> $ git rebase
>> $ git reset --hard
>> $ git clean -f
>> $ git gc --prune=now --aggressive
>> $ git push -f <branch>
>> $ git push remote [+/:]<branch>
>> $ git branch -D
>>
>> The list will be updated after some more discussion on the list.
>>
>> Usage tips and documentation
>>
>> The wrapper will also be responsible for showing a short description of every
>> command that is entered through 'ggit'. This shall be done for every command
>> unconditionally. The description will be derived from the actual documentation,
>> but  will primarily aim to help the beginner understand the Git workflow and the
>> Git model.
>>
>> A few examples to illustrate the working of the wrapper are:
>>
>> $ ggit add --all
>> Staging all changes and untracked files. Use ` [g]git commit` to commit the changes.
>>
>> $ ggit commit -m “Second commit”
>> Committing staged changes…
>> [master 0be3142] Second commit
>> 4 files changed, 6 insertions(+), 2 deletions(-)
>>
>> $ ggit reset HEAD~1 --hard
>> Resetting HEAD to 1 previous commit.
>> [WARNING] You are about to hard reset the current HEAD (master) by 1 commit.
>> This will take you back to commit b16aae3, and discard all changes make thereafter.
>> If you want to reset but also want to retain the changes made since, use --soft instead
>> of --hard.
>> Are you sure you want to continue? [Y/n] y
>> Resetting HEAD to b16aae3…
>> You can undo this action by resetting the HEAD to last commit you were on, which
>> can be seen by running `git reflog`.
> ggit could know the HEAD commit here. Therefore you could suggest 'git reset --hard $HASH_OF_OLD_HEAD'
> in addition (I like the reference to reflog to teach users where to look for this info).
>
Yeah, we can put that along with the reference to reflog so it's easier for users
to undo quickly. Will update the proposal.
>> HEAD is now at b16aae3 First commit
>>
>> $ ggit push --force origin master
>> Pushing changes to origin/master
>> [WARNING] You are about to force push your history to origin/master, which will
>> rewrite the remote history. Please ensure you really want to do so.
> I think the hardest challenge of this project is to find short and easy
> explanations that a newbie with almost no prior Git knowledge understands. 
> We don't want to duplicate the man pages here. I have the impression visual 
> explanations can often be superior.
>
>
> [WARNING] You are about to purge commits from the <URL of origin> master branch. 
>
> State right now:
> 	    o---o---o---A---B  master on <URL of origin>
> 		     \
> 		      X---Y---Z  your master
>
> State if you continue:
> 	    o---o---o---X---Y---Z  master on <URL of origin> and your master
>
> Commit A and B will be gone. If other people have worked on top of A or B then
> they won't be able to merge their changes easily.
I totally agree that visuals would serve the purpose much better. I'll
update the example with the warning message you suggest, and get started
with preparing more such visual descriptions. I'll post them for RFC soon.
> As a bonus we could also check if the force push would actually do harm before
> showing the message (that means if 'git push --force' was necessary at all or
> if 'git push' would have done the same).
That'll be a nice touch. Will keep that in mind.

Thanks and regards,
Sidhant Sharma
>
> Thanks,
> Lars
>
>
>
>> Are you sure you want to continue? [Y/n] n
>> Aborting push to origin/master
>>
>> Timeline
>>
>> Community Bonding Period
>>
>> Week 1 : Discuss the flow of course with the mentor. Discuss adequate data
>> structures and search techniques to be used.
>>
>> Week 2-3 : Discuss over an extensive list of commands that should be classified
>> as destructive. Discuss appropriate short descriptions for commands. Submit sample
>> patches for the same for comments and review.
>>
>> Week 4 : Discuss code structure, tests, optimization for least overhead and
>> other details.
>>
>> Coding Starts
>>
>> Week 1-2 : Submit code for a basic wrapper that will warn for a subset of the
>> potentially destructive command, and continue if the command is safe.
>> and this is stored as per to provide backward compatibility.
>>
>> Week 3-5 : Extend the wrapper to warn for more commands in the list, along with
>> proper instructions for undoing them. Write tests for the commands supported so far.
>>
>> Mid Term Evaluation
>>
>> Week 6-7 : Complete support for all graylisted commands with tests.
>>
>> Week 8-12: Add beginner-friendly documentation snippets to various git commands.
>>
>> Week 13 : Final cleanup, final touches suggested by mentors and community.
>>
>> Pens Down Date
>> Submission of Code to GSOC
>>
>> [1]: https://addons.mozilla.org/en-US/firefox/addon/owl/
>> [2]:  https://addons.mozilla.org/en-US/firefox/addon/blink/
>> [3]: https://addons.mozilla.org/en-US/firefox/addon/spoiler-jedi/
>> [4]: https://chrome.google.com/webstore/detail/blink-new-tab/kakaolkgegapcgdjdmlmcigejblohpkh/
>> [5]: https://github.com/TigerKid001/flubbr
>> [6]: http://eudyptula-challenge.org/
>> [7]: https://github.com/TigerKid001/Perry
>> [8]: https://github.com/TigerKid001/Dex
>> [9]: https://addons.mozilla.org/en-US/firefox/
>> [10]: http://git.github.io/SoC-2016-Ideas/#git-beginner
>>