Gerrit/Hodnocení kódu/Získání ohodnocení
- Chcete-li se dozvědět o kontrole kódu od ostatních, podívejte se do návodu a příručky pro kontrolu kódu.
Jak zajistit rychlejší kontrolu změn kódu a zvýšit pravděpodobnost, že budou přijaty?
Předpoklady
- Změnili jste nějaký kód, abyste opravili chybu nebo přidali novou funkci.
- Dodrželi jste konvence kódování.
- Dodrželi jste Kontrolní seznam předběžného potvrzení.
- Sledovali jste Kontrolní seznam zabezpečení pro vývojáře .
- Máte Účet vývojáře , který můžete použít s Gerritem a úspěšně nastavit Git/Gerrit na vašem počítači.
Nyní máte v plánu vytvořit opravu, kterou nahrajete do Gerritu, aby byl váš kód zkontrolován a sloučen (zahrnuto v kódové základně).
Váš kus kódu
Předem zkontrolujte, zda je v rozsahu
Pokud vámi navrhované změny kódu neopravují chybu, ale místo toho zavádí novou funkci, promluvte si nejprve se správci, abyste se ujistili, že váš nápad je v rozsahu projektu a že vámi navrhovaný technický přístup je optimálním řešením.[1] Ušetříte si tak čas a případné zklamání.
Otestujte své změny
Otestujte své změny ve svém vývojovém prostředí, abyste se ujistili, že nedochází k chybám kompilace nebo selhání testu. Pokud jste svůj patch z nějakého důvodu netestovali, řekněte to výslovně v komentáři v Gerrit. Zvažte procházení Kontrolního seznamu před potvrzením.
Vyhněte se poskytování neúplných oprav nebo zavádění nových chyb. Pokud víte, že váš patch potřebuje více práce, výslovně to řekněte v Gerritu tím, že jej zkontrolujete jako "-2" nebo přidáte předponu "[WIP]" (probíhající práce) do zprávy odevzdání.
Napište malé commity
S větší pravděpodobností budou přijaty malé, nezávislé, kompletní opravy.[2][3] Čím více souborů je ve vašem patchi ke kontrole, tím více času a úsilí zabere kontrola [4] a tím pravděpodobněji bude potřeba několik recenzí nebo větší počet opakování.[5]
Pokud se vaše commity budou dotýkat samostatných souborů a není mezi nimi velká závislost, bude pravděpodobně nejlepší ponechat je jako menší samostatné commity.
Dále se ujistěte, že do vašeho patche nejsou zahrnuty zbytečné změny (např. oprava stylu kódování).[1]
Pokud se však vaše odevzdání bude dotýkat stejných souborů opakovaně, spojte je do jednoho velkého odevzdání (pomocí buď --amend
nebo následného stlačení).
Napište smysluplnou zprávu o odevzdání
Zpráva Commit by měla popisovat co a proč. Jaký byl problém? Jak to oprava řeší? Jak otestovat, že to skutečně funguje? Další podrobnosti najdete na stránce Gerrit/Jak správně napsat text ke commitu .
Také se ujistěte, že jste provedli korekturu a používejte správný pravopis a interpunkci ve zprávě odevzdání.
Poskytněte dokumentaci
Pokud bude funkce ve vaší opravě viditelná pro koncové uživatele nebo administrátory, nezapomeňte aktualizovat nebo vytvořit související dokumentaci.[1] Další informace viz Zásady vývoje#Zásady dokumentace.
Nesměšujte rebase se změnami
Když rebasing, pouze rebase. Jsou-li v sadě změn provedeny jiné než rebase změny, musíte si přečíst mnohem více kódu, abyste to našli, a není to zřejmé. Když děláte skutečnou změnu, zanechte Gerrit komentář vysvětlující vaši změnu a upravte svůj souhrn odevzdání, abyste se ujistili, že je stále přesný.
Vaše činnost
Odeslat tiket Phabricator
Create a task in Phabricator explaining the motivation (see Phabricator/Help). Patches without Phabricator tickets are harder to find reviewers for. To associate them, include a line in the commit message that says "Bug:" followed by the Phabricator ticket number.
Reakce na selhání testu a zpětná vazba
Zkontrolujte nastavení Gerritu a ujistěte se, že dostáváte e-mailová upozornění. Pokud váš kód neprojde automatickými testy nebo již máte nějakou recenzi, odpovězte na ni v komentáři nebo opětovném předložení.
(Chcete-li zjistit, proč se automatické testy nezdaří, klikněte na odkaz v komentáři "neúspěšný" v Gerritu, umístěte ukazatel myši na červenou tečku neúspěšného testu, počkejte, až se zobrazí vyskakovací okno, a poté klikněte na "výstup konzoly".)
Zpětná vazba obvykle (ale ne vždy) přichází s příznakem C-2, C-1, C+1 nebo C+2 od Gerritu. Více o tom, co to znamená (z pohledu recenzenta), si můžete přečíst na Gerrit/Kontrola kódu#Dokončení recenze. Někteří recenzenti nabídnou návrhy na zlepšení, aniž by použili explicitní hodnocení C-1, aby ujistili nové přispěvatele. Stále byste měli brát jejich návrhy vážně.
Někdy obdržíte recenze, které budete vnímat jako irelevantní, například pouze kosmetické. Neignorujte takové recenze, ale upravte svůj patch tak, aby uspokojil triviální požadavky: Můžete nesouhlasit, ale diskuse stojí čas a je dražší než udělení bodu.
Přezkoumání kodexu je věcí budování konsenzu, nikoli vítězství ve volbách. Očekává se od vás, že negativní zpětnou vazbu budete řešit, nikoli ji "přehlasovat" hledáním dalších pozitivních recenzí. Řešení negativní zpětné vazby nevyžaduje vždy změny ve vašem patchi: Někdy stačí lepší vysvětlení. I v těchto případech však může být užitečné začlenit tato vysvětlení do zprávy odevzdání nebo komentářů v kódu, aby se budoucí správci se stejnými obavami lépe informovali.
Obecně platí: Buďte trpěliví a rozvíjejte se. Zkušenější autoři patchů dostávají rychlejší odpovědi a také pozitivnější.[5]
Přidání recenzentů
Výběr recenzentů hraje důležitou roli při hodnocení času. Aktivnější recenzenti poskytují rychlejší odpovědi.[5]
Ihned po potvrzení přidejte do sady změn jednoho nebo dva vývojáře jako recenzenty. (Toto jsou požadavky – neexistuje způsob, jak přiřadit recenzi jedné konkrétní osobě v Gerritu.) Zkušení vývojáři by s tím měli pomoci: Pokud si všimnete, že nezkontrolovaná sada změn přetrvává, přidejte recenzenty. Chcete-li najít recenzenty:
- Podívejte se na seznam hlavních správců nebo na správce uvedené na stránce rozšíření a zjistěte, kdo aktuálně spravuje danou část kódu nebo je ve školení správců.
- On your Gerrit patch's page, click on the project name, or "Repo" (e.g. mediawiki/core). Nyní v tomto úložišti najděte další sady změn: Lidé, kteří píší a kontrolují tyto sady změn, by byli dobrými kandidáty na přidání jako recenzenti.
- In large or very active projects, try filtering this list further. For example, if you're working on the MediaWiki database code, search for "message:rdbms" to find other changes in the rdbms component (this works as long as everyone follows the commit message guidelines and includes the component name in their commit messages).
- You can also filter changes by the files they modify; for example, search for file:mediawiki.page.gallery.styles to find all changes to styles of galleries, or path:resources/src/mediawiki.page.gallery.styles/print.less to narrow your search down to just their print mode styles (you can copy the file paths from your Gerrit patch's page, using the "Copy to clipboard" icon
on the file listing).
- See Gerrit search documentation for more advanced options.
- On your Gerrit patch's page, if you view the changes in one of the files by clicking on it in the listing at the bottom, you can click "Show blame" (in top-right corner) to find the previous patches affecting each line of the file. Unlike the previous methods, this often works even if the file has been renamed or if the code has been moved from another file. The authors and reviewers of those patches may be willing to review your work too.
Další recenze
Mnoho očí dělá brouky mělké. Přečtěte si Příručku pro kontrolu kódu a pomozte ostatním autorům chválením nebo kritikou jejich závazků. Komentáře jsou nezávazné, nezpůsobí sloučení ani zamítnutí a nemají žádný formální vliv na kontrolu kódu. Zkontrolováním se však naučíte, získáte si reputaci a přimějete lidi, aby vám opláceli laskavost tím, že v budoucnu zkontrolujete navrhované změny kódu. "How to review code in Gerrit" has the step-by-step explanation.
Řešení možných překážek
Žádná včasná zpětná vazba
Pracovní síla v projektech svobodného a otevřeného softwaru je omezená a zájmy vývojářů se mohou změnit. Některá úložiště kódu jsou aktivnější a udržovanější a budete dostávat rychlejší recenze. Jiné oblasti mají nejasnou správu nebo jsou dokonce opuštěné a možná budete muset dlouho čekat.
Nejnovější aktivitu v úložišti kódů můžete zkontrolovat prostřednictvím git log
ve vaší místní pokladně.
Chcete-li převzít opuštěný projekt a stát se jeho správcem, postupujte podle těchto kroků.
Pokud si myslíte, že váš patch zůstal bez povšimnutí delší dobu, neváhejte a upozorněte na problém na #wikimedia-tech připojit se IRC kanálu.
Další důvody pro přepracování nebo zamítnutí
I když jste dodrželi všechna doporučení, váš patch může stále vyžadovat přepracování (nebo ve vzácných případech může být dokonce zamítnut).
Kromě toho, co již bylo zmíněno, existuje více potenciálních důvodů pro zamítnutí (ne všechny jsou stejně rozhodující), jako je neoptimální řešení, pokud existuje jednodušší nebo efektivnější způsob, problémy s výkonem, problémy se zabezpečením, vylepšené pojmenování (např. proměnných), konflikty integrace se stávajícím kódem, duplikace práce, nezamýšlené (zne)užití API nebo navrhované změny interních API jsou považovány za příliš riskantní.[1]
Uvědomte si, že existuje nesoulad v úsudcích: Recenzenti oprav často považují selhání testů, neúplnou opravu, zavádění nových chyb, neoptimální řešení a nekonzistentní dokumenty pro zamítnutí opravy za mnohem rozhodnější než autoři oprav.[1]
Související odkazy
- "5 tipů pro rychlejší kontrolu kódu"
- "Poznámky ke schůzce s kontrolou kódu" - od roku 2012; příslušné části jsou nyní zahrnuty v této dokumentaci
Poznámky pod čarou
- ↑ 1.0 1.1 1.2 1.3 1.4 Yida Tao; Donggyun Han; Sunghun Kim, "Writing Acceptable Patches: An Empirical Study of Open Source Project Patches," in Software Maintenance and Evolution (ICSME), 2014 IEEE International Conference on , vol., no., pp.271-280, Sept. 29 2014-Oct. 3 2014
- ↑ Peter C. Rigby, Daniel M. German, and Margaret-Anne Storey. 2008. Open source software peer review practices: a case study of the apache server. In Proceedings of the 30th international conference on Software engineering (ICSE '08). ACM, New York, NY, USA, 541-550.
- ↑ Peter Weißgerber, Daniel Neu, and Stephan Diehl. 2008. Small patches get in!. In Proceedings of the 2008 international working conference on Mining software repositories (MSR '08). ACM, New York, NY, USA, 67-76.
- ↑ Amiangshu Bosu, Michaela Greiler, and Christian Bird. 2015. Characteristics of useful code reviews: an empirical study at Microsoft. In Proceedings of the 12th Working Conference on Mining Software Repositories (MSR '15). IEEE Press, Piscataway, NJ, USA, 146-156.
- ↑ 5.0 5.1 5.2 Baysal, O.; Kononenko, O.; Holmes, R.; Godfrey, M.W., "The influence of non-technical factors on code review," in Reverse Engineering (WCRE), 2013 20th Working Conference on , vol., no., pp.122-131, 14-17 Oct. 2013