Last modified: 2013-03-05 22:46:31 UTC

Wikimedia Bugzilla is closed!

Wikimedia migrated from Bugzilla to Phabricator. Bug reports are handled in Wikimedia Phabricator.
This static website is read-only and for historical purposes. It is not possible to log in and except for displaying bug reports and their history, links might be broken. See T38437, the corresponding Phabricator task for complete and up-to-date bug report information.
Bug 36437 - A strict and correct Git workflow document is needed
A strict and correct Git workflow document is needed
Product: Wikimedia
Classification: Unclassified
Git/Gerrit (Other open bugs)
All All
: High major with 1 vote (vote)
: ---
Assigned To: Quim Gil
Depends on:
Blocks: documentation
  Show dependency treegraph
Reported: 2012-05-02 13:04 UTC by Amir E. Aharoni
Modified: 2013-03-05 22:46 UTC (History)
14 users (show)

See Also:
Web browser: ---
Mobile Platform: ---
Assignee Huggle Beta Tester: ---


Description Amir E. Aharoni 2012-05-02 13:04:18 UTC
A strict, correct and binding Git workflow document is urgently needed.

Not "an introduction to Git for dummies", not a list of tips and not a "best practices" document, but a complete document that would be strict and binding.

There's a page called Git/Workflow at I would expect it to be such a document, but currently it is:
* way too long
* not binding
* not controlled
* not actually used by a lot of frequent committers.

I tried to improve it as much as I could, but my git knowledge is very basic. Many other developers are saying the same.

Git can be a wonderful and ultra-flexible tool. People who know it well can juggle with it as much as needed. But when there are no stable procedures for updating the local repo and for committing a simple patch, a lot of people will waste hours on figuring out things that should take minutes. And new prospective developers WILL give up before submitting the first patch. I already saw it happen.
Comment 1 Sumana Harihareswara 2012-05-04 16:12:02 UTC
Assigning this to the new contractor who is working on the Git tutorial .

