Gerrit/Výukový program

This page is a translated version of the page Gerrit/Tutorial and the translation is 97% complete.
Outdated translations are marked like this.
Pokud máte nějaké zkušenosti s příkazovým řádkem a Git, použijte místo toho krátký návod jak na to .

Tento výukový program vysvětluje, jak nainstalovat Git a používat jej k vytváření a úpravě požadavků na změny v Gerrit.

V tomto tutoriálu začínají příkazy pro zadání znakem dolaru v poli, jako je tento: příkaz. Nezadávejte předvolbu $.
Pokud příkaz obsahuje také proměnnou, kterou musíte sami změnit, pak se proměnná zobrazí červeně: command proměnná.

Co je Git?

Git je bezplatný a otevřený zdroj distribuovaný systém správy verzí. "Distributed" (distribuován) znamená, že neexistuje žádná centrální kopie úložiště. S Git, jakmile naklonujete repozitář, máte plně funkční kopii zdrojového kódu se všemi větvemi a označenými verzemi k dispozici.

Vytvořte si vývojářský účet Wikimedie

Pokud ještě nemáte vývojářský účet Wikimedie, vytvořte si jej. Stejné uživatelské jméno a heslo bude použito pro přihlášení do Gerritu níže.

Nastavení Gitu

Tyto pokyny vysvětlují, jak nainstalovat Git jako nástroj příkazového řádku (okna terminálu). Pokud dáváte přednost grafickému uživatelskému rozhraní (GUI) místo příkazového řádku, podívejte se na seznam klientů spravovaných projektem Git. Další pokyny k instalaci naleznete v oficiální dokumentaci.

Instalace

Postupujte podle Instalace Gitu a zjistěte, jak nainstalovat git do operačního systému.

Nakonfigurování Gitu

Chcete-li zobrazit všechny konfigurační proměnné používané Gitem, spusťte git config -l.

Nyní, když máte nainstalovaný Git, je čas nakonfigurovat vaše osobní údaje. Měli byste to udělat pouze jednou. Své osobní údaje můžete také kdykoli změnit opětovným spuštěním těchto příkazů.

Git sleduje, kdo provedl každý závazek, kontrolou jména a e-mailu uživatele. Kromě toho se tyto informace používají k přidružení vašich závazků k vašemu účtu Gerrit.

Zadejte dva níže uvedené příkazy a nastavte své uživatelské jméno a e-mailovou adresu. Nahraďte Gerrituser uživatelským jménem svého účtu vývojáře Wikimedie (toto bylo dříve známé jako uživatelské jméno "Wikitech", "Gerrit" nebo "LDAP", všechny jsou stejné). Nahraďte $2 svou vlastní e-mailovou adresou. A nahraďte $3 uživatelským jménem shellu (zvoleným při vytváření účtu vývojáře Wikimedie): Replace gerrituser@example.com with your own email address. And, replace shell_user with the shell username (chosen when you created the Wikimedia Developer account):

git config --global user.email "gerrituser@example.com"

git config --global user.name "Gerrituser"

git config --global url."ssh://shell_user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"

Nastavení klíčů SSH v Gerritu

K vytvoření zabezpečeného spojení mezi vaším počítačem a Gerritem používáme klíč SSH. Bezpečnostní tým Wikimedie doporučuje, aby od srpna 2021 uživatelé vytvářející klíče SSH používali typ ed25519 pro optimální zabezpečení a výkon.

Získejte svůj klíč SSH

Postupujte podle SSH klíče#Generování nového klíče SSH.


Přidejte veřejný klíč SSH do svého účtu Gerrit

  • Přihlaste se do webového rozhraní pro Gerrit. Uživatelské jméno a heslo pro váš Gerrit jsou stejné jako pro váš účet vývojáře Wikimedie.
  • Klikněte na své uživatelské jméno v pravém horním rohu a poté vyberte "Nastavení".
  • V nabídce vlevo klikněte na "Klíče SSH".
  • Vložte svůj veřejný klíč SSH do odpovídajícího pole a klikněte na "ADD NEW SSH KEY".

