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.
On Wed, May 8, 2013 at 12:34 PM, Petr Bena benapetr@gmail.com 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
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 innocentkiller@gmail.com wrote:
On Wed, May 8, 2013 at 12:34 PM, Petr Bena benapetr@gmail.com 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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 benapetr@gmail.com 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 innocentkiller@gmail.com wrote:
On Wed, May 8, 2013 at 12:34 PM, Petr Bena benapetr@gmail.com 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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 innocentkiller@gmail.com 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 benapetr@gmail.com 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 innocentkiller@gmail.com wrote:
On Wed, May 8, 2013 at 12:34 PM, Petr Bena benapetr@gmail.com 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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 <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
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.
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 spage@wikimedia.org 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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.)
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
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 marc@uberbox.org 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Wed, May 8, 2013 at 8:34 PM, Petr Bena benapetr@gmail.com 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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 katkov.juriy@gmail.com wrote:
On Wed, May 8, 2013 at 8:34 PM, Petr Bena benapetr@gmail.com 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
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 benapetr@gmail.com 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 katkov.juriy@gmail.com wrote:
On Wed, May 8, 2013 at 8:34 PM, Petr Bena benapetr@gmail.com 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 Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Wed, May 8, 2013 at 3:04 PM, Petr Bena benapetr@gmail.com 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
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@lists.wikimedia.org