Přechod dokumentace na Git?

Upozornění: Tohle vlákno je hodně staré a informace nemusí být platné pro současné Nette.
David Grudl
Nette Core | 8074
+
0
-

Zvažuju, že bych wiki, která pohání tento web, částečně převedl na Git.

Dřív jsem se tomu bránil, protože zdejší systém byl hotový a plně vyhovující a nemělo smysl se pouštět do zbytečné práce. Stejně tak Git byla záležitost pro pár early adopterů.

Čekají nás dvě důležité novinky: nový portál pro doplňky a rozdělení dokumentace na 2.0.x a 2.1. Což bude vyžadovat nutnost zasáhnout do pár let starého engine. A zdá se mi, že lepší než jej vylepšovat bude ho zredukovat a přenést co nejvíce úloh na Git.

Moje představa je taková, že na straně serveru budou vlastně jen statické stránky, které si vygeneruje na základě zdrojů stažených z Gitu. Z původního engine bych nechal editor, který bych upravil do podoby https://editor.texy.info a sloužil by k editaci obsahu na lokálním počítači. Aby měl člověk náhled nad výsledkem. Myslím, že se tak bude editovat daleko lépe. Nemluvě o cherrypickování úprav mezi verzemi atd.

Samozřejmě se tím zvětšuje vstupní bariéra pro nové zájemce o editaci. Dnes už v tom nevidím problém. Naopak mi myslím, že posílání úprav ve formě push requestů namísto zásahů do živého dokumentu je vhodnější. Pochopitelně stálí editoři by měli právo pushovat přímo.

Co si o tom myslíte?

hrach
Člen | 1834
+
0
-

Vyborne, uzasne! :)

Vojtěch Dobeš
Gold Partner | 1316
+
0
-

Myslím, že je to super :).

Felix
Nette Core | 1180
+
0
-

Libi se mi to. Kazdopadne jsem zvedavej na ten engine wiki. Ten starej bude taky nekde dostupny?

MartinitCZ
Člen | 580
+
0
-

Dle nadpisu jsem se lekl, že se bude jednat o tu hnusnou wiki, ale článek vše vyjasnil.

Jsem pro.

PS: Měl bych zájem, stejně jako @Felix, o zdrojáky. :)

Milo
Nette Core | 1283
+
0
-

Dobrá věc, hlavně ten live náhled. A jak budou řešené překlady? Nedala by se CZ/EN verze držet v jednom dokumentu?

Filip Procházka
Moderator | 4668
+
0
-

Výborně! Super! Nejlepší!

redhead
Člen | 1313
+
0
-

Překlady mě zajímají nejvíce. Aspoň se budou lépe sledovat změny v jaz. mutacích a bude jednodušší na ně reagovat. Bomba!

Honza Marek
Člen | 1664
+
0
-

jistě..

Jan Tvrdík
Nette guru | 2595
+
0
-

+1, pro zájemce doplňuji odkaz na historické čtení.

@David Grudl: Pokud bys potřeboval s něčím pomoci, dej vědět.

David Grudl
Nette Core | 8074
+
0
-

Převaděč na Git je v podstatě hotový. Teď to chce vymyslet, jak nastavit rozdělení do větví vs. adresářů.

Jan Tvrdík
Nette guru | 2595
+
0
-

@David Grudl: Nemohl bys to commity vygenerovat s commit message začínající na název upravovaného souboru? Takže např. commit 572ec028a by neměl commit message „update“, ale „doc.cs/composer: update“?

Doplněno: tohle mi asi funguje

git filter-branch --msg-filter '
	path=$(git show --name-only --oneline $GIT_COMMIT | sed 1d | sed 's/.txt//') &&
	orig=$(cat) &&
	echo "$path: $orig"
'
David Grudl
Nette Core | 8074
+
0
-

Myslíš, že se v té historii bude někdo hrabat? Udělat by to samozřejmě šlo, ale je jasné, že dál to stejně nikdo dělat nebude.

Patrik Votoček
Člen | 2221
+
0
-

proč mají soubory příponu txt a né texy?

Jan Tvrdík
Nette guru | 2595
+
0
-

David Grudl wrote: Myslíš, že se v té historii bude někdo hrabat?

Ano, minimálně já. Když se to commit messages nespraví teď, tak už budou navždy nahovno. Osobně mě totiž víc, než ten text od uživatele, zajímá právě, který soubor se mění.

Udělat by to samozřejmě šlo, ale je jasné, že dál to stejně nikdo dělat nebude.

Myslím, že je reálné, aby to lidi dělali dát. A i kdyby to nedělali, tak přirozeně napíší spíš commit message „updated composer page“ než „update“. Staré zprávy ale byly psány v kontextu, kdy zmiňovat znova název upravované stránky nedávalo smysl.

