Create Task
Maniphest T134256

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

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
Search...

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):

Aklapper added a comment.May 11 2016, 7:03 PM

Quick status update:

Aklapper added a comment.May 12 2016, 6:31 PM

Quick status update:

Aklapper added a comment.May 12 2016, 6:32 PM

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
Aklapper added a comment.May 15 2016, 10:44 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
01tonythomas added a subscriber: 01tonythomas.Sep 7 2016, 4:13 AM

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.

01tonythomas added a comment.Sep 9 2016, 12:32 PM

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

Aklapper added a comment.Oct 2 2016, 8:41 AM

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

In T134256#2613626, @01tonythomas wrote:
  • 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

In T134256#2622878, @01tonythomas wrote:

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

Content licensed under Creative Commons Attribution-ShareAlike 3.0 (CC-BY-SA) unless otherwise noted; code licensed under GNU General Public License (GPL) or other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL