Gerrit/Jak správně napsat text ke commitu
Tato stránka dokumentuje pokyny pro vývoj MediaWiki, vytvořené v průběhu času na základě dohovoru vývojářů (nebo někdy na základě prohlášení hlavního vývojáře) |
Důležitou roli hraje zpráva o potvrzení vaší změny. Je to první věc, kterou ostatní lidé uvidí o vaší změně.
component: Short subject line
More details. The blank line between the subject and body is
mandatory. The subject line is used to represent the commit in
code-review requests, search results, git rebase, logs, and more.
Bug: T54321
Struktura
Subjekt
První řádek zprávy odevzdání je znám jako subject (předmět). Předmět by měl být kratší než 80 znaků (zaměřte se na 50–70).
- Shrňte svou změnu do předmětu. Mějte na paměti, že to bude v úložišti navždy.
- Volitelně uveďte před předmět příslušnou komponentu. Komponenta je obecná oblast, kterou vaše potvrzení změní.
- Pomocí imperativní nálada popište svůj patch jako změnu. Vyhněte se uvádění faktu, jako je "Odznak skrývá nulu" nebo "Nulový odznak", který je nejednoznačný a nepopisuje změnu (dobrou nebo špatné před nebo po?). Zvažte místo toho "Skrýt nuly v odznakech", "Zobrazit nuly v odznakech" nebo "Odznak: Obnovit zobrazení nuly".
Rozkazovací nálada zní, jako byste někomu dávali pokyny, a může začínat slovy jako "Změnit", "Opravit", "Přidat", "Odebrat", "Dokument", "Refaktor", "atd." - Váš předmět by měl být krátký, jasně uveďte, co váš commit mění.
Nemělo by být možné použít stejný předmět pro dva commity, které dělají různé věci. Lidé budou číst váš předmět vytržený z kontextu, když prochází ve zdrojích změn, v e-mailech s kontrolou kódu, v protokolech git-blame, v poznámkách k vydání, v protokolu změn nasazení atd. Dobrý předmět pomáhá rychle rozhodnout, zda tento závazek z mnoha bude relevantní pro daný zájem nebo zájem. - Předmět neukončujte (
.
).
Dobré příklady jsou: | Špatné příklady by byly: |
---|---|
|
|
Tělo
Při psaní hlavního textu se zamyslete nad následujícími otázkami:
- Proč by tato změna měla být provedena? Co je špatného na aktuálním kódu?
- Proč by se to mělo měnit tímto způsobem? Existují jiné způsoby?
- Zvažovali jste i jiné přístupy? Pokud ano, popište, proč nebyly tak dobré.
- Jak může recenzent otestovat nebo ověřit, že váš kód funguje správně?
Doporučeno:
- Oddělte tělo od předmětu jedním prázdným řádkem.
- Zabalte zprávu tak, aby řádky byly dlouhé maximálně 100 znaků. Mnoho editorů/nástrojů to umí automaticky; 72 znaků je běžná šířka zalamování.[1] Nepřerušujte však adresy URL, aby se 'hodily', protože by na ně nebylo možné kliknout. Uchovejte je, i když jsou delší.
- Odkazujte na další odevzdání pomocí (krátkého) Gerrit Change-Id, jako je
I83f83377f2
, nebo hash Git commitu jako51e3fb9a71
. Pokud související změna ještě není sloučena, vždy použijte Gerrit Change-Id, protože hash Git commitu se po začlenění změní, což by vedlo ke slepé uličce.
Nedoporučeno:
- Neodkazujte na jiné odevzdání pomocí adresy URL nebo čísla změny.
- Místo toho použijte Gerrit Change-Id jako
I83f83377f2
nebo Git commit hash jako51e3fb9a71
. Tento druh hash se automaticky převede na odkaz při zobrazení změny v prohlížečích Gerrit, Gitiles a dalších repozitářích. Umožňuje také snadnou navigaci v úložišti Git během vývoje, například prostřednictvímgit show
nebo uvnitř textových editorů. - Na druhou stranu lze adresu URL vyřešit pouze ve webovém prohlížeči a jde na pevné místo, což narušuje pracovní postupy kontroly kódu a odchyluje se od místního kontextu. Například v prohlížeči Git vám hash umožňuje rychle přejít od jednoho potvrzení k souvisejícímu ve stejném nástroji, místo aby byl odeslán do Gerritu. Hashe lze také vyhledávat v Gerritu, aby se automaticky našly odevzdání, která na ně odkazují.
- Dalším problémem je, že čísla změn mohou být nejednoznačná nebo mohou být automaticky spojena s jiným potvrzením, než zamýšlíte. Je to proto, že hodnoty commit hash jsou někdy pouze čísla, např. commit 665661 je jiný než change 665661.
- Místo toho použijte Gerrit Change-Id jako
- Nepoužívejte pouze adresu URL jako vysvětlení změny.
- Pokud je změna odůvodněna diskusí jinde nebo nějakou externí dokumentací, zkuste shrnout klíčové body ve zprávě odevzdání a odkázat také na URL.
Zápatí a metadata
Nejdůležitější informace v zápatí jsou Change-Id
(povinné) a Bug
.
Naformátujte metadata "Bug
" a "Change-Id
" přesně jako v příkladech níže a umístěte je společně na konec těla za jeden prázdný řádek.
Více informací o jednotlivých polích metadat naleznete níže.
Příklady
Dobrý příklad
jquery.badge: Add ability to display the number zero Cupcake ipsum dolor sit. Amet tart cheesecake tiramisu chocolate cake topping. Icing ice cream sweet roll. Biscuit dragée toffee wypas. Does not yet address T44834 or T176. Follow-up to Id5e7cbb1. Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907
Špatný příklad
Improved the code by fixing a bug. Changed the files a.php and b.php Bug: T42 Change-Id: I88c5f819c42d9fe1468be6b2cf74413d7d6d6907
Další informace
.gitmessage
([příklad https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/refs/heads/master/.gitmessage]), použijte následující příkaz k získání šablony, která vás povede při psaní zprávy odevzdání: git config commit.template=.gitmessage
Subjekt
Většina programů, které používáme a které zobrazují potvrzení Git, vykresluje předmět (subject) jako prostý text. To znamená, že adresy URL nefungují a výběr/kopírování textu často není možné. Proto v předmětu neuvádějte úkoly Phabricator, commity Git ani adresy URL. Místo toho je uveďte v hlavním textu nebo metadatech zápatí. Tímto způsobem je lze univerzálně vybrat, zkopírovat nebo kliknout.
- Gerrit používá předmět v: e-mailových upozorněních, upozorněních IRC, výsledcích vyhledávání.
- GitHub používá předmět v: commit historie, commit subjektu.
- Git CLI používá předmět v:
git shortlog
,git log --oneline
,git rebase -i
,git show
, etc. - Poznámky k verzi implementačních větví MediaWiki Wikimedie
- a mnohem víc!
Součást
Řádek předmětu můžete začít částí, která bude indikovat, jaká oblast projektu byla změněna vaším odevzdáním.
Mělo by to být jedno z následujících:
- Adresář tříd PHP pod
includes/
neboincludes/libs
, například "installer", "jobqueue", "objectcache", "resourceloader", "rdbms", atd. - Název třídy PHP, například "Title", "User", "OutputPage", atd.; typicky pro třídy bez podadresáře v
includes/
. - Název modulu ResourceLoader (jako "mediawiki.Title", "mediawiki.util", atd.).
- Obecné klíčové slovo ovlivňující více oblastí souvisejících s typem změny, například:
- "build" - pro změny souborů souvisejících s vývojovým workflow, jako jsou aktualizace
package.json
,.travis.yml
, atd. - "tests" or "test" (depending on directory name) - pro změny, které ovlivňují pouze testovací sady QUnit nebo PHPUnit nebo běžce testovací sady.
- "build" - pro změny souborů souvisejících s vývojovým workflow, jako jsou aktualizace
Phabricator
Chcete-li odkazovat na chybu nebo úkol Phabricator , ve zprávě o odevzdání je uveďte inline pomocí zápisu Txxx (např. "That was caused by T169.")
Chcete-li vyjádřit, že se odevzdání vyřeší (dokonce částečně) nebo je pro chybu speciálně relevantní, přidejte Bug: Txxx
do zápatí na konec zprávy odevzdání.[2]
(Pokud upravujete zprávu commit, vložte ji bezprostředně nad řádek Change-Id:
, bez prázdného řádku mezi nimi. Nezapomeňte dodržovat pravidla celkové struktury a oddělte tělo od předmětu jedním prázdným řádkem.)
Bug: T169
Robot automaticky zanechá komentář k úloze Phabricatoru o všech významných událostech (sloučení, opuštění, atd.).
Pokud oprava řeší dvě nebo více chyb, umístěte každou referenci Bug: T12345
na samostatný řádek dole.
Bug: T299087 Bug: T299088
Křížové odkazy
Kdykoli odkazujete na další odevzdání, použijte SHA-1 git hash sloučeného odevzdání. Pokud odevzdání stále čeká na kontrolu, použijte hash Gerrit Change-Id místo hash git, protože hash souvisí s individuální sadou patchů (která se změní, když se znovu založí, čímž vznikne slepá ulička).
ID změny
Nástroj git-review
společnosti Gerrit automaticky připojí klíčové slovo "Change-Id: Ixxx
" k novým odevzdáním.
Závislosti
Depends-On: Ixxx
Pokud máte závislosti mezi repozitáři (vaše odevzdání závisí na jiném odevzdání v jiném úložišti), deklarujte je přidáním Depends-On: Ixxx...
do posledního odstavce.
("Ixxx"... jsou Change-Id
druhého potvrzení.)
To dá pokyn Zuulu, aby otestoval odevzdání společně s tímto.
Chcete-li vývojářům poskytnout další pokyny, můžete inverzní vztah označit pomocí Needed-By: Iyyy...
v posledním odstavci zprávy odevzdání v jiném úložišti.
("Iyyy"... jsou Change-Id
vašeho závazku.)
Všimněte si, že Zuul na to nereaguje, je to jen ku prospěchu lidských čtenářů.
Gerrit také automaticky přidá zpětné odkazy na základě přítomnosti Depends-On
, bez ohledu na jakékoli Needed-By
.
Připisování kreditu ostatním
Co-Authored-by: gerrit_username <gerrit_user_email@example.com>
Přidejte tento řádek před Change-Id
, abyste poděkovali ostatním vývojářům pracujícím na změně.
Můžete přidat více než jeden oddělený zalomením řádku.
by
ne velké. Jsou to Co-Authored-by
, ne Co-Authored-By
.
Další informace
- Příručka:Pravidla pro psaní kódu
- commit-message-validator
- Závazné pokyny Gerrit
- Node.js Závazné pokyny
- Základní pokyny pro závazky Git
- Závazné pokyny jQuery
- Závazné pokyny Erlang
- Poznámka o zprávách Git Commit - od Tima Popea
- Jak napsat zprávu Git Commit - od Chrise Beamse
- Gerrit integrations with the Puppet Catalogue Compiler
Poznámky pod čarou
- ↑ Toto je dědictví z dob, kdy byly linky poskytovány na děrných štítcích. Sloupce 1 až 72 se používají pro prohlášení a sloupce 73 až 80 pro krátké komentáře. Velikost 72 je dostatečně rozumná na to, aby kód pochopil na první pohled.
- ↑
Stejně jako u všech záhlaví/zápatí pište název se slovy jednotlivě velkými písmeny a pomlčkami mezi nimi (např.
Hypothetical-Header-Or-Footer
). Za jménem následujte dvojtečkou (":") a poté jednou mezerou. Podobně jako u Git commit, HTTP a Email hlaviček by přidání dalších prázdných řádků nad zápatí odřízlo zápatí a nesprávně zahrnulo první část do těla.