Test připojení Gerrit SSH

Připojte se k serveru Gerrit přes ssh a zkontrolujte, zda vše funguje podle očekávání. Nahraďte shell_user vaším uživatelským jménem shellu, jak je uvedeno v nastavení Gerrit:

ssh -p 29418 shell_user@gerrit.wikimedia.org
  • Buďte opatrní a porovnejte, že "otisk klíče ed25519" je stejný jako SSH otisk na gerrit.wikimedia.org:29418. Pokud je to stejné, odpovězte "Ano" na "Opravdu chcete pokračovat v připojení?". Poté zadejte přístupovou frázi pro váš klíč.
  • Měli byste dostat zprávu "Vítejte v Gerrit Code Review". Na posledním řádku by mělo být uvedeno "Připojení k gerrit.wikimedia.org uzavřeno."
  • Pokud narazíte na problémy, použijte ssh -p 29418 -v shell_user@gerrit.wikimedia.org (nahraďte shell_user vaším uživatelským jménem shellu). -v poskytne podrobný výstup, který pomůže najít problémy. Pak si přečtěte Odstraňování problémů Gerrit.

Příklad zprávy o úspěšném připojení Gerrit SSH vypadá takto:

Example:

Stáhněte si kód pomocí Git

Sandbox

Pokud byste si chtěli procvičit používání Gerritu, můžete si stáhnout (také nazývané "klonování") úložiště, které tento tutoriál používá, s názvem "sandbox".

Spusťte následující na Git Bash příkazový řádek:

git clone https://gerrit.wikimedia.org/r/sandbox

Tím se zkopíruje celá historie a kódová základna úložiště rozšíření "sandbox" do vašeho počítače. Budete mít pracovní adresář hlavní větve rozšíření (obvykle také nazývaný "git master"). Zadejte nový adresář (příkazem cd sandbox). Nyní se můžete podívat na kód a začít jej upravovat.

Stávající úložiště

Klonování repozitáře Sandbox vám nezíská nastavení vývojového prostředí ani spuštěnou instalaci MediaWiki. (Spuštění bude vyžadovat MediaWiki Core a umístění kódu, který jste odhlásili, na místo, které očekává váš webový server.) Podívejte se na Stáhnout z Git, kde najdete informace o tom, jak stáhnout MediaWiki Core, rozšíření, vzhledy nebo jakýkoli jiný projektový repozitář hostovaný na gerrit.wikimedia.org z Gitu.

Vagrant

Pokud jste si stáhli MediaWiki nebo rozšíření pomocí Vagrant, ujistěte se, že máte nakonfigurován Git pro odesílání kódu pomocí SSH namísto HTTPS.

Připravte se na práci s Gerritem

Hlavní stránka: Gerrit/git-review

Gerrit vyžaduje, aby vaše zpráva potvrzení měla "změnit ID". Vypadají jako Change-Id: Ibd3be19ed1a23c8638144b4a1d32f544ca1b5f97 začínající I (velké i). Pokaždé, když upravíte odevzdání za účelem vylepšení existujícího patche v Gerritu, toto ID změny zůstane stejné, takže ho Gerrit chápe jako novou "sadu oprav", která řeší stejnou změnu kódu.

Existuje doplněk git s názvem git-review, který přidává řádek Change-ID do vašich revizí. Doporučuje se použít git-review. Usnadňuje konfiguraci vašeho klonu Git, odeslání změny nebo načtení existující.

Instalace git-review

Všimněte si, že Wikimedia Gerrit vyžaduje git-review verze 1.27 nebo novější.

Další podrobnosti naleznete na stránce Gerrit/git-přezkoumání#Instalace.

  Linux

  Windows

  macOS

  • Pro OS X 10.11 El Capitan a novější postupujte podle Metody 1.
  • Ve verzích před 10.11 použijte instalační program balíku pip Python podle Metody 2.

