Git for idiots

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|

Git for idiots

Petr Bena
Hi,

Long time ago when I started learning with git I decided to create a
simple guide (basically I was just taking some notes of what is
needed). I never thought that it could be useful to anyone so I never
announced it anywhere. However I got some feedback to it, so I decided
to inform you too.

The basic idea is to create a TOTALLY SIMPLE guide that git
illiterates like me can understand and thanks to which they would find
out how to do stuff in wikimedia git / gerrit.

Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots

It doesn't contain so much and there are some mistakes / feel free to fix them.

Since wikimedia switched to gerrit from svn I have yet met a tons of
people who had problems adapting to it, so this could eventually help
some.

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Chad
On Wed, May 8, 2013 at 12:34 PM, Petr Bena <[hidden email]> wrote:

> Hi,
>
> Long time ago when I started learning with git I decided to create a
> simple guide (basically I was just taking some notes of what is
> needed). I never thought that it could be useful to anyone so I never
> announced it anywhere. However I got some feedback to it, so I decided
> to inform you too.
>
> The basic idea is to create a TOTALLY SIMPLE guide that git
> illiterates like me can understand and thanks to which they would find
> out how to do stuff in wikimedia git / gerrit.
>
> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots
>
> It doesn't contain so much and there are some mistakes / feel free to fix them.
>
> Since wikimedia switched to gerrit from svn I have yet met a tons of
> people who had problems adapting to it, so this could eventually help
> some.
>

We've got [[Git/Workflow]], [[Git/Tutorial]] and [[Git/Getting
started]] (in decreasing
order of complexity/depth), so I would be hesitant to add yet another
howto page.
Considering this is supposed to be quick-and-easy docs, I'd suggest folding any
unique content into the getting started doc.

-Chad

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Petr Bena
I was using these tutorials in past, and they were pretty complicated
for me to understand git. I don't say it should be considered some
"official" documentation, rather something what desperate people could
use.

Git/Workflow and such are written by people who already understand git
- they don't see what seems complicated to newbies or what is really
hard and makes git evil to new users. I think some far, far simpler
guide like "git for dummies" or whatever similar, could be useful for
many new contributors who have no idea about git.

On Wed, May 8, 2013 at 6:37 PM, Chad <[hidden email]> wrote:

> On Wed, May 8, 2013 at 12:34 PM, Petr Bena <[hidden email]> wrote:
>> Hi,
>>
>> Long time ago when I started learning with git I decided to create a
>> simple guide (basically I was just taking some notes of what is
>> needed). I never thought that it could be useful to anyone so I never
>> announced it anywhere. However I got some feedback to it, so I decided
>> to inform you too.
>>
>> The basic idea is to create a TOTALLY SIMPLE guide that git
>> illiterates like me can understand and thanks to which they would find
>> out how to do stuff in wikimedia git / gerrit.
>>
>> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots
>>
>> It doesn't contain so much and there are some mistakes / feel free to fix them.
>>
>> Since wikimedia switched to gerrit from svn I have yet met a tons of
>> people who had problems adapting to it, so this could eventually help
>> some.
>>
>
> We've got [[Git/Workflow]], [[Git/Tutorial]] and [[Git/Getting
> started]] (in decreasing
> order of complexity/depth), so I would be hesitant to add yet another
> howto page.
> Considering this is supposed to be quick-and-easy docs, I'd suggest folding any
> unique content into the getting started doc.
>
> -Chad
>
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Chad
Well, that was the point of [[Git/Getting started]] because the Workflow
document sucks.

-Chad

On Wed, May 8, 2013 at 12:41 PM, Petr Bena <[hidden email]> wrote:

