Dotaz: GitHub organizace projektu

[Jack Hokus]

Ahoj,

mám rozpracovaný pokus o překlad delšího textu z angličtiny. Zatím funguju tak, že mám text na svém webu. Rád bych začal používat systém pro správu verzí. Už dřív jsem si zřídil účet na GitHubu. Mám tam pár textů. Určených k tomu, abych si to trochu osahal. Nicméně, tenhle program umí spoustu věcí a dost se v tom ztrácím.

Rád bych se Vás zeptal, jak použít GitHub pro práci na překladu textu.

Zdroje: Kniha o Gitu

Manuál

---

---

Odpovědi

[Filip Jirsák]

Především, git a github jsou dvě samostatné věci.

Git je nástroj na verzování a můžeš jej používat lokálně. To znamená v pracovním adresáři git init ., potom budeš měnit pracovní soubory, dáš git add soubor, git commit -m"Smysluplný popis provedených změn.". V git log potom přehledně uvidíš, co se v každé změně událo. Takto si můžeš lokálně verzovat libovolnou svou práci.

V předchozím příkladu nám vznikl repositář. Každý git pracovní adresář je repositář. Repositáře můžeš clonovat (git clone) jak na lokálním systému, tak i vzdáleně. Přístup přes ssh funguje out of box. Takže si na svém serveru založíš repositář a clonuješ si jej na lokální stroj pomocí git clone user@server:repo na svůj stroj. Tímto máš současně data na dvou místech. Těchto repositářů je možné mít libovolné množství. Jen je potřeba před každou prací udělat git pull a po každé práci a commitu ještě git push.

A tady se dostávám k githubu. GitHub je prostě jen správce repositářů. Jeden z mnoha. Poskytuje uživateli klikací přístup pro tvorbu vzdálených repositářů. Ale nejdřív je potřeba si projít znalostí práce s lokálními repy a osahat si git jako takový a ne se hned vrhnout na github.

[Filip Jirsák]

Ahoj,
myslím si, že pro tvůj systém použití nemusíš nutně používat více větví, mergovat atd. Začni tak, že budeš prostě jen verzovat.
Pokud máš projekt na githubu, tak začni tak, že si z něj uděláš lokální repo:

git clone https://github.com/tvujlogin/tvujprojekt.git

A následně si do adresáře můžeš nahrát své překlady a začít verzovat a posílat zpět na github:

# vlezeme si do adresáře s projektem
cd tvujprojekt

# naharejeme si do něj překlady (soubory a adresáře)
...

# přidáme nové soubory do gitu
git add .

# provedeme commit do lokální working copy a samozřejmě ke commitu dáme komentář
git commit -m 'nove preklady yxz'

# pushneme změny na github
git push

# push se zeptá na login a heslo do githubu

Github umožňuje ověřování i pomocí klíčů a používání pro přenos ssh, nemusíš využívat tedy login a heslo.

Samozřejmě nemusíš dělat push jen do githubu, ale můžeš posílat své změny do více git repositářů (nebude tvůj usecase, ale jen pro info). Tomu, kam jde push, se říká origin a seznam rep, kam to posíláš, získáš pomocí příkazu :

git remote show origin

* remote origin
  Fetch URL: https://github.com/tvujlogin/tvujprojekt.git
  Push  URL: https://github.com/tvujlogin/tvujprojekt.git
  HEAD branch: master
  Remote branch:
    master tracked
  Local branch configured for 'git pull':
    master merges with remote master
  Local ref configured for 'git push':
    master pushes to master (up to date)

Jinak při každé změně překladu vždy použiješ tyto tři příkazy popsané výše, aby vše bylo v gitu jak u tebe, tak na githubu:

git add .
git commit -m 'poznamka ke commitu'
git push

Zdar Max

[Josef Kufner]

