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