> I was using these tutorials in past, and they were pretty complicated
> for me to understand git. I don't say it should be considered some
> "official" documentation, rather something what desperate people could
> use.
>
> Git/Workflow and such are written by people who already understand git
> - they don't see what seems complicated to newbies or what is really
> hard and makes git evil to new users. I think some far, far simpler
> guide like "git for dummies" or whatever similar, could be useful for
> many new contributors who have no idea about git.
>
> On Wed, May 8, 2013 at 6:37 PM, Chad <[hidden email]> wrote:
>> On Wed, May 8, 2013 at 12:34 PM, Petr Bena <[hidden email]> wrote:
>>> Hi,
>>>
>>> Long time ago when I started learning with git I decided to create a
>>> simple guide (basically I was just taking some notes of what is
>>> needed). I never thought that it could be useful to anyone so I never
>>> announced it anywhere. However I got some feedback to it, so I decided
>>> to inform you too.
>>>
>>> The basic idea is to create a TOTALLY SIMPLE guide that git
>>> illiterates like me can understand and thanks to which they would find
>>> out how to do stuff in wikimedia git / gerrit.
>>>
>>> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots
>>>
>>> It doesn't contain so much and there are some mistakes / feel free to fix them.
>>>
>>> Since wikimedia switched to gerrit from svn I have yet met a tons of
>>> people who had problems adapting to it, so this could eventually help
>>> some.
>>>
>>
>> We've got [[Git/Workflow]], [[Git/Tutorial]] and [[Git/Getting
>> started]] (in decreasing
>> order of complexity/depth), so I would be hesitant to add yet another
>> howto page.
>> Considering this is supposed to be quick-and-easy docs, I'd suggest folding any
>> unique content into the getting started doc.
>>
>> -Chad
>>
>> _______________________________________________
>> Wikitech-l mailing list
>> [hidden email]
>> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Anthony
I guess the viewpoint and perspective from the more experienced users may
be different. The veterans may start to take some knowledge for granted, as
a given knowledge that they may thing people would already know.

For example, the underlying concept of git commit is something that I now
take for granted. But it's something that I have to really visit and talk
about when I'm teaching a friend to use git.

Perhaps we need contributions from people who have only just learned how to
properly use git, rather than only having veterans write the guide up.
People who still have the learning experience fresh in their minds.

And perhaps we also need contributions from people who routinely teach
their friends about git.


On Thu, May 9, 2013 at 12:54 AM, Chad <[hidden email]> wrote:

> Well, that was the point of [[Git/Getting started]] because the Workflow
> document sucks.
>
> -Chad
>
> On Wed, May 8, 2013 at 12:41 PM, Petr Bena <[hidden email]> wrote:
> > I was using these tutorials in past, and they were pretty complicated
> > for me to understand git. I don't say it should be considered some
> > "official" documentation, rather something what desperate people could
> > use.
> >
> > Git/Workflow and such are written by people who already understand git
> > - they don't see what seems complicated to newbies or what is really
> > hard and makes git evil to new users. I think some far, far simpler
> > guide like "git for dummies" or whatever similar, could be useful for
> > many new contributors who have no idea about git.
> >
> > On Wed, May 8, 2013 at 6:37 PM, Chad <[hidden email]> wrote:
> >> On Wed, May 8, 2013 at 12:34 PM, Petr Bena <[hidden email]> wrote:
> >>> Hi,
> >>>
> >>> Long time ago when I started learning with git I decided to create a
> >>> simple guide (basically I was just taking some notes of what is
> >>> needed). I never thought that it could be useful to anyone so I never
> >>> announced it anywhere. However I got some feedback to it, so I decided
> >>> to inform you too.
> >>>
> >>> The basic idea is to create a TOTALLY SIMPLE guide that git
> >>> illiterates like me can understand and thanks to which they would find
> >>> out how to do stuff in wikimedia git / gerrit.
> >>>
> >>> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots
> >>>
> >>> It doesn't contain so much and there are some mistakes / feel free to
> fix them.
> >>>
> >>> Since wikimedia switched to gerrit from svn I have yet met a tons of
> >>> people who had problems adapting to it, so this could eventually help
> >>> some.
> >>>
> >>
> >> We've got [[Git/Workflow]], [[Git/Tutorial]] and [[Git/Getting
> >> started]] (in decreasing
> >> order of complexity/depth), so I would be hesitant to add yet another
> >> howto page.
> >> Considering this is supposed to be quick-and-easy docs, I'd suggest
> folding any
> >> unique content into the getting started doc.
> >>
> >> -Chad
> >>
> >> _______________________________________________
> >> Wikitech-l mailing list
> >> [hidden email]
> >> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
> >
> > _______________________________________________
> > Wikitech-l mailing list
> > [hidden email]
> > https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Quim Gil-2
In reply to this post by Petr Bena
On 05/08/2013 09:41 AM, Petr Bena wrote:
> I was using these tutorials in past, and they were pretty complicated
> for me to understand git.

Have you checked recently these pages?