Různé manuály a statické weby se dělají tak, že maš lokální Git repozitář s textem a dalšími materiály, kde pracuješ (git commit). Součástí těchto zdrojových materiálů je i skript (a konfigurační soubor), který sestaví požadovanou webovou prezentaci, PDF, nebo cokoliv chceš. Z tohoto repozitáře to pomocí git push nahraješ do veřejného repozitáře na Githubu, Gitlabu, nebo něčem takovém. Tam se pomocí nějakého CI nástroje (Continuous Integration) spustí v kontejneru ten skript a sestavená prezentace se nahraje na web (jak je napsáno v tom konfiguračním souboru). Je to trochu komplikované na nastavení, ale jakmile to funguje, tak to neskutečně šetří práci.

Na webu pak bývají odkazy na repozitář, kde čtenáři mohou forknout repozitář, udělat úpravy a požádat o jejich začlenění. Pokud se ti nabídnuté změny líbí, zmáčkneš tlačítko "Merge", commity se přidají k těm tvým, CI sestaví aktualizovanou prezentaci a rovnou se to po chvilce samo objeví na webu.

Pokud jsi někdy slyšel o generátorech statických webů, tak přesně takto se používají.

[Heron]

Nic proti CI, ale tohle mi přijde kanón na vrabce. Používám jekyll, stačí si vytvořit Makefile se dvěma řádky (jekyll build, rsync na webserver) a je to. Kdybych chtěl, tak to můžu udělat jako git push hook (ale ne každou změnu chci hned vrážet na veřejný web)

[Josef Kufner]

A když k tomu připíšeš ještě ten párřádkový konfigurační soubor pro CI, tak nemusíš řešit hook ani ručně spouštět make a nehrozí, že na to zapomeneš. CI je od toho, aby to hlídalo za tebe a ty jsi se nemusel starat. Navíc CI už je integrované a připravené univerzální řešení. Na Githubu nebo Gitlabu si beztak ten hook nenastavíš.

Že to je kanón na vrabce ti to přijde jen kvuli tomu, že to má GUI a v pozadí běží služby, které odbavují úlohy. Ve skutečnosti je to velmi štíhlá a jednoduchá věc.

[Heron]

Jasně, jenže to se bavíš o připraveném a centralizovaném řešení (počkej, až sem přijde Franta). Ono nainstalovat a spravovat svůj vlastní GitLab včetně CI workerů zase taková sranda není a taková Gitea vlastní CI vůbec nemá. Takže začátečníkovi bych radil spíše lokální řešení. Navíc nevím, jak github získá přístupové údaje k tomu webserveru, kam to ten worker má potom nahrát. Přece mu je nedáš / ten webserver může mít omezení pouze na tvé IP.

[Josef Kufner]

Lokální řešení budeš mít tak jako tak. Ten skript (ať už makefile nebo shell skript) se musí pripravit bez ohledu na CI, jinak to je utrpení. Typicky takové skripty jsou žádoucí dva – jeden pro sestavení, druhý pro nahrání na server. Do CI se pak napíše spusť jeden a když projde, tak i ten druhý.

Pokud používáš Github, tak pravděpodobně použiješ i další hostované služby na provoz webu, takže přístup se nastaví do proměnných v konfiguraci CI, které nejsou commitnuté do repozitáře. Na serveru pak vyhradíš ten přístup jen pro tu konkrétní věc (tj. jen SFTP či rsync pro konkrétní adresář), což u hostovaných služeb je výchozí stav. Alternativně můžeš nechat připravit balíček a po HTTP říct webu ať se aktualizuje (z pevně definovaného zdroje).

Pokud máš vlastní server a vlastní hosting (VPS nebo domácí server), tak stačí shell runner, který to spustí pod vyhrazeným uživatelem, ale tam zas nechceš spouštět kód od cizích lidí. Na to už je potřeba si vyrobit pomíjivý kontejner.

[Filip Jirsák]

