Page MenuHomePhabricator

Make Wikimedia's Git/Gerrit documentation less horrible and less scattered
Closed, ResolvedPublic

Description

A prerequisite for T129068: Improve code contribution guidelines for patch authors.
Because when those instructions to set up Git and Gerrit make me give up, I won't ever need to get to the Code Contribution guidelines.

Related Objects

StatusAssignedTask
ResolvedQgil
ResolvedDicortazar
DuplicateQgil
ResolvedQgil
ResolvedQgil
Resolvedgreg
InvalidNone
InvalidNone
ResolvedQgil
ResolvedAklapper
OpenNone
DeclinedNone
OpenNone
ResolvedAklapper
ResolvedAklapper
ResolvedAklapper
ResolvedDicortazar
ResolvedDicortazar
ResolvedAcs
ResolvedDicortazar
ResolvedDicortazar
ResolvedDicortazar
ResolvedDicortazar
ResolvedDicortazar
ResolvedDicortazar
InvalidDicortazar
ResolvedDicortazar
ResolvedDicortazar
ResolvedAklapper
ResolvedDicortazar
ResolvedDicortazar
DuplicateNone
ResolvedDicortazar
ResolvedBawolff
Resolvedmmodell
ResolvedNone
Resolvedmmodell
ResolvedLegoktm
Resolvedtstarling
Resolvedgreg
ResolvedAklapper
ResolvedAklapper
ResolvedAklapper
ResolvedAklapper
ResolvedNone

Event Timeline

Aklapper created this task.May 3 2016, 1:30 PM
Restricted Application added a subscriber: Zppix. · View Herald TranscriptMay 3 2016, 1:30 PM
Aklapper added a comment.EditedMay 3 2016, 4:15 PM

Posting a quick update. As this is complex and as I might wonder what I've been up to.

Work so far (so far in the last two days):

Stuff to do (not at all a complete list):

Quick status update:

Quick status update:

Last item left before I consider this task "acceptable" and hence resolved (as perfect is the enemy of good):

greg awarded a token.May 13 2016, 6:05 PM

I went through mw:Gerrit/* subpages to check which ones are relevant and to link from mw:Gerrit.
I'll drop my thoughts for that specific page https://www.mediawiki.org/wiki/Gerrit in this comment so I can pick them up tomorrow again:

  • Prerequisites:
    • dev env (vagrant); link to developer_hub and how_to_become_a_hacker, etc
  • Get the code and submit your first patch:
    • Gerrit/Tutorial - A thorough guide to using Git and Gerrit for MediaWiki development
    • Gerrit/Getting started - A very short guide to using Git and Gerrit for MediaWiki development
  • Tutorials and help for Gerrit:
    • Gerrit/Advanced usage - How to do things "the hard way" in gerrit
    • Gerrit/Troubleshooting - Problems and how to solve them
    • Gerrit/Navigation - How to navigate Gerrit's interface
    • Gerrit/FAQ - Frequently asked questions concerning how to use Git and Gerrit
    • Gerrit/GitHub - About integration with the GitHub service
  • For code contributors / authors:
    • Gerrit/Code review/Getting reviews - Learn how to get your patches reviewed
    • Gerrit/Commit message guidelines - Learn how to write good commit summaries
  • For code reviewers:
    • Gerrit/Code review - Learn how to perform code review. Your help reviewing changes is welcome!
    • Gerrit/+2 - Guidelines for reviewers with merging rights in Gerrit
  • For project owners / administration:
    • Gerrit/Inactive projects - Guidelines how to handle inactive projects
    • Gerrit/New repositories - How to create a new project in Gerrit
    • Gerrit/Project ownership - How to become the owner of a project in Gerrit
    • Gerrit/+2 - Guidelines for reviewers with merging rights in Gerrit
  • If you only want to get the code and do not plan to propose changes:
    • To simply browse & fork our code you can use the GitHub mirror. (TODO: We ignore pull requests according to https://www.mediawiki.org/wiki/Gerrit/GitHub#..._but_not_pull_requests , hence don't advertise like that?? In any case, link to mw:gerrit/GitHub from here)
    • To make an anonymous git clone of core MediaWiki... (TODO: again: is that relevant here? readonly?! Maybe just remove this whole section and move both items to better places in the mw:Gerrit/Tutorial?)
  • See Also:
    • .... (what's already there)
Aklapper closed this task as Resolved.EditedMay 23 2016, 11:21 AM

135 edits later, we're done with this part I'd say.
Big thanks to everybody who helped with edits and input!
I also emailed wikitech-l.

Done:

Not done:

Next steps:

Qgil awarded a token.May 23 2016, 1:22 PM

Something I had seen while asking Hackathon participants to move top down in https://www.mediawiki.org/wiki/Gerrit/Tutorial

These are found to be frequent blockers during hackathons and other events, and I am sure other devs too had been at similar situations.

Something more. This has happened many times, and I just think some fix with the document might help here.

tonythomas> in https://www.mediawiki.org/wiki/Gerrit/Tutorial#How_to_submit_a_patch -- it is said just to clone the Mediawiki core, and I see people just execute that command straightaway, while it should be actually done from the webserver DocumentRoot
17:51 <tonythomas> this can be like /var/www/html/ in most apache installs
17:51 <tonythomas> all my attendees (I guess), gets stuck here, and just clone the thing from where the terminal is at that point, and then wonders
17:52 <tonythomas> but its an expected knowledge for someone who have done something with php, apache etc, that the app should rest in the DocumentRoot, though

@01tonythomas: Thanks! This is extremely viable feedback.
Not 100% happy but I tried to improve things:

  • https://www.mediawiki.org/wiki/Gerrit/Tutorial#Setting_up_git-review - the git review -s should be run inside core/ which will only happen in the following 'How to submit a patch' doc. This is clear from the screenshot too. People get stuck here, as they keep on trying git review -s and the error message fatal: Not a git repository (or any parent up to mount point /home) shows up. Solution would be to move this from there, and I think it is not needed too, as clone via git from wm gerrit, and the first patch push would automatically setup gerrit for you.

https://www.mediawiki.org/w/index.php?title=Gerrit%2FTutorial&type=revision&diff=2251259&oldid=2249448

  • Downloading of MW core is given in https://www.mediawiki.org/wiki/Gerrit/Tutorial#How_to_submit_a_patch - this creates confusion and should be renamed as 'Download Mediawiki code (core) from Gerrit' or something like that. I think the downloading of core an extensions section can be a subsection in the submit a patch too, which would make more sense.

https://www.mediawiki.org/w/index.php?title=Gerrit%2FTutorial&type=revision&diff=2251268&oldid=2251259

https://www.mediawiki.org/w/index.php?title=Gerrit%2FTutorial&type=revision&diff=2251272&oldid=2251268

Something more. This has happened many times, and I just think some fix with the document might help here.

Fixed by yourself in https://www.mediawiki.org/w/index.php?title=Gerrit%2FTutorial&type=revision&diff=2236574&oldid=2235784