http://www.mediawiki.org/wiki/Gerrit/Getting_started

http://www.mediawiki.org/wiki/Gerrit/Tutorial

I'm a git-idiot and they were useful even before we went through the
Git/Gerrit a couple of months ago.

You are encouraged to improve these pages. Thank you! As Chad says we
are not going to push a 3rd reference document.

--
Quim Gil
Technical Contributor Coordinator @ Wikimedia Foundation
http://www.mediawiki.org/wiki/User:Qgil

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Yury Katkov
In reply to this post by Petr Bena
On Wed, May 8, 2013 at 8:34 PM, Petr Bena <[hidden email]> wrote:

> Hi,
>
> Long time ago when I started learning with git I decided to create a
> simple guide (basically I was just taking some notes of what is
> needed). I never thought that it could be useful to anyone so I never
> announced it anywhere. However I got some feedback to it, so I decided
> to inform you too.
>
> The basic idea is to create a TOTALLY SIMPLE guide that git
> illiterates like me can understand and thanks to which they would find
> out how to do stuff in wikimedia git / gerrit.
>
> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots

I love it!

I've written something similar for myself as well: just a bunch of
copy+paste commands for those who use Git once in two months.

>
>
> It doesn't contain so much and there are some mistakes / feel free to fix
> them.
>
> Since wikimedia switched to gerrit from svn I have yet met a tons of
> people who had problems adapting to it, so this could eventually help
> some.
>
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Petr Bena
Biggest disadvantage I see on the official documents is they don't
contain the hypothetical situation when something is wrong, they are
relying on the fact that everything is as it's supposed to be -
perfect. That user has perfectly configured system, that user doesn't
accidentally break repository or get lost in some process and stuck as
they can't continue for whatever reason.

The  guide should count on that and display some alternative commands
or reasons why some error messages are showing up (especially gerrit
is making stuff very hard, sometimes it reject the commit with cryptic
reasons) - or git-review is missing the .gitreview file sometimes and
doesn't work. These newbie guides should count on that.

The expert on git never get in such a situation because they are doing
everything correct. So they naturally can't expect this to happen. I
know I can edit the current documents but I have no idea how to merge
them with document I wrote. We could eventually insert a FAQ into
beginner guide that contain "Why am I getting error X, Y" etc with
explanation why it happens and how to fix it.

On Wed, May 8, 2013 at 7:49 PM, Yury Katkov <[hidden email]> wrote:

> On Wed, May 8, 2013 at 8:34 PM, Petr Bena <[hidden email]> wrote:
>
>> Hi,
>>
>> Long time ago when I started learning with git I decided to create a
>> simple guide (basically I was just taking some notes of what is
>> needed). I never thought that it could be useful to anyone so I never
>> announced it anywhere. However I got some feedback to it, so I decided
>> to inform you too.
>>
>> The basic idea is to create a TOTALLY SIMPLE guide that git
>> illiterates like me can understand and thanks to which they would find
>> out how to do stuff in wikimedia git / gerrit.
>>
>> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots
>
> I love it!
>
> I've written something similar for myself as well: just a bunch of
> copy+paste commands for those who use Git once in two months.
>
>>
>>
>> It doesn't contain so much and there are some mistakes / feel free to fix
>> them.
>>
>> Since wikimedia switched to gerrit from svn I have yet met a tons of
>> people who had problems adapting to it, so this could eventually help
>> some.
>>
>> _______________________________________________
>> Wikitech-l mailing list
>> [hidden email]
>> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Petr Bena
Also note that in my document I have some hints like this:

Sometimes it's needed to use following, should you know why, feel free
to explain it:
git push origin HEAD:refs/publish/master

which I was told to use by someone else, and it works! So I noted it
somewhere in case I would get into same issue again BUT I have no idea
why it works. I just know it works and I don't know why. These things
should be explained by expert, not me. But every notes of beginner in
git or questions would greatly contribute to improve the documents


On Wed, May 8, 2013 at 9:02 PM, Petr Bena <[hidden email]> wrote:

