Talk:Gerrit/Tutorial/Archive 1

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:

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.

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)

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 test/mediawiki/extensions/examples) 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:

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?

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)

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:

git clone https://gerrit.wikimedia.org/r/test/mediawiki/extensions/examples.git core

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)

origin vs. gerrit

Somehow after following this excellent tutorial and Git/Workflow, I have wound up with both "origin" and "gerrit" in my .git/config as remotes. They're actually the same host, but they show up as separate branches in git remote -l. The url for origin is

 [remote "origin"]
 	url = https://gerrit.wikimedia.org/r/mediawiki/extensions/MyExt

whereas for gerrit it is

 [remote "gerrit"]
 	url = ssh://username@gerrit.wikimedia.org:29418/mediawiki/extensions/MyExt

Because there are two, pushing to one leaves you not updated with respect to the other until you `git fetch remote` again. And trying to push to origin (over https) prompts for a username and password; the SSH password doesn't work, though gerrit has a web page that provides an HTTP Password.

I'm not sure how to fix -- SPage (WMF) (talk) 21:49, 20 August 2012 (UTC)

I did notice that the tutorial says to use git pull origin master while the workflow page says to use git pull gerrit master. Is that as it should be? Leucosticte (talk) 11:52, 6 October 2012 (UTC)

Struggling for MONTHS now...

There are essential pieces of information missing needed to get to work. Yes, I got the example extension; that doesn't help me, I need CORE! Where is the listing of all repositories where I can pick the one I need and clone it?

After trying lots of random URLs, I found the core repository at https://gerrit.wikimedia.org/r/mediawiki/core.git, but I get a 502 error when trying to clone. Is there someone please that can write a short, consice instruction on how to clone core? — Edokter (talk) — 11:54, 15 September 2012 (UTC)

"https://gerrit.wikimedia.org/r/pathToRepo.git" or "ssh://USERNAME@gerrit.wikimedia.org:29418/pathToRepo.git" if you have a Gerrit account. See gerrit:#/admin/projects for a list of the repository paths and descriptions. --Krenair ^{(talk • contribs)} 14:26, 15 September 2012 (UTC)

"The page you requested was not found, or you do not have permission to view this page." — Edokter (talk) — 20:12, 15 September 2012 (UTC)

Never mind; gerrit url handler is broken. — Edokter (talk) — 20:22, 15 September 2012 (UTC)

Oops, looks like MediaWiki encoded that URL. --Krenair ^{(talk • contribs)} 20:41, 15 September 2012 (UTC)

You said, There are essential pieces of information missing needed to get to work. What other pieces of information do you need? I hope https://gerrit.wikimedia.org/r/#/admin/projects/ helps you. I'm sorry for the trouble. Also, our IRC channel can often help you faster than people will see your questions onwiki. Sumana Harihareswara, Engineering Community Manager (talk) 03:01, 17 September 2012 (UTC)

git-review on Windows

I've just finished setting up git-review on Windows and have a couple of suggestions for the tutorial.

- Under "Installing git-review", it would be helpful to add a subsection on Windows with a link to http://www.mediawiki.org/wiki/Git/Workflow#Windows.

- Under "Set up SSH keys in Gerrit", the very last line, "Log into the web interface for gerrit..." appears to apply only to the Linux directions, which is false. I think this can be solved with a little whitespace.

Vasu.raman (talk) 15:58, 6 October 2012 (UTC)

Screenshots should be killed

Hi. The current collection of screenshots (sample image: File:Screen Shot 2012-05-25 at 10.39.36 AM.png) should be killed. Some people have recently been complaining about copyright concerns (apparently the screenshots are of Mac OS X's Terminal.app, Apple Inc.'s intellectual property), but that misses the larger issue: they're images of text. It doesn't make any sense for them to be images. They should be text so that they're able to be resized, reformatted, localized, etc. tswiki:Template:Terminal might be helpful for this purpose. No idea if I'll have time to do the deed myself anytime soon. Any help would be appreciated! --MZMcBride (talk) 03:59, 14 December 2012 (UTC)

Hashar already imported the template last year to Template:Terminal so what's missing is just converting the screenshots to text. --Tim Landscheidt 16:19, 17 March 2013 (UTC)

Git setup on Windows a nightmare

This definitely is not a way to go... I spent whole afternoon trying to contribute a single line of code but failed to set the whole thing up... :-( I dont know thether Subversion was easier, but this definitely is not a way how to attract more developers...--Kozuch (talk) 11:14, 28 January 2013 (UTC)

What problems did you find?--Qgil (talk) 00:37, 2 March 2013 (UTC)

Dividing into specific pages

What about splitting this long page into several focused pages? This would make each page more handy, easier to evolve/update. People specialized on each area could also watch and help in the right pages. This would also help fighting overlapping and having better connections with Gerrit/Workflow and Gerrit/Code review.--Qgil (talk) 00:47, 2 March 2013 (UTC)

Introduction
    How to Use this Tutorial
    What is Git?
    What is Gerrit?
    Why did Wikimedia engineering move from Subversion to Git
    See also

Setup
    Set Up SSH Keys in Gerrit
    Setting up Git
    Installing git-review

How to submit a patch
    Update master
    Create a branch
    Make and commit your change
    Prepare to push your change set to Gerrit
    Push your change set to Gerrit
    Amending a change

How we review code
    Review before merge
    Who can review? Gerrit project owners
    How to comment on, review, and merge code in Gerrit

As a newbie easy-patch submitter, I liked it a lot that this page contained all I really needed to know, and that even without knowing where to look for the information I needed it was easy for me to find it just by skimming and scrolling the page. --Nemo 20:45, 2 March 2013 (UTC)

To make it clear, I'm proposing only 4 pages that we could even turn into 3:

• Introduction + Setup
• How to submit a patch
• How we review code

These are distinct areas with no overlap. The support required for each is very different. Intro & Setup is a one-time thing. Submitting a patch and reviewing code are very different activities.--Qgil (talk) 21:33, 5 March 2013 (UTC)

I don't know what's best, but please don't say "only 4 pages". 4 pages means +300 % effort for searching stuff within them. --Nemo 21:38, 5 March 2013 (UTC)