Talk:Gerrit/Tutorial/LQT Archive 1

Welcome to the Git Tutorial document!
Please offer your feedback, to help us improve both the tutorial and this document! The outline, as it stands today, may change a little. But, it is most of what the tutorial will cover in Berlin. Keep in mind that this document is a work-in-progress and will mature along with the Git/Gerrit implementation.

Collaboration section
I know one of the main complaints of Git/Workflow is that it's entirely too long and covers stuff well beyond the basic use case. Looking at the Collaboration section, I'm thinking we might be in danger of repeating ourselves. Specifically, I'm not sure if Project Ownership or 20% time are good topics to cover here. ^demon (talk) 15:57, 20 May 2012 (UTC)


 * Good points. Thanks,^demon. What do the rest of you think? Should we skinny down Workflow for the tutorial? I'll remove the 20% time topic. Danielle Benoit (talk) 19:46, 21 May 2012 (UTC)

Essential topics for a 1-hour tutorial
Here's my proposal for essential topics for a 1-hour tutorial: I already did this one with a single programmer and it took about forty minutes. With a group it will probably take more. --Amir E. Aharoni (talk) 17:46, 25 May 2012 (UTC)
 * What is version control? :A way to store every version of every source code file, so that there would be a way to read every previous version and to see what changes were made and by whom and to manage releases. Comparable to versions of Wikipedia articles, but more complex - with branches, merges and other fun stuff.
 * What is Git? :A distributed version control system. Distributed means that technically there is no central repository ("repo"), that every repository is independent, and everybody can pull changes from everybody else. In practice, the Wikimedia repository is the repository used for releases.
 * What is Gerrit? :A web-based system for checking every change to the central repository. It's possible to see the diff, to pull the change for testing at your own repo, to comment on the whole change and on separate lines, to upload an amended version of the change, and to merge it to the master repo. Practically everybody can send a change for review in Gerrit, but only some people have the permission to write to the master repo.
 * How to install Git :Linux, Mac, Windows.
 * How to install git review.
 * How to create and upload SSH keys. :It's important and frequently neglected, because everybody does it ones and forgets it.
 * How to clone the core repo.
 * How to clone extensions.
 * How to pull updates.
 * How to submit a change: Create a branch, edit files, commit (once per branch!), check your commit (git diff --cached, git show HEAD), git review.
 * How to amend a change: mention rebase, fetch. Briefly mention the other stuff that everybody hates :)
 * How to review.

Thoughts from the runthrough
Patrick will be giving the intro in his own words, despite the prose that is on the tutorial for use by future readers.

We'll need to revise the instructions to reflect the use of the test or example repo rather than the core mediawiki repo.

We won't deal with multiple remotes in the tutorial syllabus, but we'll take questions about it during Q&A.

Question re git diff, git diff cache - clarification needed?

"To prepare submitting a file" - clarify wording. Clarify "git add" & discourage people from using -a because you might commit stuff you didn't mean to. "Git add" stages a file and is different from "git commit -a".

This is weirdly time-travel-y:
 * Before your changes can be merged into master, they must undergo review in Gerrit.


 * But first, it's a good idea to synchronize your change set with any changes that may have occurred in master while you've been working. From within the branch you've been working on, excute the following command:

Explain better difference between "git pull origin master" and "git pull --rebase origin master" per Ryan's thoughts.
 * I changed "git pull --rebase origin master" to just "git pull origin master" in the initial example since rebasing here isn't necessary. Kaldari (talk) 00:16, 26 May 2012 (UTC)

Should we stress that people should work on one change at a time, pull from master often, and push them as they work! (until they are more comfortable switching between branches). Lots of problems are caused by Git-review & wrong branch.

Sumana Harihareswara, Wikimedia Foundation Engineering Community Manager (talk) 23:55, 25 May 2012 (UTC)

I think we need to explain what "git rebase master" does the first time it is mentioned. Kaldari (talk) 00:14, 26 May 2012 (UTC)

Clarify wording re jenkins-bot & gerrit2 -- they are automatic test runners.

re +1 and -1: Reword the thing about "no formal effect" to "no automatic effect".

There might be more than 1 patchset, but let's take that as a possible Q&A.

If you do git-review -s, do you need a Gerrit account for that? YES. Because when it is installing the commit message hook, it has to do an scp request to get the hook.

We should add something -- if you have an extension that's your own, how to get ownership? Leave to Q&A, tell people to click on the Gerrit project ownership link.

suggestions

 * add git install instructions for mac
 * use example extension repo (Gerrit project ) instead of git core (in instructions, keep screenshots the same)
 * give instructions for pip install for windows
 * if they get an "no ".gitreview" file found, then they need to cd into the core/extension directory before running
 * if installing git-review and get permission errors, a suggestion to use "sudo" on it
 * remove the --rebase from "update master"
 * explain what is value of +1 (collab with others)
 * note git-review -s requires a gerrit account first.
 * prune the screenshots on the article page to the meaningful content

git review complains about multiple commits
There are three problems with this "git review complains about multiple commits" thing, both here and on Git/Workflow: I've got a hunch that addressing this, especially #3, will make a lot of people happier. --Amir E. Aharoni (talk) 13:15, 26 May 2012 (UTC)
 * 1) The solution provided here and on Git/Workflow is different from the one usually offered on IRC by Roan: `git fetch gerrit'. By "usually" I mean that I saw Roan doing it at least twice. Other people may suggest other things.
 * 2) Roan's suggestion actually works. I haven't yet got the chance the suggestion here (git fetch --all; git remote update) and it's possible that it works, too, and that it's even better (I don't know how to cause this issue to happen). But honestly, I don't quite understand why does it work, and I would love to understand it. Currently all the offered solution sound too much like magic and it's not great.
 * 3) Most importantly: Is there really no way to avoid this in the first place?

Typo that I'm not sure how to fix
Since I'm not "git" savvy, I'm not sure how you want to handle it. In the section:

https://www.mediawiki.org/wiki/Git/Tutorial#Download_MediaWiki_example_extension_using_Git

There's a sentence "So, in this example you will have a core directory." followed by a screenshot showing a core directory. I don't see any command that would produce a directory named "core". Presumably, there's a line missing like:

Also, it says that the name is taken from the end of the URL which is "examples.git". However, it appears to drop the ".git" extension. Worth noting? --KevinCole (talk) 18:14, 10 July 2012 (UTC)