Gerrit/Code review/cs

Toto je průvodce revizí a slučováním příspěvků do úložišť kódu Wikimedie, napsaný primárně pro vývojáře "provádějící" recenze kódu.


 * Vývojáři, kteří odesílají kód ke kontrole, viz Kontrola kódu.
 * Úvod do nástroje Gerrit (komentování kódu; porovnání sad patchů) najdete ve webovém průvodci Gerritem.

Cíle

 * Poskytujte rychlé recenze, abyste se vyhnuli bitrotu a pocitům opuštěnosti. Rychlá zpětná vazba povzbuzuje vývojáře, aby nadále přispívali, a pomáhá tak rozšířit naši základnu přispěvatelů.
 * Buď milý. Přispěné záplaty jsou dárky. Recenze ovlivňují vnímání dobrovolníka o celém projektu.
 * Z dlouhodobého hlediska povzbuzujte přispěvatele kódu, aby se také stali recenzenty.



Hledání oprav ke kontrole
Je zde spousta kódu ke kontrole. Jak rozdělit úkol na lépe zvládnutelné části?

Existuje několik základních vzorů:



Podle projektu
Pokud jste správce, zvažte nastavení e-mailových upozornění na nové sady patchů ve vašich projektech (úložištích) prostřednictvím "Watched Projects" v Gerritu. Případně se můžete přidat do Gerrit Reviewer Bot, který vás automaticky přidá jako recenzenta do každé nové sady patchů.


 * Identifikujte hlavní části práce nebo sady souvisejících revizí. Dobrým způsobem, jak toho dosáhnout, může být rychlý chronologický přehled. Nebo si můžete vybrat úložiště s mnoha otevřenými sadami změn.
 * Otevřete všechny stránky changesetů jako karty v okně prohlížeče. Otevřete příslušné soubory v textovém editoru.
 * Zkontrolujte nové nebo neznámé soubory jako celek. Vyberte sadu změn s hlavní změnou v příslušném souboru a zkontrolujte ji.



Podle autora

 * Vyberte autora s (mnoha) otevřenými sadami změn, načtěte jej do Gerritu.
 * Procházejte revize chronologicky nebo postupujte po jednom tématu/úložišti.
 * Tato metoda umožňuje recenzentovi poznat jednotlivé vývojáře: Jejich dovednosti, chyby a zájmy. Práce má smysl pro pokrok a kontinuitu.

Pokud vás již někdo přidal jako potenciálního recenzenta a víte, že patch nebudete recenzovat, odeberte se ze seznamu recenzentů.



Noví přispěvatelé do našich projektů
Do své nabídky můžete přidat (některý z) níže uvedených dotazů úpravou uživatelských preferencí. "Nový přispěvatel" je definován jako osoba, která přispěla celkem pěti nebo méně sadami změn.


 * Otevřené sady změn od nových přispěvatelů byly úspěšně ověřeny robotem Jenkins a čekají na zpětnou vazbu od recenzentů
 * Zkontrolujte opravu, pokud jste obeznámeni s úložištěm, a udělejte rozhodnutí (CR±1 nebo CR±2).
 * Otevřené sady změn od nových přispěvatelů úspěšně ověřeny botem Jenkins a schváleny recenzentem (CR>0)
 * Pomozte učinit rozhodnutí (CR±1 nebo CR-2 nebo CR+2, pokud máte práva +2 pro úložiště).
 * Otevřené sady změn od nových přispěvatelů úspěšně ověřeny botem Jenkins a zamítnuty recenzentem (CR<0)
 * Zeptejte se, zda přispěvatel potřebuje pomoc a zda přispěvatel plánuje pokračovat ve zlepšování sady změn.
 * Otevřené sady změn od nových přispěvatelů nebyly úspěšně ověřeny botem Jenkins
 * Zeptejte se, zda přispěvatel potřebuje pomoc a zda přispěvatel plánuje pokračovat ve zlepšování sady změn.
 * Výsledky výše uvedených dotazů jsou všechny zahrnuty v tomto jediném dotazu: Všechny otevřené sady změn od nových přispěvatelů