Konfigurace git-review

Výchozí název vzdáleného hostitele Git je "origin". Tento název používají také projekty Wikimedie. Potřebujeme říct git-review, aby používali tohoto hostitele. Nahraďte gerrituser svým uživatelským jménem Gerrit:

git config --global gitreview.remote origin

git config --global gitreview.username gerrituser

Nastavení git-review

Po stažení ("klonování") úložiště jej musíte nastavit na git-review. K tomu dojde automaticky při prvním pokusu o odeslání odevzdání, ale obecně je lepší to udělat hned po klonování. Ujistěte se, že jste v adresáři projektu, který jste naklonovali (jinak se zobrazí chyba "fatal: Not a git repository" (nejedná se o úložiště git)). Poté spusťte tento příkaz:

git review -s --verbose

Ke konci výstupu byste měli vidět něco takového:

Example:

To vás může požádat o vaše uživatelské jméno git, pokud se liší od uživatelského jména shellu, které používáte.

Pokud se vám nepodařilo nainstalovat git-review, můžete k odeslání opravy použít Gerrit patch uploader nebo Gerrit/Web tutorial.

Ve výchozím nastavení git-review používá větev master. Pokud repo, na kterém pracujete, používá jinou větev, např. main, musíte nastavit konfigurační proměnnou gitreview.branch. To lze provést pomocí následujícího příkazu (kde main je název větve):

git config --add gitreview.branch main

Odeslat opravu

Ujistěte se, že jste naklonovali úložiště kódu, o které máte zájem (viz výše Stažení kódu pomocí Gitu).

Ujistěte se, že jste v adresáři úložiště kódu (příkaz pwd vám řekne, kde přesně jste).

Aktualizace hlavní vývojové větve

Ujistěte se, že hlavní vývojová větev (větev vytvořená při prvním klonování úložiště) je aktuální:

git pull origin master

Všimněte si však, že některá úložiště používají pro svou hlavní vývojovou větev jiný název (například main místo master nebo repozitář operations/puppet má větev production místo větve master).

Vytvoření větve

Nejprve vytvořte místní pobočku pro vaši novou změnu. Nahraďte BRANCHNAME níže krátkým, ale přiměřeně popisným názvem (např. T1234, pokud pro vaše změny existuje odpovídající úkol Phabricator , cleanup-something nebo badtitle-error). Ostatní lidé budou také používat toto jméno k identifikaci vaší pobočky.

git checkout -b BRANCHNAME origin/master

Example:

Tím vytvoříte novou větev (nazvanou BRANCHNAME) od nejnovějšího 'mastera' a zkontrolujete ji. Ve výše uvedeném příkladu jsme tuto novou větev nazvali cleanup-something.

Provedení změn

Proveďte změny v místním kódu. Použijte svůj preferovaný textový editor a upravte soubor. V níže uvedeném příkladu upravíme soubor README.md a přidáme slovo.

Poté zavřete textový editor a zkontrolujte změny, které jste provedli od posledního odevzdání, v souborech a v adresáři:

git diff

Example:

git diff zobrazuje vaše změny v jednotném formátu rozdílu: Odebrané řádky mají předponu mínus (-) a přidané řádky mají předponu plus (+). Tyto změny ještě nejsou "připraveny" (prostřednictvím git add) pro příští potvrzení.

Připravte své změny pro potvrzení

Spusťte git status a rozhodněte se, které z vašich změn by se měly stát součástí vašeho odevzdání. Zobrazí se seznam všech souborů, které jste v adresáři změnili. V tomto okamžiku výstup zobrazí jako poslední řádek "žádné změny nebyly přidány do odevzdání".

Použijte git add, aby se vaše změněné soubory staly součástí vašeho příštího odevzdání. Ve výše uvedeném příkladu jsme upravili soubor README.md, takže příkaz bude:

git add README.md Všechny soubory, které jste změnili a které jste nepředali do git add, budou při spuštění git commit v dalším kroku ignorovány.

