[For your info]
I've spend some time in the last weeks rewriting and cleaning up our technical Git / Gerrit / Code Review documentation on mediawiki.org.
135 edits later, things feel a bit cleaner. :)
=== Changes ===
There is a central Git/Gerrit "Troubleshooting" page linked from the most relevant pages, instead of separate sections on three or four different pages which partially duplicated content (setting up Git and Gerrit on different operating systems had similar problems and missing central information). Some rather specific subpages were merged into existing pages (e.g. into "Gerrit/Advanced usage"). The entrance page https://www.mediawiki.org/wiki/Gerrit has a "Prerequisites" section and the sections are now structured by usecase / type of user. Some "too much detail" content was also removed (like the history of the Git and Gerrit software; you can check Wikipedia as it's irrelevant if you want just to get your patch done).
Full list of changes: https://phabricator.wikimedia.org/T134256#2317711
=== No changes ===
Some stuff I did not touch (as perfect is the enemy of good). For example, I'm still wondering about the role of https://www.mediawiki.org/wiki/Git_for_dummies compared to https://www.mediawiki.org/wiki/Gerrit/Getting_started%C2%A0and%C2%A0 https://www.mediawiki.org/wiki/Gerrit/Tutorial%C2%A0. Plus I still consider the screenshots of command line text output distractive on https://www.mediawiki.org/wiki/Gerrit/Tutorial%C2%A0.
=== Thank you ===
Thank you a lot to everybody who provided feedback, answers to my Gerrit questions, and helped editing those pages!
=== Next steps ===
After this technical documentation exercise, the next steps will focus on soft / social+organizational aspects of code review: * https://phabricator.wikimedia.org/T129068 Improve code contribution guidelines for patch authors by fixing https://www.mediawiki.org/wiki/Gerrit/Code_review/Getting_reviews%C2%A0etc * https://phabricator.wikimedia.org/T129067 Agree on + document a structured, standardized approach for reviewing code contributions by fixing https://www.mediawiki.org/wiki/Gerrit/Code_review%C2%A0etc.
Needless to say, your help is very welcome. More information to come soon.
Cheers, andre
2016-05-23 14:22 GMT+03:00 Andre Klapper aklapper@wikimedia.org:
Some stuff I did not touch (as perfect is the enemy of good). For example, I'm still wondering about the role of https://www.mediawiki.org/wiki/Git_for_dummies compared to https://www.mediawiki.org/wiki/Gerrit/Getting_started and https://www.mediawiki.org/wiki/Gerrit/Tutorial .
The original title of "Gerrit/Getting started" when I created it was "Git/TLDR". I explained the reason for this in a <!-- --> comment on top of it. It is still relevant today: * "Gerrit/Tutorial" is 16 pages when printed. * "Git for dummies" is 9 pages when printed. * "Gerrit/Getting started" is 1 page when printed.
I don't know about the other pages, but the number of pages in "Gerrit/Getting started" is very much by design, and I regularly check that it still conforms to that design.
"Gerit/Tutorial" is evidently[1] more popular despite being the longest, which I find surprising, but of course I'm biased. (It may or may not have something to do with search terms.)
[1] https://tools.wmflabs.org/pageviews/?project=mediawiki.org&platform=all-...
-- Amir Elisha Aharoni · אָמִיר אֱלִישָׁע אַהֲרוֹנִי http://aharoni.wordpress.com “We're living in pieces, I want to live in peace.” – T. Moore
I think it would be great to favor git fetch and git rebase over git pull and merge[1] in the beginners documentation so people don't start out with bad habits.
[1] https://wikitech.wikimedia.org/wiki/Help:Git_rebase
Bernd
On Mon, May 23, 2016 at 5:37 AM, Amir E. Aharoni < amir.aharoni@mail.huji.ac.il> wrote:
2016-05-23 14:22 GMT+03:00 Andre Klapper aklapper@wikimedia.org:
Some stuff I did not touch (as perfect is the enemy of good). For example, I'm still wondering about the role of https://www.mediawiki.org/wiki/Git_for_dummies compared to https://www.mediawiki.org/wiki/Gerrit/Getting_started and https://www.mediawiki.org/wiki/Gerrit/Tutorial .
The original title of "Gerrit/Getting started" when I created it was "Git/TLDR". I explained the reason for this in a <!-- --> comment on top of it. It is still relevant today:
- "Gerrit/Tutorial" is 16 pages when printed.
- "Git for dummies" is 9 pages when printed.
- "Gerrit/Getting started" is 1 page when printed.
I don't know about the other pages, but the number of pages in "Gerrit/Getting started" is very much by design, and I regularly check that it still conforms to that design.
"Gerit/Tutorial" is evidently[1] more popular despite being the longest, which I find surprising, but of course I'm biased. (It may or may not have something to do with search terms.)
[1]
https://tools.wmflabs.org/pageviews/?project=mediawiki.org&platform=all-...
-- Amir Elisha Aharoni · אָמִיר אֱלִישָׁע אַהֲרוֹנִי http://aharoni.wordpress.com “We're living in pieces, I want to live in peace.” – T. Moore _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Mon, May 23, 2016 at 9:42 AM Bernd Sitzmann bernd@wikimedia.org wrote:
I think it would be great to favor git fetch and git rebase over git pull and merge[1] in the beginners documentation so people don't start out with bad habits.
[1] https://wikitech.wikimedia.org/wiki/Help:Git_rebase
Bernd
`git pull -r` for life :)
-Chad
I should stop myself here and just echo what Chad said but I feel compelled to say more.
Skip past the quoted text for the tl;dr version.
That article[1] comes across as incredibly condescending. Is the purpose to keep people ignorant and oppressed? Prevent them from understanding nuance by prescribing one world view and denying any other perspectives? Make them slaves to gerrit? I really fail to see the benefit of such propaganda.
I think it would be great to favor git fetch and git rebase over git pull and merge[1] in the beginners documentation so people don't start out with bad habits.
tl;dr:
# ~/.gitconfig
[branch] autosetuprebase = always
On Mon, May 23, 2016 at 12:32 PM, Chad innocentkiller@gmail.com wrote:
On Mon, May 23, 2016 at 9:42 AM Bernd Sitzmann bernd@wikimedia.org wrote:
I think it would be great to favor git fetch and git rebase over git pull and merge[1] in the beginners documentation so people don't start out
with
bad habits.
[1] https://wikitech.wikimedia.org/wiki/Help:Git_rebase
Bernd
`git pull -r` for life :)
-Chad _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
In case it wasn't obvious:
That was mostly intended as humor, though I do find the Help:Git_rebase article to be very one sided.
On Tue, May 24, 2016 at 10:00 PM, Mukunda Modell mmodell@wikimedia.org wrote:
I should stop myself here and just echo what Chad said but I feel compelled to say more.
Skip past the quoted text for the tl;dr version.
That article[1] comes across as incredibly condescending. Is the purpose to keep people ignorant and oppressed? Prevent them from understanding nuance by prescribing one world view and denying any other perspectives? Make them slaves to gerrit? I really fail to see the benefit of such propaganda.
I think it would be great to favor git fetch and git rebase over git pull and merge[1] in the beginners documentation so people don't start out
with
bad habits.
tl;dr:
# ~/.gitconfig
[branch] autosetuprebase = always
On Mon, May 23, 2016 at 12:32 PM, Chad innocentkiller@gmail.com wrote:
On Mon, May 23, 2016 at 9:42 AM Bernd Sitzmann bernd@wikimedia.org wrote:
I think it would be great to favor git fetch and git rebase over git
pull
and merge[1] in the beginners documentation so people don't start out
with
bad habits.
[1] https://wikitech.wikimedia.org/wiki/Help:Git_rebase
Bernd
`git pull -r` for life :)
-Chad _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Mon, 2016-05-23 at 17:32 +0000, Chad wrote:
On Mon, May 23, 2016 at 9:42 AM Bernd Sitzmann wrote:
I think it would be great to favor git fetch and git rebase over git pull and merge[1] in the beginners documentation so people don't start out with bad habits.
`git pull -r` for life :)
-Chad
I concentrated on Git docs on mediawiki.org and pretty much ignored content on wikitech.wikimedia.org.
I'm not a Git pro at all so if there seems to be consensus, please anyone be bold and edit to improve our contribution guidelines.
Thank you in advance!
andre
wikitech-l@lists.wikimedia.org