Chronologické (a obráceně chronologické)

 * Začněte na nejstarší otevřené sadě změn, kontrolujte, dokud nedokončíte frontu. Alternativně začněte od poslední revize a čtěte postupně každý rozdíl, dokud nedosáhnete konce. Tento přístup je vhodný pro menší revize, ale vyžaduje neustálé přepínání mezi projekty a jejich kontexty.



Kontroly checklistu


Je to chtěné

 * Úplně první otázkou je, zda je příspěvek dobrý nápad. Pokud příspěvek není užitečný nebo neodpovídá směru a rozsahu projektu, vysvětlete a poskytněte zpětnou vazbu ohledně lepších nápadů.

Obecné

 * Přidaný kód by měl fungovat tak, jak je inzerováno, to znamená, že by měly být opraveny všechny chyby nalezené v kódu. (Ale buďte opatrní, abyste neobvinili současného vývojáře z kódu napsaného předchozím vývojářem.)
 * Zachovejte zpětnou kompatibilitu pro stabilní rozhraní, pokud je to relativně jednoduché.
 * Pokud je nutná zásadní změna za účelem provedení významných vylepšení, ujistěte se, že jsou dodržovány zásady stabilního rozhraní.
 * Přečtěte si příslušné zprávy o chybách nebo dokumentaci.
 * Seznamte se se všemi relevantními technickými problémy. Přečtěte si příslušné specifikace nebo části návodu.

Výkon

 * Kód, který je v požadavku spuštěn mnohokrát, nebo kód, který se spouští při spuštění, by měl být zkontrolován z hlediska výkonu (např. členem Wikimedia Performance Team). Podezřelý kód může být potřeba otestovat.
 * Jakýkoli webový kód, který je velmi neefektivní (z hlediska času, paměti, počtu dotazů atd.), by měl být označen pro opravu (např. vytvořením úkolu pro Phabricator).
 * Změny schématu databáze nebo změny dotazů s vysokým provozem by měl zkontrolovat expert na databáze. (Odpovídající úkol Phabricator by měl mít přiřazenou značku značku "schema-change".)

Vývoj

 * Zlepší nebo zhorší tato změna uživatelský dojem pro koncové uživatele? Pokud to má vliv na uživatelskou zkušenost nebo vizuální design, zvažte konzultaci nebo designový mailing list nebo jednoho ze správců designu.

Styl

 * Ujistěte se, že jsou dodrženy konvence stylu kódování, jako jsou mezery, délka řádku, umístění složených závorek atd.

Čitelnost

 * Funkce by měly dělat to, co říkají jejich názvy. Výběr správného slovesa je zásadní, funkce get* by měla něco získat, funkce set* by měla něco nastavit.
 * Názvy proměnných by měly používat angličtinu. Pokud je to možné, nepoužívejte zkratky.
 * Preferují se komentáře k funkcím.
 * Příliš komplikovaný kód by měl být zjednodušen. This usually means making it longer. For instance:
 * Ternary operators (?:) may need to be replaced with if/else.
 * Long expressions may need to be broken up into several statements.
 * Clever use of operator precedence, shortcut evaluation, assignment expressions, etc. may need to be rewritten.
 * Duplication, whether within files or across files, should be avoided.
 * It is bad for readability since it's necessary to play "spot the difference" to work out what has changed. Reading many near-copies of some code necessarily takes longer than reading a single abstraction.
 * It is bad for maintainability, since if a bug (or missing feature) is found in the copied code, all instances of it have to be fixed.
 * Some new developers might copy large sections of code from other extensions or from the core, and change some minor details in it. If a developer seems to be writing code which is "too good" for their level of experience, try grep'ing the code base for some code fragments, to identify the source. Guide the developer towards either rewriting or refactoring.
 * Taking shortcuts can be counterproductive, since the amount of time spent figuring out the shortcut and verifying that it works could have been spent just typing out the original idea in full.