Kdykoli si můžete změny již zavedené spuštěním git status kdykoli prohlédnout. Poté, co spustíte git add, git status již nebude ukazovat řádek "do potvrzení nebyly přidány žádné změny".
Můžete také použít git diff --cached, abyste viděli, které změny jsou naplánovány a půjdou do dalšího potvrzení. Výstup bude vypadat stejně jako u výše uvedeného příkazu git diff.

Proveďte své postupné změny

Jakmile budete spokojeni se seznamem změn přidaných pomocí git add, můžete tyto změny převést na potvrzení ve vašem místním úložišti pomocí

git commit

sandbox/.git/COMMIT_EDITMSG:

Poté budete ve svém textovém editoru požádáni, abyste přidali popisné shrnutí vašeho odevzdání. Musíte se řídit pokyny k zaslání zprávy. To ostatní lidé uvidí, když se podívají na historii změn v úložišti kódu.

Uložte zprávu odevzdání a zavřete textový editor. Zobrazí se souhrn (ID odevzdání, váš předmět, změněné soubory a řádky).

Tento krok můžete opakovat znovu a znovu, dokud nebudete mít sadu změn, které chcete poslat do hlavní větve.

Když zadáte git commit, zavazujete se k vaší místní kopii.

To znamená, že se můžete zavázat, jak často chcete, aniž byste potenciálně pokazili věci jinému vývojáři na projektu.

Připravte se poslat svůj závazek Gerritu

Synchronizujte svůj changeset se všemi změnami, ke kterým mohlo dojít v hlavní větvi, když jste pracovali ("rebasing"). Z vaší pobočky spusťte:

git pull --rebase origin master

Example:
git pull --rebase origin master načte nové odevzdání ze vzdáleného místa a poté na nich znovu založí vaše místní odevzdání.

Dočasně odloží změny, které jste provedli ve vaší větvi, použije všechny změny, které se udály v hlavní větvi, na vaši pracovní větev, a poté všechny změny, které jste provedli, sloučí (znovu potvrdí) zpět do větve. Tím se vyhnete budoucím konfliktům při sloučení.

Navíc vám dává příležitost otestovat své změny proti nejnovějšímu kódu v masteru.

Nyní jste připraveni odeslat svůj kód společnosti Gerrit ke kontrole. Pokud jste provedli několik souvisejících odevzdání, zvažte jejich sloučení do jediného odevzdání ke kontrole.

Odešlete svůj závazek Gerritu

Pokud jste postupovali podle #Připravte se na práci s Gerritem výše a nainstalovali jste git-review a spustili git review -s, pak příkaz k odeslání změn do Gerrit je:

git review

Example:

Po úspěchu obdržíte potvrzení a odkaz na sadu změn v Gerritu. Ve výše uvedeném příkladu je tento odkaz: https://gerrit.wikimedia.org/r/#/c/sandbox/+/563720

Gratulujeme! Váš patch je v Gerritu a doufáme, že bude brzy zkontrolován!

<span id="If_git review_fails">

Pokud git review selže

Pokud budete při spuštění git review požádáni o zadání svého uživatelského jména a hesla, znamená to, že Git ještě nebyl nakonfigurován pro používání SSH.

Projděte si kroky na #nastavení Gitu. Konkrétně spusťte následující příkaz:

git config --global url."ssh://shell_user@gerrit.wikimedia.org:29418/".insteadOf "https://gerrit.wikimedia.org/r/"

Pokud si nejste jisti, zda jste to již udělali, můžete jej spustit znovu. Nahraďte shell_user uživatelským jménem shellu pro váš účet vývojáře Wikimedie.

Pokud získáte Permission denied (publickey). fatal: Could not read from remote repository., přečtěte si pokyny na SSH keys#Add SSH Private key to use with Git , abyste se ujistili, že váš agent ssh běží a vaše identita je přidána. Pokud zavřete prostředí Git Bash, budete odhlášeni a budete muset pokaždé znovu postupovat podle těchto pokynů.

