Readme pro váš projekt
--
Souboru README.md si možná někdo z vás již stihl všimnout ať už v článku o Gitu nebo při průzkumu práce s repozitáři. Například v Githubu je možnost tento soubor přidat k repozitáři při jeho zakládání. Ovšem ne každý ho pro své soukromé, cvičné a menší projekty využívá. A přitom se jedná o zajímavý a užitečný soubor.
README soubor aneb příručka ke každému projektu
Doslovně by se název souboru dal přeložit jako „Přečti mě“. Pojmenování souboru je specifické, využívá verzálky neboli velká písmena abecedy a jednotný název „README“. Koncovky souboru mohou být i jiné, než .md ale jedná se o preferovanou a nejhojněji používanou variantu textového formátu. Zkratka .md je pak odvozena ze slov „MarkDown“ a jedná se o syntax používanou k jeho psaní. Další koncovky — textové formáty mohou být například .txt (text bez formátování) a existují i další, ale mají svá specifika co se formátování týče, zatímco Markdown umožňuje různé způsoby formátování textu, .txt nikoliv a jedná se tak o obyčejný text.
Když se generuje HTML část projektu, soubor README má přednost a sám je převeden do HTML formátu. Je to také část, která se vygeneruje v repozitáři, tak aby ji každý mohl vidět a přečíst, jakmile si repozitář například v Githubu otevře. Najdeme jej hned pod složkami/soubory repozitáře.
Bývá zpravidla uložen v hlavním adresáři, tzv. root adresáři. To znamená, že by neměl být zanořený v žádné druhotné složce. Také by měl existovat pouze jeden v rámci repozitáře. Jednotlivé repozitáře jej tedy obsahovat mohou, ale nemusí.
A co by měl obsahovat ?
Především informace o projektu nebo programu samotném, k čemu slouží, jak funguje, jak si jej lokálně u sebe v počítači spustit, jaké technologie jsou v něm použity a někdy také pokyny pro případně zájemce o podílení se na jeho vývoji. Užitečné informace o pojmenovávání souborů, složek, obrázků tzv. “naming convention” a jiné.
Někdy obsahuje i pokyny přímo k psaní kódu, to platí obzvláště na větších projektech, kde přispívá více autorů a je potřeba udržet jistý standard a formu v psaní kódu pro přehlednost, úpravy, opravy atd.
Velmi nápomocný je i pro nováčky, kteří nemají dostatečnou znalost specifik projektu. Pokud například nastoupíte do nové práce a narazíte na nové repozitáře, se kterými budete potřebovat pracovat, je vhodné a žádoucí se nejdříve podívat právě na tento soubor a pečlivě si ho projít a postupovat podle něj.
Také je doporučeno pravidelně README aktualizovat, nově příchozím pak nevznikne nepříjemnost v podobě nefunkčních postupů k instalaci, nastavení a spuštění aplikace.
README pro váš projekt
Popřemýšlejte o svém projektu. Je potřeba ho přiblížit ostatním lidem, kteří vaši práci uvidí poprvé. Může to být klidně někdo na pohovoru nebo ještě před pozvánkou na pohovor.
Váš popis pomůže k pochopení vaší motivace, proč váš program/projekt vznikl, kam směřuje, co je jeho účel, můžete zde připsat i další autory, kteří s vámi na projektu stabilně spolupracovali a přispěli ať už z hlediska psaní kódu nebo tvorby designu.
Pokud je nutné nejdříve nainstalovat různé externí závislosti nezapomeňte je uvést a to i jejich verze, které jsou v projektu využity nebo je prolinkujte. Popište postup, jak aplikaci následně spustit lokálně.
Pokud jste využili více specifických technologií (různé programovací jazyky na frontendu, backendu), framework, specifický druh databáze nebo externí aplikace pro správu dat, uveďte je zde také.
Praktické cvičení
Zkuste si cvičně ve svém repozitáři soubor přidat, stačí v hlavní adresáři projektu vytvořit soubor a pojmenovat přesně: REAME.md a uložit ho zatím prázdný.
Pro psaní README lze použít jak zápis HTML, tak i často preferovanou Markdown syntaxi (pozor na formát souboru, HTML tagy a markdown spolehlivě funguje v souboru s koncovkou .md, nikoliv v .txt) .
Vyzkoušet můžete například markdown cheatsheet. Psaní pomocí markdown syntaxe je jednoduché. Například pro nadpis stačí před text přidat znak #. Vytvoříte si tak základní strukturu s informacemi o projektu během pár minut.
Jakmile budete mít základ souboru zpracovaný, můžete zapátrat ve svém IDE, zda má nativní rozšíření pro zobrazení výsledného vzhledu. Například VS Code umožňuje otevřít náhled výsledného README přímo vedle souboru.
Jednoduchá tvorba README online
Pokud byste chtěli vaše Readme ještě více doladit a pozvednout na další úroveň, existují online nástroje, které vám pomohou soubor vygenerovat téměř bez práce a dohledávání správných značek.
Nejznámější online nástroje pro generování README:
A jedna třešnička na závěr v podobě open source generátoru README s různými widgety a dalšími vychytávkami. Nejspíš jej pro svůj projekt nevyužijete, slouží spíše k inspiraci. Výsledný soubor je zajímavý a najdete v něm různé a validní způsoby zápisu a formátování.
Obsah README souboru se odvíjí od významu, množství použitých technologií,velikosti a komplexity repozitáře/projektu. U menšího projektu bude vždy stačit základní souhrn informací a pokynů k jeho spuštění. U komplexnějších aplikací může být zápis všech informací někdy i delší než na 100 řádků.
Věříme, že odteď pro vás README soubory již nebudou nenápadné a nezajímavé soubory, ale spíše způsob, jak srozumitelně a zajímavě předat informace o vašich aplikacích komukoliv, kdo chce o vaší práci vědět více.
Těšíme se příště.
ReactGirls
Autorka článku: Martina Piekná
