Vytvoření stránky README pro úložiště

  • Článek

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Vaše úložiště Git by mělo mít soubor readme, aby diváci věděli, co váš kód dělá a jak ho můžou začít používat. Váš soubor readme by měl mluvit s následujícími cílovými skupinami:

  • Uživatelé, kteří chtějí jenom spustit váš kód.
  • Vývojáři, kteří chtějí sestavit a otestovat váš kód Vývojáři jsou také uživatelé.
  • Přispěvatelé, kteří chtějí odeslat změny do kódu. Přispěvatelé jsou vývojáři i uživatelé.

Napište soubor readme v Markdownu místo prostého textu. Markdown usnadňuje formátování textu, zahrnutí obrázků a odkazů podle potřeby na další dokumentaci z readme.

Tady je několik skvělých souborů readme, které používají tento formát a hovoří se všemi třemi cílovými skupinami, pro referenci a inspiraci:

Vytvoření úvodu

Začněte se souborem readme s krátkým vysvětlením popisem projektu. Pokud má váš projekt uživatelské rozhraní, přidejte do svého úvodu snímek obrazovky nebo animovaný obrázek GIF. Pokud váš kód využívá jinou aplikaci nebo knihovnu, nezapomeňte tyto závislosti uvést v úvodu nebo přímo pod ním. Aplikace a nástroje, které běží jenom na konkrétních platformách, by měly mít podporované verze operačního systému uvedené v této části souboru readme.

Pomozte uživatelům začít

Provedou uživatele tím, že si kód zprovozní ve svém vlastním systému v další části souboru readme. Zaměřte se na základní kroky, které vám pomůžou začít s kódem. Propojte požadované verze libovolného požadovaného softwaru, aby se k nim uživatelé mohli snadno dostat. Pokud máte složité kroky nastavení, zdokumentujte je mimo soubor readme a propojte je.

Zjistěte, kde získat nejnovější verzi kódu. Nejlepší je binární instalační program nebo pokyny k používání kódu prostřednictvím nástrojů pro balení. Pokud je váš projekt knihovnou nebo rozhraním rozhraní API, vložte fragment kódu zobrazující základní použití a zobrazte ukázkový výstup kódu v tomto fragmentu kódu.

Poskytnutí kroků sestavení pro vývojáře

V další části souboru readme můžete vývojářům ukázat, jak sestavit kód z čerstvého klonu úložiště a spustit všechny zahrnuté testy. Postupujte následovně:

  • Uveďte podrobnosti o nástrojích potřebných k sestavení kódu a zdokumentujte kroky, které je nakonfigurují tak, aby získaly čisté sestavení.
  • Rozdělte zhuštěné nebo složité pokyny k sestavení na samostatnou stránku v dokumentaci a v případě potřeby na ni odkazujte.
  • Projděte si pokyny, jak je napíšete, abyste ověřili, že pokyny budou fungovat pro nového přispěvatele.

Nezapomeňte, že vývojář, který se spoléhá na tyto pokyny, může být po určitou dobu mimo práci na projektu.

Poskytněte příkazy ke spuštění všech testovacích případů, které jsou součástí zdrojového kódu po úspěšném sestavení. Vývojáři se na tyto testovací případy spoléhají, aby při provádění změn nepřerušili kód. Vhodné testovací případy také slouží jako ukázky, které můžou vývojáři použít k vytvoření vlastních testovacích případů při přidávání nových funkcí.

Pomoc uživatelům při přispívání

Poslední část vašeho souboru readme pomáhá uživatelům a vývojářům zapojit se do hlášení problémů a navrhnout nápady, které váš kód zlepší. Uživatelé by měli být propojeni s kanály, kde můžou otevírat chyby, požadovat funkce nebo získat pomoc s použitím kódu.

Vývojáři potřebují vědět, jaká pravidla musí dodržovat, aby mohli přispívat změnami, jako jsou pravidla kódování/testování a požadavky na žádosti o přijetí změn. Pokud potřebujete souhlas přispěvatele s přijetím žádostí o přijetí změn nebo vynutit pravidla chování komunity, měl by být tento proces propojený nebo zdokumentovaný v této části. Uveďte, jaká licence se kód vydá pod kódem, a odkaz na úplný text licence.