> Biggest disadvantage I see on the official documents is they don't
> contain the hypothetical situation when something is wrong, they are
> relying on the fact that everything is as it's supposed to be -
> perfect. That user has perfectly configured system, that user doesn't
> accidentally break repository or get lost in some process and stuck as
> they can't continue for whatever reason.
>
> The  guide should count on that and display some alternative commands
> or reasons why some error messages are showing up (especially gerrit
> is making stuff very hard, sometimes it reject the commit with cryptic
> reasons) - or git-review is missing the .gitreview file sometimes and
> doesn't work. These newbie guides should count on that.
>
> The expert on git never get in such a situation because they are doing
> everything correct. So they naturally can't expect this to happen. I
> know I can edit the current documents but I have no idea how to merge
> them with document I wrote. We could eventually insert a FAQ into
> beginner guide that contain "Why am I getting error X, Y" etc with
> explanation why it happens and how to fix it.
>
> On Wed, May 8, 2013 at 7:49 PM, Yury Katkov <[hidden email]> wrote:
>> On Wed, May 8, 2013 at 8:34 PM, Petr Bena <[hidden email]> wrote:
>>
>>> Hi,
>>>
>>> Long time ago when I started learning with git I decided to create a
>>> simple guide (basically I was just taking some notes of what is
>>> needed). I never thought that it could be useful to anyone so I never
>>> announced it anywhere. However I got some feedback to it, so I decided
>>> to inform you too.
>>>
>>> The basic idea is to create a TOTALLY SIMPLE guide that git
>>> illiterates like me can understand and thanks to which they would find
>>> out how to do stuff in wikimedia git / gerrit.
>>>
>>> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots
>>
>> I love it!
>>
>> I've written something similar for myself as well: just a bunch of
>> copy+paste commands for those who use Git once in two months.
>>
>>>
>>>
>>> It doesn't contain so much and there are some mistakes / feel free to fix
>>> them.
>>>
>>> Since wikimedia switched to gerrit from svn I have yet met a tons of
>>> people who had problems adapting to it, so this could eventually help
>>> some.
>>>
>>> _______________________________________________
>>> Wikitech-l mailing list
>>> [hidden email]
>>> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>> _______________________________________________
>> Wikitech-l mailing list
>> [hidden email]
>> https://lists.wikimedia.org/mailman/listinfo/wikitech-l

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Chad
On Wed, May 8, 2013 at 3:04 PM, Petr Bena <[hidden email]> wrote:

> Also note that in my document I have some hints like this:
>
> Sometimes it's needed to use following, should you know why, feel free
> to explain it:
> git push origin HEAD:refs/publish/master
>
> which I was told to use by someone else, and it works! So I noted it
> somewhere in case I would get into same issue again BUT I have no idea
> why it works. I just know it works and I don't know why. These things
> should be explained by expert, not me. But every notes of beginner in
> git or questions would greatly contribute to improve the documents
>

That's easy to explain, actually. This is what you're doing every time
you submit stuff to
Gerrit (and what the official Gerrit docs say to do).

`git push origin HEAD:refs/for/master`

So what this is saying is "Push to origin my HEAD commit, with the
destination of
refs/for/master." refs/for/foobar is the magic Gerrit ref for "This
change is FOR the branch
FOOBAR." HEAD doesn't have to be HEAD (it's just a pointer), you could
just as easily
refer to a random tag or sha1 in the same command. For example, let's
say you wanted to
push the change just before HEAD for review (but your HEAD wasn't
ready), you could do:

`git push origin HEAD~1:refs/for/master`

git-review is nothing more than a wrapper around these commands (and a
couple of other
things) since people like less typing :)

Just for comparison, when you're doing a `git push origin master` (a
la Github), you're actually
just typing the shorthand version of `git push origin
refs/heads/master:refs/heads/master.`

-Chad

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

mathieu lovato stumpf guntz
In reply to this post by Petr Bena
Le mercredi 08 mai 2013 à 18:34 +0200, Petr Bena a écrit :

> Hi,
>
> Long time ago when I started learning with git I decided to create a
> simple guide (basically I was just taking some notes of what is
> needed). I never thought that it could be useful to anyone so I never
> announced it anywhere. However I got some feedback to it, so I decided
> to inform you too.
>
> The basic idea is to create a TOTALLY SIMPLE guide that git
> illiterates like me can understand and thanks to which they would find
> out how to do stuff in wikimedia git / gerrit.
>
> Link is here: www.mediawiki.org/wiki/User:Petrb/Git_for_idiots

Interesting idea. Probably you should also put a part "for those who
don't know svn", just like you go with "everything is ok/wrong". I
didn't read the whole thing, so maybe in practice it doen't matter, but
if you want something accessible to total newbies, you shouldn't expect
them to know svn. Also you may have more contributors using {{empty}}
than if you say "I don't know windows, look at this and move along".

