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://USERNAME@gerrit.wikimedia.org: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