View source for Talk:Gerrit/Tutorial

{{archives}}

== Amending one of your own existing changes ==

Under {{section link|{{PAGENAME}}|Amending a change (your own or someone else's)|nopage=1}}, the Gerrit tutorial says to use <code>git review -d</code> to download/checkout the change you want to amend before then making any changes to it. However, for amending your own patches, I'm wondering why the tutorial doesn't just say to make any changes in the branch you originally pushed to Gerrit from (if you still have access to it), before then running <code>git review</code> as you did when originally pushing the patch to Gerrit? 

This appeared to work when I tested it in the Gerrit sandbox (at [[gerrit:1141150]]), and - when you already have a local branch that you've been working in - it strikes me as being simpler than first using <code>git review -d</code> to download & checkout a new (pseudo-identical?) branch. Please tell me if I'm missing something here, though!
Best, <span class="skin-invert" style="color:#000"><span style="">&zwj;—&zwj;</span>[[user:a smart kitten|<span style="color:purple">a&nbsp;smart kitten</span>]]<sub>[<nowiki/>[[user talk:a smart kitten|<span style="color:#c814c8">meow</span>]]]</sub></span> 12:11, 4 May 2025 (UTC)

:I’ve used this method many times. I think the only reason for not documenting it is that the author didn’t want to describe two ways to achieve the same thing – but maybe they should have. —[[User:Tacsipacsi|Tacsipacsi]] ([[User talk:Tacsipacsi|talk]]) 20:05, 4 May 2025 (UTC)
::@[[User:A smart kitten|A smart kitten]] @[[User:Tacsipacsi|Tacsipacsi]] I just got to this situation myself today :) I rewrote a lot of the section, what do you think? [[Gerrit/Tutorial#Amending_changes]] [[User:Douginamug|Douginamug]] ([[User talk:Douginamug|talk]]) 08:16, 7 May 2025 (UTC)
:I tend to always re-pull the change from upstream specifically so that if there have been any new change sets pushed by a reviewer I have them to start my work from. Generally treating gerrit's view of the change set as canonical once you do your first <code>git review</code> submission will make your life easier in my experience. -- [[User:BDavis (WMF)|BDavis (WMF)]] ([[User talk:BDavis (WMF)|talk]]) 23:41, 7 May 2025 (UTC)
::Amendments by others is a good point, and one should indeed be aware of them (I didn’t consider them when writing the above answer, even though I’ve experienced quite a few accidents arising from ignoring this possibility); however, I don’t think always re-pulling is the solution for that:
::* on the one side, most patches are never amended by others (maybe amending others’ changes is more common within WMF/WMDE teams than among volunteers, but my experience is that even WMF employees’ patches are rarely amended by others), so it just wastes time to check out the patch again;
::* and on the other side, there’s still a race condition: what if someone amends the change <em>after</em> you re-pulled it?
::So I’d keep the mention of re-using local branches, but add a warning to watch out for conflicts. —[[User:Tacsipacsi|Tacsipacsi]] ([[User talk:Tacsipacsi|talk]]) 17:06, 10 May 2025 (UTC)

== Rewrite requested ==

This documentation is far too broad (Wikipedia already defines Git), difficult to follow, contains archaic or vague references, a "wall of words", without helpful workflow or concept illustrations, the only screenshots are for console messages which could be easily put into <code><nowiki><pre></nowiki></code> tags for easy editing and even translation. 

In short, the tutorial at https://vlab.noaa.gov/code-review/Documentation/intro-gerrit-walkthrough-github.html is a far better example. 

Where does that page come from? It is a single page of the upstream project documentation which NOAA publishes for their users of Gerrit, complete with local 'dirty' modifications. NOAA does this because they offer Gerrit to their people just like WMF. WMF could easily do the same, or just reference it and make notes of exceptions or deviation in the WMF instance.

Wait! WMF already '''does''' publish a copy of the official documentation at https://gerrit.wikimedia.org/r/Documentation/index.html for the version used by WMF

So why is that link buried in the footnotes, and why does the '[[Gerrit/Advanced usage|advanced]]' page tell users in 2026 to consult the <code>man</code> page? It is totally understandable that an advanced user ''would'' use <code>man</code> but that's not helpful to average users as a generic warning label.

I would rewrite this entire page, but I don't have the time, and don't have the political capital. I'm just a user with plenty of knowledge about Git and code review but unfamiliar with Gerrit and WMF idioms trying to make a contribution to the MediaWiki codebase and encountering friction and frustration instead of a helpful User Guide or Tutorial. [[User:GregRundlett|Greg Rundlett]] ([[User talk:GregRundlett|talk]]) 19:33, 20 May 2026 (UTC)