Zobrazení změny / další kroky

Otevřete odkaz na svůj changeset Gerrit ve webovém prohlížeči.

V části "Soubory" po kliknutí na šipku dolů napravo od libovolného souboru v seznamu můžete vidět rozdíl vašich změn na soubor: Staré řádky jsou zobrazeny červeně a nové řádky jsou zobrazeny zelenou barvou. .

Gerritův rozdílový algoritmus (jGit) se mírně liší od výchozího rozdílového algoritmu git. Rozdíly zobrazené Gerritem nemusí vypadat jako rozdíly zobrazené Git na vašem počítači.

Pokud váš odevzdání adresuje tiket v Phabricator, bude komentář automaticky přidán do úlohy Phabricator, pokud jste postupovali podle pokynů pro zprávy Commit. Pokud jste to neudělali, můžete buď opravit zprávu o odevzdání (vytvořením aktualizované sady oprav), nebo ručně přidat komentář k lístku Phabricator, který obsahuje odkaz na vaši sadu změn v Gerrit.

Další běžné situace

Pokud zde vaše situace není pokryta, podívejte se také na Pokročilé použití Gerrit.

Squash několik odevzdání do jednoho jediného commitu přes rebase

Pokud jste před odesláním ke kontrole provedli několik souvisejících odevzdání do místního úložiště, měli byste tyto odevzdání zmáčknout (sloučit) do jednoho jediného potvrzení.

Volba --interactive nebo -i vám umožňuje změnit (přepsat) vaši historii odevzdání. U každého odevzdání můžete upravit a změnit zprávu odevzdání, přidat nebo odebrat soubory nebo provést jiné úpravy.

Nejprve musíte Gitu sdělit, jak daleko zpět chcete táhnout. Chcete-li získat seznam všech změn ve vaší pobočce:

git rebase -i origin/master

Můžete také omezit zobrazený seznam posledních změn. HEAD~3 znamená stáhnout poslední tři potvrzení:

git rebase -i HEAD~3

Po zadání tohoto příkazu váš textový editor zobrazí vaše odevzdání v opačném pořadí a seznam dostupných příkazů:

Example:

Protože chceme poslat ke kontrole pouze jeden commit, zmáčkneme poslední dva commity do jednoho. Změňte tedy všechny kromě prvního "pick" na "squash":

pick aa8cf1d Adding method customFilterFunctionGetRiskyCountryCodeScore() to GatewayAdapter.
squash 38828e2 Adding $wgDonationInterfaceCustomFiltersFunctionsRiskyCountries to donationinterface.php
squash be33007 Fix a typo

Když dokončíte vybírání a zmáčknutí a uložíte soubor, ve vašem textovém editoru se otevře další soubor, který vám umožní upravit a sloučit odevzdávané zprávy. Dávejte pozor, abyste ponechali pouze jeden z řádků Change-Id a aby bylo ve spodní části zprávy po jednom prázdném řádku.

Vaše zprávy z vašich předchozích odevzdání budou automaticky umístěny do této zprávy:

Example:

Nezapomeňte do odevzdání vložit svou (aktualizovanou) souhrnnou zprávu. V tomto případě bude nová souhrnná zpráva:

(mingle-fr-2012-69) Adding a custom filter for risky countries.
Pokud jde o to, který Change-Id chcete použít, zmáčknutí commitu do existujícího commitu (který už je v Gerritu), musíte vybrat Change-Id, který patří tomu, pro který jste chtěli odeslat nový patchset (přežívající commit). Pokud jsou vaše commity nové a nejsou v Gerritu, nezáleží na tom, jaké Change-Id si vyberete.

Pokud vše půjde dobře, měla by se zobrazit zpráva o úspěšném přehodnocení:

Example:

Poté odešlete svůj patch ke kontrole:

git review