Security

 * The reviewer should have read and understood the security guide and should be aware of the security issues discussed there.
 * There should not be the remotest possibility of arbitrary server-side code execution. This means that there should be no eval or create_function, and no /e modifier on preg_replace.
 * Check for text protocol injection issues (XSS, SQL injection, etc.) Insist on output-side escaping.
 * Check any write actions for CSRF.
 * Be wary of special entry points which may bypass the security provisions in WebStart.php.
 * Be wary of unnecessary duplication of security-relevant MW core functionality, such as using $_REQUEST instead of $wgRequest, or escaping SQL with addslashes instead of $dbr->addQuotes.
 * Only if you work on ancient code: Check for register_globals issues, especially classic arbitrary inclusion vulnerabilities. (Register Globals has been removed in PHP 5.4.0 and MediaWiki ≥1.27 requires PHP ≥5.5.9.)
 * If in doubt, consider contacting the Wikimedia Security Team.

Architecture

 * Names which are in a shared (global) namespace should be prefixed (or otherwise specific to the extension in question) to avoid conflicts between extensions. This includes:
 * Global variables
 * Global functions
 * Class names
 * Message names
 * Table names
 * The aim of modularity is to separate concerns. Modules should not depend on each other in unexpected or complex ways. The interfaces between modules should be as simple as possible without resorting to code duplication.
 * Check against the Architecture Principles.

Logic

 * Point out shortcuts and ask the developer to do a proper job.

Giving positive feedback

 * If you want to help to review the code, but don't feel comfortable (yet) making the final decision, you can use  in Gerrit and indicate whether you've "verified" and/or "inspected" the code.
 * If the revision is good and has passed all tests above, mark it  in Gerrit. If you are particularly impressed by someone's work, say so in a comment. When you mark a commit with , you're saying:
 * I've inspected this code, and
 * the code makes sense, and
 * the code works and does something that we want to do, and
 * the code doesn't do anything that we don't want it to do, and
 * the code follows our development guidelines, and
 * the code will still make sense in five years.

Giving negative feedback

 * If the revision is trivial, broken and has no obvious value, mark the commit as "Code-Review -2"
 * If the revision has issues but also has some utility, or is showing signs of heading in the right direction, mark it  and add a comment explaining what is wrong and how to fix it.  Never mark something   without adding a comment. If someone marks your code   it means that your code is good, but needs improvement.

You have to weigh up the costs and benefits of each course of action. If you reject the change completely, then that change will be lost, and the developer may be discouraged. If you tolerate the fault, the end product will suffer. If you fix it yourself, then you're letting yourself get distracted, and perhaps you're making the developer believe that it is acceptable to submit low-quality code and then let someone else worry about the details.

General guidelines on comment style, especially when giving negative feedback:
 * 1)  Focus your comments on the code and any objectively-observed behavior, not motivations; for example, don't state or imply assumptions about motivating factors like whether the developer was too lazy or unexperienced to do things right. Ask questions instead of making demands to foster a technical discussion: "What do you think about...?" "Did you consider...?" "Can you clarify...?"
 * 2)  Be empathetic and kind. Recognise that the developer has probably put a lot of work in their idea, and thank them for their contribution if you feel comfortable and sincere in doing so. "Why didn't you just..." provides a judgement, putting people on the defensive. Be positive.
 * 3)  Let them know where they can appeal your decision. For example, invite them to discuss the issue on wikitech-l or on IRC.
 * 4)  Be clear.  Don't sugarcoat things so much that the central message is obscured.
 * 5)  Most importantly, give the feedback quickly. Don't just leave negative feedback to someone else or hope they aren't persistent enough to get their contribution accepted.