It seems like there should be a reference (the Workflow document) and a HOWTO (the tutorial).  The reference should very detailed and descriptive, but the HOWTO should be as simple as possible and prescriptive.
Comment 2 Krinkle 2012-07-08 23:07:32 UTC
Almost everything currently in the Workflow document are tutorials. How people do things should only be in the specification / guideline if it is relevant for other people (e.g. whether I use git-review or git push HEAD:refs/for/master doesn't matter for anyone but myself).
Comment 3 Andre Klapper 2012-10-19 18:03:47 UTC
Danielle: Is there any progress on this?
Comment 4 Sumana Harihareswara 2012-10-19 18:07:45 UTC
Since Danielle is no longer contracting for the Wikimedia Foundation I am de-assigning her from this.
Comment 6 Quim Gil 2012-11-27 17:45:55 UTC
^demon just shared the URL that says it all:

For what is worth I have proposed this task as a project proposal for the Outreach Program for Women, since we have many candidates interested in documentation tasks:

We need a mentor. Volunteers please contact me. Thank you!
Comment 7 Andre Klapper 2012-12-10 08:50:07 UTC
Yesterday night I read and failed to find out what I'm expected to do with my patches in Gerrit that have received two +1s. 
Just do it and merge? Wait for someone providing a +2? 
I still have no idea what I'm expected to do (or not) & the docs don't tell me.

Hence my random two cents on our Git/Gerrit documentation:

Git/Gerrit should be a starting page. Highlevel overview. Keep actions (I want to do X) and roles ("I only want to get&run code" vs. "I want to develop and contribute back") in mind. Do NOT explain checking out etc like currently done.
Separate Git and Gerrit frontpages could be killed.

Have some Git page only for people that only want to check out and compile but not commit code. They don't need info on Gerrit or how to commit/push.

Cruft: Git/Workflow is written in future tense (before migration to Git/Gerrit) and should be merged with Git/Tutorial. I don't care about stuff like "Gerrit 2.3" and I don't even want to know which Gerrit version we run...

Sections like Git/Workflow#Troubleshooting  Git/Workflow#Troubleshooting_2  could be merged into Git/Tips and/or a Troubleshooting.

Gerrit/Navigation title could make clear it's about web interface only.
Comment 8 Antoine "hashar" Musso (WMF) 2012-12-10 09:14:17 UTC
The continuous integration workflow is described at :

That is a different workflow than submitting a patch in Gerrit, it is more about how to get it merged in the repository.
Comment 9 Andre Klapper 2012-12-10 09:36:11 UTC
Ah, thanks! "Continuous integration" is not mentioned at all on the Git/Workflow page so I don't know anything about it or other funky infrastructure pieces. ;)
Goal: "Make me find my way to get a patch merged into the codebase, please."
Comment 11 dan 2012-12-11 01:52:42 UTC
proposal :

1. these two pages would merge into one page, possibly :
2. place all git and gerrit documentation under that main url

3. content :
   a. use the opening from the current Gerrit page.
   b. table of contents of all of the related documentation
4. - break up the sections into their own pages and refer to them in the tutorial, e.g :
   a. What is Git
   b. What is Gerrit
   c. Why did Wikimedia engineering
   d. Setup SSH Keys in Gerrit
   e. Setting up Git
5. - break up the sections into their own pages and refer to them based on the workflow
   a. Getting setup section could become part of the tutorial instead
   b. create a step-by-step workflow and create sub-pages for those:
      i. create or use an existing repository
      ii. clone the repository
      iii. create a branch
      iv. work on your code
      v commit your code
      vi. push your change set
6. - break up the sections into their own pages and refer to them from the workflow page

7. - incorporate this info in the workflow sub-pages

8. redirect these to the main Git_and_Gerrit page

9. - add to the toc under the main Git_and_Gerrit page, possible move the System messages to its own page

10. incorporate this info in the workflow sub-pages
Comment 13 dan 2012-12-11 02:00:55 UTC
8. redirect these to the main Git_and_Gerrit page or an appropriate sub-page

(In reply to comment #11)
Comment 14 Quim Gil 2012-12-11 04:47:45 UTC
dan, your proposal makes sense as starters and I just wish you have the energy to keep it pushing it until completion. Do you feel like taking the bug and assigning it to yourself?

One comment that might be useful. There are basically 4 types of content to address:

- Git generic.
- Gerrit generic.
- Git/Gerrit specific to the general MediaWiki community workflow.
- Instructions specific to the workflow of certain project e.g. MediaWiki Core, extension X...


- Git / Gerrit generic content would be left to a minimum, linking to external resources for introductions, concepts, etc.
- Each workflow description specific to MediaWiki should have one and oly one page with a step-by-steb guide.
- If there are any instructions relative to a single project then they should be located in the documentation specific to that project, and linked from the Git / Gerrit pages.

Your proposal goes in this (common sense) line, but I want to stress the goodness of modularizing our Git/Gerrit documentation, not mix the different types and not spend much time/words with the generic info that others maintain so well.
Comment 15 Quim Gil 2012-12-11 22:21:55 UTC
After a chat with dan he volunteers on driving this task. Thank you!

It's not a trivial one. Please report here aout your progress and do not hesitate asking for help.
Comment 16 dan 2012-12-13 01:18:51 UTC
here’s a start :

i will continue to flush out my ideas, and once i’ve got the groundwork done, i’d be happy to accept anyone’s help adding and polishing the content.
Comment 17 Quim Gil 2012-12-27 19:12:06 UTC
From Gerrit code review guidelines -

"I'm a bit confused when it comes to various options I have in gerrit (for -2, -1, +1, +2) and it seems the docs are not up to date on that."

Referring to

The thread generated some answers but maybe that info doesn't make it to the page.
Comment 18 Andre Klapper 2013-01-02 11:31:22 UTC
Adding one more item to the link list... is one overview page.
Comment 19 Chad H. 2013-01-02 16:01:18 UTC
(In reply to comment #18)
> Adding one more item to the link list...
> is one overview
> page.

*sigh* Just what we need...another page to add to the pile. Complained on-list about this already.
Comment 20 Quim Gil 2013-02-22 22:12:15 UTC
It is very silent here. Is it because the problem has been progressively solved or because we got used to it?
Comment 21 Amir E. Aharoni 2013-02-22 23:47:47 UTC
We got used, but I repeatedly see new developers getting confused by it.
Comment 22 Krinkle 2013-02-23 00:58:03 UTC
(In reply to comment #20)
> It is very silent here. Is it because the problem has been progressively
> solved or because we got used to it?

I agree with Amir that "we" have obviously gotten used to it (we know exactly which page we like best and use CTRL-F to find a keyword and look up that one nasty trick we keep forgetting).

But that's not useful for new comers.

I think we're not there yet, but we're slowly promoting some of the pages to be more visible and merging some. is a pretty good portal now.

With main tabs being:
* Getting started
* Tutorial
* Workflow

And then there's a bunch of links in the sidebar.
Comment 23 Quim Gil 2013-02-28 05:48:40 UTC
(In reply to comment #11)
> proposal :
> 1. these two pages would merge into one page, possibly
> :
>    a.
>    b.

Even simpler proposal: 

a. Merge the content of both pages at
b. Make Git --> #REDIRECT [[Gerrit]]

And then go through the pages under Git/ and either rename to /Gerrit or merge/clean.


We don't need much Git documentation. It is generic and exists elsewhere. The basic Git steps are explained in our workflow, the rest can be linked.

Most of the documentation we need refer to our code review process, and we can organize hat under Gerrit/ . Generic Gerrit documentation also exists elsewhere and we can simply link to that.

Then we have a bunch of content created during the review process and the first days of Git/Gerrit at Wikimedia. A lot of that is simply not very useful or redundant.

After all that is cleaned we probably won't even need to have 2 extra nav bars.
Comment 24 Quim Gil 2013-02-28 05:53:14 UTC 
is now a redirect to

One page less.
Comment 25 MZMcBride 2013-02-28 07:53:56 UTC
(In reply to comment #23)
> And then go through the pages under Git/ and either rename to /Gerrit or
> merge/clean.

I think you mean Gerrit/ here. :-)

> Rationale:
> We don't need much Git documentation. It is generic and exists elsewhere. The
> basic Git steps are explained in our workflow, the rest can be linked.

Agreed, let's put everything under a "Gerrit/" pseudo-namespace and merge anything that's currently under "Git/" to "Gerrit/". If we ultimately switch to another Git frontend in the future (e.g., Phabricator), we'll use that as a pseudo-namespace. Makes sense to me.

(In reply to comment #24)
> is now a redirect to 
> One page less.

Yay. This is a good first step, but ultimately I think "Git/Gerrit" will point to "Gerrit/Workflow", as will "Git/Workflow".

That is, content page: [[mw:Gerrit/Workflow]] (keeping all content under "Gerrit/"). Redirect from [[mw:Git/Workflow]] and redirect from [[mw:Git/Gerrit]]. Sounds good to me.
Comment 26 Quim Gil 2013-02-28 17:45:41 UTC
Yes, there will be a little bit of extra work moving redirects to Gerrit but I'm happy doing it. I'm in axing mode and I just didn't want to wait.

More: git-review is now the place to document anything git-review. The page was a stub created and orphan before I found it.

git-gerrit is also an upstream project but the upstream documentation about installation seems to be too simplistic, covering only Linux (?). Anyway, you can see already some progress killing redundancies in mediawiki-org:

The only mw: page containing overlapping info is but being a tutorial I guess this makes sense... (not sure) Still, it would be good to check what page has better documentation. Help is welcome.

I have also requested a soft redirect at the basically duplicated page in Labs:
Comment 27 Quim Gil 2013-02-28 18:56:22 UTC
Another page less, converted into a redirect to the relevant section in the tutorial:
Comment 28 Quim Gil 2013-03-01 23:40:22 UTC content that was duplicated with the Tutorial has been removed. Mainly Setup instructions and basic Git operations). There is still plenty of material duplicated there. In order to avoid spamming the people in CC here, your answers and feedback are welcome at

On the other hand:

Git is now a redirect to Gerrit. Discussion about the whole cleaning happens at has now less links to offer and I have already mentioned my purpose to get rid of it completely (because we won't need it anymore). Yes, discussion happens in the discussion page.  :)
Comment 29 Quim Gil 2013-03-05 22:46:31 UTC
After a bunch of hours of wiki editing I'm resolving this report as FIXED:

* is the single landing page and contains the links to all the essential pages.

* and its shortest version contain the info that most users need as "workflow": setup, committing and reviewing.

* is the main page to find out about the multiple tutorials, tips and tricks we have around. 

* There are other pages describing the workflow for special cases: requesting a new repository, project ownership, +2 rights, code review process before merging.

The current situation is quite clear for new contributors (my main motivation to take this bug). A lot of polishing can be still done for the rest. At least there is no duplication under anymore.

If you still see users complaining please ask them to do it in the relevant discussion pages, or help them with an edit in the right place. Or at least paste their complaints here so we know what still needs fixing. Thank you.

Note You need to log in before you can comment on or make changes to this bug.