Gerrit/Jak správně napsat text ke commitu

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:
"Add Badge::query to query the API" "Avoid API query in SimpleBadge" "Support zeroes in SimpleBadge::add" "badger: Add accessibility labels to form fields" "rdbms: Avoid infinite loop on null input" "htmlform: Change colours to match April 2020 design"	"Added Badge::query method", "Badge can query the API" "Badge doesn't do API queries" "Fixed Badge::query method", "Zeroes work when adding badges" "Implement accessibility fixes" "Fix crash" "Use a better design"

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í. 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 jako 51e3fb9a71. 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 jako 51e3fb9a71. 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ím git 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.
• 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

Pokud má úložiště, do kterého přispíváte, soubor .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/ nebo includes/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.

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í. (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.

Všimněte si, že na rozdíl od jiných slov v zápatí zprávy odevzdání je slovo 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