Last modified: 2013-03-05 22:46:31 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 mediawiki.org. 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.
Assigning this to the new contractor who is working on the Git tutorial https://www.mediawiki.org/wiki/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.
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).
Danielle: Is there any progress on this?
Since Danielle is no longer contracting for the Wikimedia Foundation I am de-assigning her from this.
List by Krinkle from wikitech-l today: * https://www.mediawiki.org/wiki/Git * https://www.mediawiki.org/wiki/Git/TLDR * https://www.mediawiki.org/wiki/Git/Tutorial * https://www.mediawiki.org/wiki/Git/Workflow * https://www.mediawiki.org/wiki/Git/Tips * https://www.mediawiki.org/wiki/Gerrit * https://www.mediawiki.org/wiki/Gerrit/Navigation + https://www.mediawiki.org/wiki/Git/Gerrit
^demon just shared the URL that says it all: http://www.mediawiki.org/wiki/Special:PrefixIndex/Git 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: http://www.mediawiki.org/wiki/Outreach_Program_for_Women#Consolidate_the_Git_.2F_Gerrit_documentation We need a mentor. Volunteers please contact me. Thank you!
Yesterday night I read https://www.mediawiki.org/wiki/Git/Workflow#Who_can_review.3F_Gerrit_project_owners 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.
The continuous integration workflow is described at : https://www.mediawiki.org/wiki/Continuous_integration/Workflow That is a different workflow than submitting a patch in Gerrit, it is more about how to get it merged in the repository.
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."
https://labsconsole.wikimedia.org/wiki/Help:Git https://labsconsole.wikimedia.org/wiki/Git
proposal : 1. these two pages would merge into one page, possibly https://www.mediawiki.org/wiki/Git_and_Gerrit : a. https://www.mediawiki.org/wiki/Git b. https://www.mediawiki.org/wiki/Gerrit 2. place all git and gerrit documentation under that main url https://www.mediawiki.org/wiki/Git_and_Gerrit/ 3. https://www.mediawiki.org/wiki/Git_and_Gerrit content : a. use the opening from the current Gerrit page. b. table of contents of all of the related documentation 4. https://www.mediawiki.org/wiki/Git/Tutorial - 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 etc. 5. https://www.mediawiki.org/wiki/Git/Workflow - 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 etc. 6. https://www.mediawiki.org/wiki/Git/Tips - break up the sections into their own pages and refer to them from the workflow page 7. https://www.mediawiki.org/wiki/Git/TLDR - incorporate this info in the workflow sub-pages 8. redirect these to the main Git_and_Gerrit page 9. https://www.mediawiki.org/wiki/Gerrit/Navigation - add to the toc under the main Git_and_Gerrit page, possible move the System messages to its own page 10. https://www.mediawiki.org/wiki/Git/Gerrit incorporate this info in the workflow sub-pages
https://labsconsole.wikimedia.org/wiki/Special:PrefixIndex/Git (In reply to comment #10) > https://labsconsole.wikimedia.org/wiki/Help:Git > https://labsconsole.wikimedia.org/wiki/Git
8. https://labsconsole.wikimedia.org/wiki/Special:PrefixIndex/Git redirect these to the main Git_and_Gerrit page or an appropriate sub-page (In reply to comment #11)
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... Ideally... - 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.
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.
here’s a start : http://www.mediawiki.org/wiki/User:Dan-nl/Git_and_Gerrit 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.
From Gerrit code review guidelines - http://lists.wikimedia.org/pipermail/wikitech-l/2012-December/065335.html "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 http://www.mediawiki.org/wiki/Code_review_guide The thread generated some answers but maybe that info doesn't make it to the page.
Adding one more item to the link list... https://www.mediawiki.org/wiki/Manual:MediaWiki_Git_Guide is one overview page.
(In reply to comment #18) > Adding one more item to the link list... > https://www.mediawiki.org/wiki/Manual:MediaWiki_Git_Guide is one overview > page. *sigh* Just what we need...another page to add to the pile. Complained on-list about this already.
It is very silent here. Is it because the problem has been progressively solved or because we got used to it?
We got used, but I repeatedly see new developers getting confused by it.
(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. https://www.mediawiki.org/wiki/Git 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.
(In reply to comment #11) > proposal : > > 1. these two pages would merge into one page, possibly > https://www.mediawiki.org/wiki/Git_and_Gerrit : > a. https://www.mediawiki.org/wiki/Git > b. https://www.mediawiki.org/wiki/Gerrit Even simpler proposal: a. Merge the content of both pages at https://www.mediawiki.org/wiki/Gerrit b. Make Git --> #REDIRECT [[Gerrit]] And then go through the pages under Git/ and either rename to /Gerrit or merge/clean. 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. 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.
https://www.mediawiki.org/wiki/Git/Gerrit is now a redirect to https://www.mediawiki.org/wiki/Git/Workflow One page less.
(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) > https://www.mediawiki.org/wiki/Git/Gerrit > is now a redirect to > https://www.mediawiki.org/wiki/Git/Workflow > > 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.
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 https://www.mediawiki.org/wiki/Gerrit/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: https://www.mediawiki.org/wiki/Special:WhatLinksHere/Gerrit/git-review The only mw: page containing overlapping info is https://www.mediawiki.org/wiki/Git/Tutorial 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: https://labsconsole.wikimedia.org/wiki/Talk:Git-review#Moving_git-review_documentation_to_mw:Git.2Fgit-review
Another page less, converted into a redirect to the relevant section in the tutorial: https://www.mediawiki.org/w/index.php?title=Git/Graphical_User_Interfaces&redirect=no
https://www.mediawiki.org/wiki/Gerrit/Workflow 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 https://www.mediawiki.org/wiki/Talk:Gerrit/Workflow On the other hand: Git is now a redirect to Gerrit. Discussion about the whole cleaning happens at https://www.mediawiki.org/wiki/Talk:Gerrit https://www.mediawiki.org/wiki/Template:Git_and_Gerrit 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. :)
After a bunch of hours of wiki editing I'm resolving this report as FIXED: * https://www.mediawiki.org/wiki/Gerrit is the single landing page and contains the links to all the essential pages. * https://www.mediawiki.org/wiki/Gerrit/Tutorial and its shortest version https://www.mediawiki.org/wiki/Gerrit/Getting_started contain the info that most users need as "workflow": setup, committing and reviewing. * https://www.mediawiki.org/wiki/Gerrit/Advanced_usage 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 mediawiki.org 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.