Aprart from that, nice job.

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Moriel Schottlender
In reply to this post by Quim Gil-2
Quim Gil <qgil <at> wikimedia.org> writes:

>
> On 05/08/2013 09:41 AM, Petr Bena wrote:
> > I was using these tutorials in past, and they were pretty complicated
> > for me to understand git.
>
> Have you checked recently these pages?
>
> http://www.mediawiki.org/wiki/Gerrit/Getting_started
>
> http://www.mediawiki.org/wiki/Gerrit/Tutorial
>
> I'm a git-idiot and they were useful even before we went through the
> Git/Gerrit a couple of months ago.
>
> You are encouraged to improve these pages. Thank you! As Chad says we
> are not going to push a 3rd reference document.
>

I also had troubles with the existing tutorials, and for me it's even worse,
since I am (shriek!) a Windows user.

I actually started drafting a "Gerrit/Git for Windows Dummies" page with the
solutions I found to be easiest for myself, and some of them are already up
in Petr's page (Yay!)

For example, one of the biggest issues for me was the SSH public key.
Creating a pair isn't a problem (the explanation in the tutorial is from
GitHub, and is fairly straight forward) but finding where to *submit it* was
tricky.

The SSH Key submission appears as an option in two places - the wikitech
site (where we ask for dev account) and the gerrit settings. It's really
confusing. Also, where the tutorial/quickstart said something like
git clone ssh://[hidden email]:29418/mediawiki/core.git
In effect, it means "TOKEN" (the shell token we chose when registering for
development account) and not (as it looks) the username we use to log into
gerrit.

These are small comments and they probably sound silly to people who are
experienced and do this a lot, but for people who aren't so well versed with
Git and Gerrit (or even linux and command-line work) they can get you stuck
for hours.

I know that it's recommended we edit the existing tutorials, but in this
case, I think that it might be a good idea to add another tutorial for
complete newbies.

The "Getting Started" tutorial is more of a reference -- it didn't
completely help me when I started from scratch, but I use it a lot now to
make sure I remember the procedure correctly. (I might add the 'fetch/reset'
reference there in case someone wants to reset their changes from scratch,
which happens to us newbies a lot ;)

The "Advanced Usage" is meant for advanced stuff and if something goes wrong
-- it assumes you already have git going, and that you're on a GNU/Linux
system for the most part.

Adding another page for a complete walkthrough for either windows users
and/or people who aren't versed in git/gerrit can help newbies without
ruining the references that experienced users use right now.

Moriel


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

S Page-3
> I think that it might be a good idea to add another tutorial for
complete newbies.

Note Mediawiki.org doesn't have a "Git tutorial". There are tons of those
on the web.  Thanks to recent work (by Quim and others I think) we have
three fairly rational pages,
https://www.mediawiki.org/wiki/Gerrit/Getting_started
https://www.mediawiki.org/wiki/Gerrit/Tutorial
https://www.mediawiki.org/wiki/Gerrit/Advanced_usage

Improve those. I'm certain more pages won't help.  Git+Gerrit is
fundamentally hard and complicated with lots of steps and commands, so the
tutorial is going to be long with lots of sections. Additional pages
writing down "Stuff I found difficult before and after going through the
tutorial" just add to the confusion.

Petr's document is useful for the dwindling band of people familiar with
svn, and I'm not sure why it mentions git push (I never use it, I use git
review with gerrit).

A big problem with the documents is inconsistent setup.  They don't even
agree whether the remote should be called origin, gerrit, or review,
because the experts who add to them have different opinions.

--
=S Page  software engineer on E3
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Rahul Maliakkal
>Biggest disadvantage I see on the official documents is they don't
>contain the hypothetical situation when something is wrong, they are
>relying on the fact that everything is as it's supposed to be -
>perfect. That user has perfectly configured system, that user doesn't
>accidentally break repository or get lost in some process and stuck as
>they can't continue for whatever reason.