Měli byste vidět zprávu podobnou této, která ukazuje, že vaše recenze git byla odeslána Gerritu (v tomto příkladu na https://gerrit.wikimedia.org/r/7187):

Example:

Úprava změny (vaše nebo někoho jiného)

Někdy může být potřeba upravit odeslanou změnu. Změnu můžete upravit, pokud ještě nebyla sloučena.

Můžete upravit své vlastní změny. Chcete-li upravit změny odeslané někým jiným, musíte být členem skupiny Gerrit's Trusted-Contributors (důvěryhodných přispěvatelů). Chcete-li se stát členem Trusted-Contributors, najděte někoho, kdo je členem, a požádejte ho, aby vás přidal. Skupina je virální v tom, že členové mohou přidávat nové členy, zodpovědně používající své pravomoci.

Nejprve zkontrolujte změnu pomocí tohoto příkazu:

git review -d changeNumber Například: git review -d 1814356

Můžete se podívat do Gerritu a zjistit changeNumber. Je to šestimístné číslo v adrese URL vaší stránky s kontrolou kódu.

Dále proveďte změny ve svém oblíbeném textovém editoru.

git add soubory podle potřeby, pak potvrďte změnu (ujistěte se, že upravujete odevzdání):

git add Example/Example.body.php

git commit --amend

NEPOUŽÍVEJTE příznak -m k zadání souhrnu odevzdání: Tím se přepíše předchozí souhrn a znovu se vygeneruje Change-Id. Místo toho použijte textový editor ke změně shrnutí odevzdání (v případě potřeby v souboru .git/COMMIT_EDITMSG a ponechte řádek Change-Id nedotčený.

Zatlačte na změnu:

git review


Rebasing (aktualizace opravy, aby zahrnovala další změny)

Někdy můžete chtít aktualizovat svůj patch tak, aby zahrnoval všechny změny v úložišti, ke kterým došlo od doby, kdy jste jej odeslali. Tomu se říká "rebasing" (přeměna). Obvykle to není třeba to dělat, ledaže by revize trvala dlouho a chcete se ujistit, že vaše změny stále fungují s nejnovější verzí softwaru, nebo pokud Gerrit nahlásí konflikt sloučení ve vaší změně.

Můžete to udělat lokálně pomocí příkazu git rebase se správnými možnostmi, ale webové rozhraní Gerrit poskytuje pohodlnější způsob, jak to udělat.

V nejjednodušším scénáři stačí kliknout na "Rebase", ponechejte výchozí výběr "Rebase na horní části hlavní pobočky" a opět klikněte na "Rebase".

Pokud má vaše oprava konflikt sloučení, dostanete chybu. Poté můžete zkontrolovat možnost "Povolit Rebase s konflikty" a zkusit to znovu, což změní vaši opravu s konfliktními značkami, podobně jako ty, které vytvoří příkazy GIT. Poté to budete muset sami změnit a editovat soubory ručně, abyste vyřešili konflikty.

Někdy můžete také chtít, aby se aktualizovala vaše oprava, aby zahrnovala změny navržené v jiné opravě (přidání závislosti na této záplatě), ale které ještě nebyly sloučeny. V tomto případě místo toho vyberte "Rebase na konkrétní změně, ref nebo commitovat" a zadejte změnu ve vstupním poli.

Pokud vaše oprava již má takovou závislost, získáte také možnost vybrat "Rebase na horní části hlavní větve (rozbije relační řetězec)", abyste ji odstranili. Získáte také možnost zkontrolovat "Rebase All Acsortors", která opraví záplatu se závislostí.

Pokud používáte příkaz git rebase, je nejlepší učinit aktualizace Rebase samostatnou opravou, takže recenzenti kódu mají snadnější čas vidět, jaké změny jste provedli a které změny se stalo v jiných záplatách.

Řešení problémů

Problémy a jak je vyřešit, najdete na stránce Gerrit/Odstraňování problémů .

Související odkazy

Tyto stránky jsou také užitečné:

Průvodce třetími stranami na Git

Poznámky pod čarou