Nečte se vám to lépe?


Doplněno: koukám, že David při tom importu automaticky spojil změny se stejnou zprávou, s čím jsem nepočítal, takže vznikaly commity jako 2d8d75546. Taky jsem zapomněl, že upload souborů taky způsobí commit, který mění více, než jeden soubor, takže vznikly commity jako e82f12c9ce.

David Grudl
Nette Core | 8074
+
0
-

V tom spojování commitů byl bug, budu to přegenerovávat. Commit message nějak rozšířím.

Každopádně jako největší otázku vidím rozdělení do větví, jelikož větvit se bude jen samotná dokumentace. Asi bych vše nechal v jediném repu, se samostatnou větví pro doc resp. doc09, samostatnou pro addons a samostatnou pro zbytek.

jansfabik
Člen | 193
+
0
-

A u těch ikonek by asi mělo být uvedeno, pod jakou licencí jsou šířeny.

Patrik Votoček
Člen | 2221
+
0
-

David Grudl napsal(a):

Každopádně jako největší otázku vidím rozdělení do větví, jelikož větvit se bude jen samotná dokumentace. Asi bych vše nechal v jediném repu, se samostatnou větví pro doc resp. doc09, samostatnou pro addons a samostatnou pro zbytek.

Pokud se má větvit tak bych asi dal dokumentaci do samostatného repozitáře (ať v tom není zbytečně bordel). A složková struktura by pak reflektovala URL (část za doménou bez přípony).

PS: přitom mě napadlo že pokud uživatel zadá do URL i příponu tak by ho to mohlo přesměrovat na danný soubor na githubu. :-)

Filip Procházka
Moderator | 4668
+
0
-

proč mají soubory příponu txt a né texy?

+1

Pokud se má větvit tak bych asi dal dokumentaci do samostatného repozitáře

vždyť to přeci je, ne?


Každopádně super práce! Je to absolutně super!

Editoval HosipLan (18. 9. 2012 18:36)

David Grudl
Nette Core | 8074
+
0
-

Mít soubory bez přípony je divné a nepraktické, nakonec u všech přiložených obrázků & spol. přípona je. A přípona .txt mi připadala nejmíň divná. Ale samozřejmě to může být i .texy.

Patrik Votoček
Člen | 2221
+
0
-

HosipLan napsal(a):

Pokud se má větvit tak bych asi dal dokumentaci do samostatného repozitáře

vždyť to přeci je, ne?

Já teda nevím ale já tam vidím celý obsah nette.org.

David Grudl napsal(a):

Mít soubory bez přípony je divné a nepraktické

O nepadlo ani slovo… :-)

A přípona .txt mi připadala nejmíň divná. Ale samozřejmě to může být i .texy.

Jde o to že až se třeba někdo rozhodne naučit nějaký editor (např.: Sublime Text 2) Texy! tak to bude moct jednoduše detekovat…

David Grudl
Nette Core | 8074
+
0
-

Rozdělil jsem to do samostatných větví a už bych to viděl jako definitivní stav.

hrach
Člen | 1834
+
0
-

Hm, taky mi prijde udrzovat rozdilny obsah ve vetvich. Ale krok ku predu obrovsky, to jo :)

Patrik Votoček
Člen | 2221
+
0
-

hned to vypadá lépe…

má nějaký hlubší důvod / význam to že ve větvi doc-2.0 je složka documentation.cs a né jenom cs?

nemělo by se repo spíš jmenovat „nette.org“?

a poslední asi nejdůležitější dotaz jak to teď teda bude fungovat (use-case)?

David Grudl
Nette Core | 8074
+
0
-

Git repozitář sice existuje, ale předchod bude vyžadovat ještě dost práce, takže stránky editujte jako dosud. Jen prosím žádné nepřejmenovávejte.

Jan Tvrdík
Nette guru | 2595
+
0
-

@David Grudl: V jakém je to teď stavu? Rád bych přešel s dokumentací na Git před vydáním 2.1. Chceš si to napsat sám nebo ti s tím můžeme nějak pomoct, např. uspořádat hackaton?

Kromě vlastního přechodu na Git mám v hlavně hromadu nápadů, jak ten systém vylepšit i po jiných stránkách, ale do close-source systému neumím poslat pull request :)

Teď pomalu končí studentům zkouškové období, takže je ideální čas přehodit na ně nějakou práci!

Editoval Jan Tvrdík (24. 5. 2013 22:26)

ic
Člen | 430
+
0
-

Zdá se, že je hotovo: https://github.com/nette/docs

Majkl578
Moderator | 1364
+
0
-

Hotovo není úplně. Dokumentace sice již na gitu je a z gitu se generuje, nicméně se automaticky neaktualizje.