I couldn't resist posting on this thread. I am relatively a new MediaWiki
developer and I started bug fixing 2 months ago during which I had to go
through https://www.mediawiki.org/wiki/Gerrit/Tutorial and many other
references spread over the Internet. The Tutorial assumes that everything
goes smoothly. Although the
https://www.mediawiki.org/wiki/Gerrit/Advanced_usage#Troubleshooting article
does solve few of the problems, there are still many issues to be
highlighted like what should the user do to undo a commit, some information
regarding staging and unstaging would be helpful, commands like "git show
<hash>" to view the changes after a developer commits, use of git log with
the option "-p". These are just a few features that I would love to see and
maybe other new developers too.

Thanks


On Sat, May 11, 2013 at 3:05 AM, S Page <[hidden email]> wrote:

> > I think that it might be a good idea to add another tutorial for
> complete newbies.
>
> Note Mediawiki.org doesn't have a "Git tutorial". There are tons of those
> on the web.  Thanks to recent work (by Quim and others I think) we have
> three fairly rational pages,
> https://www.mediawiki.org/wiki/Gerrit/Getting_started
> https://www.mediawiki.org/wiki/Gerrit/Tutorial
> https://www.mediawiki.org/wiki/Gerrit/Advanced_usage
>
> Improve those. I'm certain more pages won't help.  Git+Gerrit is
> fundamentally hard and complicated with lots of steps and commands, so the
> tutorial is going to be long with lots of sections. Additional pages
> writing down "Stuff I found difficult before and after going through the
> tutorial" just add to the confusion.
>
> Petr's document is useful for the dwindling band of people familiar with
> svn, and I'm not sure why it mentions git push (I never use it, I use git
> review with gerrit).
>
> A big problem with the documents is inconsistent setup.  They don't even
> agree whether the remote should be called origin, gerrit, or review,
> because the experts who add to them have different opinions.
>
> --
> =S Page  software engineer on E3
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Steve Summit
In reply to this post by S Page-3
S Page wrote:
> Note Mediawiki.org doesn't have a "Git tutorial". There are tons of those
> on the web...
>
> Git+Gerrit is fundamentally hard and complicated...

So perhaps there could be a little section somewhere saying
something like:

        Using Git and Gerrit effectively requires understanding
        how they work.  If you're used to "conventional" source
        code repositories like svn, you'll find git to be
        considerably different, in part because it's completely
        distributed, without any central repository which you
        "check files out of", much less that you "check files
        in to".  Instead, with git, you mumble flarg the bjango
        in order to tnark your flittle and svetch it out to the
        rest of the hortlespoon.  For a good explanation of this,
        see http://one.of.the/tons/of/good/tutorials/on/the/web.

(Obviously that's incomplete, but as someone who only understands
conventional repositories that you check files out of and in to,
I don't yet get git at all, myself, either.)

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Marc-Andre
On 05/10/2013 06:12 PM, Steve Summit wrote:
> (Obviously that's incomplete, but as someone who only understands
> conventional repositories that you check files out of and in to,
> I don't yet get git at all, myself, either.)

Despite the snark, this is also my experience.  I've yet to get really
used to git, and regularly run into problems whenever I do something
more complicated than clone-commit-review; and right now my default
solution to "Oy!  I've hosed my repo again" is to clone anew and
cherry-pick stuff back in.

And I'm no newbie, I've been using source control since SCCS and RCS.  :-)

-- Marc


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: Git for idiots

Jiabao Wu
I am new to gerrit for mediawiki. It really took me a long time to
make it work, while there is nothing wrong in the instructions.
Sometimes I solved the problems I encountered by simple methods like
restart, update. I feel less instruction manuals with more detailed
information would help. Also, it would be nice if there is a trouble
shooting page, everyone can add the problem under the corresponding
category in the page.

On Sat, May 11, 2013 at 8:34 AM, Marc A. Pelletier <[hidden email]> wrote:

> On 05/10/2013 06:12 PM, Steve Summit wrote:
>> (Obviously that's incomplete, but as someone who only understands
>> conventional repositories that you check files out of and in to,
>> I don't yet get git at all, myself, either.)
>
> Despite the snark, this is also my experience.  I've yet to get really
> used to git, and regularly run into problems whenever I do something
> more complicated than clone-commit-review; and right now my default
> solution to "Oy!  I've hosed my repo again" is to clone anew and
> cherry-pick stuff back in.
>
> And I'm no newbie, I've been using source control since SCCS and RCS.  :-)
>
> -- Marc
>
>
> _______________________________________________
> Wikitech-l mailing list
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l



--
Cheers,
Jiabao

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l