Pokud to má být jen statický web bez vazby na další služby, je nejjednodušší použít GitHub Pages, které jsou rovnou v GitHubu vestavěné. Pokud píše web rovnou v HTML+CSS (tj. není tam žádný překlad), jenom zveřejní repository přes GitHub Pages a má hotovo. Pokud tam je nějaký build proces, stačí říct, že se na GitHub Pages nemá zveřejnit kořenový adresář repository, ale třeba adresář /build. Lokálně pak spustí build, commit a push a web je publikován. Pro složitější web se pak vyplatí řešit build v rámci CI, ale pro začátek to není potřeba.

[jiwopene]

U takovéhle věci je CI zbytečně složité řešení, resp. není jednodušší. Místo řešení (Makefile + hook v Gitu), které běží lokálně a má minimum částí, kde se může rozbít, pak musíte používat software na jiném stroji, který případně výstup posílá dál (např. na webserver). Tím vzniká rovnou několik míst, kde tento systém může selhat a kde můžete udělat chybu. Další problémy mohou nastat, pokud toto řešení přestane vyhovovat – např. GitHub změní podmínky používání a bude Vám bránit v používání této služby, službu zpoplatní, GitHub přestane fungovat (výpadek) a budete potřebovat něco na poslední chvíli změnit – a budete se muset obejít bez jeho služeb.

[Josef Kufner]

Věř tomu, že to je pořád spolehlivější než když tam necháš člověka.

Mezi lokálním buildem a CI je jeden jediný rozdíl: Musíš definovat jak vypadá prostředí pro build.

CI pořád vyžaduje, aby fungoval lokální build. Pořád tam máš ten samý Makefile. Když CI vypadne, spustíš to ručně lokálně, nebo se přesuneš k jinému poskytovateli, převedeš těch pár řádek konfigurace do jiného formátu a v klidu pokračuješ. Ta konfigurace typicky říká "spusť make a pak to uploadni tam a tam".

Hook v lokálním repozitáři sice vypadá na první pohled jednodušeji, ale ve skutečnosti je s tím daleko více problémů. V první řadě se ti hook nepřenese, když si někdo další naklonuje repozitář. Pak také tvůj pracovní adresář není vždy v plně konzistentním stavu a může tam být nějaký bordel, který nechceš zrovna teď smazat ani commitovat, ale přitom ho nechceš v buildu. CI ti stále dává konzistentní výsledky.

Takový hook také nemusí fungovat na jiném systému, než je ten tvůj, kde jsi ho vytvořil. Rozhodně ho nespustíš třeba na telefonu nebo tabletu, když někde daleko od tvého počítače zjistíš, že je potřeba na webu upravit jednu drobnou, ale ošklivou chybu. (Ano, už jsem to dělal.)

CI je celkově složitější. Je tam v pozadí infrastruktura, která není úplně triviální, ale je to vyřešená a odladěná věc. Efektivně to vypadá tak, že na webu zaškrtneš "chci CI" a ono to funguje. Dnes už to je ve stavu, kdy je s tím méně práce, než s tím hookem a je to spolehlivější.

[zdenek2008]

Pokud potrebujes venovat vice casu tomu prekladu nez studiu gitu a mas ho uz nainstalovany, v konzoli zadej git add nazev_souboru a na konkretni ukladani novych verzi si pust git gui. Tam ti bude pro zacatek stacit kliknout na "commit" na konci dne a mas ulozeno. Pozor: git soubory jsou skryte a muzes smazat adresar i s nimi (treba budes ve spechu apod.). Asi bude jistejsi to cele obcas nekam zkopirovat. Online repozitar snad staci nechat na pozdeji, mezitim si rozmyslis jestli ho vubec na svuj projekt potrebujes. Do alternativnich systemu bych se ani nehrnul, at pripadne netravis vzacny cas ve slepych ulickach. Hodne stesti.

[Filip Jirsák]

Naopak. Vzdálený repozitář je výborná záloha. Je tedy vhodné si ho nastavit hned na začátku a ten git push občas udělat.