Veřejné předmětové projekty

Většina předmětových materiálů je uložena v projektech ve skupině PB071 na fakultním GitLabu. To umožňuje organizátorům jednodušší spolupráci na částech předmětu.

Protože je ale obvykle práce příliš mnoho a lidí i času příliš málo, mohou se v materiálech objevit překlepy, nepřesnosti a chyby. Proto jsou některé projekty ve skupině přístupné po přihlášení všem uživatelům. Zde můžete chyby nahlásit, nebo přímo navrhnout opravu.

Bonusové body

Podle závažnosti nalezené chyby a kvality návrhu opravy mohou být autoři odměněni Kontr Coins nebo tvrdými bonusovými body. Akceptovaný návrh opravy pomocí Merge request bude zcela jistě odměněný alespoň ½ Kontr Coin. Ve výjimečných případech mohou být udělené i tvrdé body.

Za tento bonus lze získat maximálně 3 Kontr Coins za semestr.

Tento dokument popisuje, jak můžete opravu navrhnout.

Veřejné projekty

Všechny veřejné projekty si můžete prohlédnout přímo ve skupině v GitLabu.

  • Webové stránky

    V těchto projektech můžete navrhovat zejména opravy překlepů. Nedoporučujeme navrhovat změnu znění pravidel .

  • Zadání domácích úkolů

    Projekt s kopiemi zdrojových kódů zadání.

  • Code Styles

    Konfigurace stylů pro clang-format, které používá i Kontr pro kontrolu stylu. Zde také naleznete konfiguraci clang-tidy používanou v testech.

    Do tohoto projektu můžete zkusit přihlásit i svůj vlastní styl. Nejdříve si však přečtěte nápovědu.

  • CUT (C Unit Tests)

    Nástroj pro psaní jednotkových testů, který používáme pro semináře i domácí úkoly.

  • Integrated Negligent Technician

    Otravný a drzý autentizační robot pro předmětový Discord server.

  • Spaceship builder

    Nástroj pro sestavení webu z většího počtu Git repozitářů. Používá se pro generování webu předmětu, který se skládá z více než patnácti částí. Většina z nich není přístupná (např. projekty s domácími úkoly).

Postup

Hlášení chyby (Issues)

Pro hlášení chyb nebo návrh na novou funkcionalitu můžete obecně využít Issues.

Výjimky jsou pouze tyto:

  • Domácí úkoly

    Na nejasnosti v zadání se ptejte v Diskusním fóru ISu. Stejně tak tam hlaste chyby v referenční implementaci. To je důležité proto, aby o tom věděli i ostatní studenti.

Konvence pro zadávání Issues:

  • Issue vyplňte ideálně v angličtině.

    Stejně se tomu v praxi pravděpodobně nevyhnete. Pokud však máte s angličtinou problém, nevadí ani čeština nebo slovenština. Jiné jazyky nepoužívejte.

  • Název (Title) by měla být jedna krátká a výstižná věta.

    Na začátku s velkým písmenem a bez tečky na konci. Příklady vizte popis stylu zpráv pro verze (níže).

  • Další informace uveďte v Description.

    Zde uveďte např. ukázky kódu, delší popis, návrh na řešení atd.

    Pokud je problém dostatečně jasný i z názvu, toto pole vyplňovat nemusíte.

  • Hotovo!

    Další informace (Assignee, Reviewer, Labels, …) nastavovat nemusíte, o to se postarají správci projektu.

Návrhy na opravu (Merge request)

V případě překlepů v materiálech nebo zadáních domácích úkolů nám můžete opravu navrhnout přímo pomocí Merge requests.

Nepoužívejte tlačítko Upravit na webu

Všechny stránky předmětu mají na konci stránky tlačítko Upravit. Tato funkcionalita je však dostupná pouze pro členy projektu, ze kterého se stránka vygenerovala (tj. vyučující předmětu).

Předtím, než začnete

  • Nastavte si jméno a e-mail

    Navržené změny musí mít nastavenou položku Author tak, aby bylo jasné, kdo změnu udělal. Nastavte si proto Git tak, jak jste to viděli na prvním cvičení:

    git config --global user.name "Vaše Jméno"
git config --global user.email "login@fi.muni.cz"

    U jména použijte i diakritiku. E-mail nemusí být nutně fakultní, můžete použít i univerzitní nebo osobní.

    Pokud již máte konfiguraci Gitu, kterou nechcete měnit, můžete si nastavit Git pro daný projekt po naklonování se stejnými příkazy bez přepínače --global. Další možností je zavolat git commit --author="Vaše Jméno <email>".

Postup pro vytvoření návrhu změny

  • Vytvořte si kopii projektu

    V předmětové skupině v GitLabu vyberte projekt, pro který chcete navrhnout opravu. Na hlavní stránce projektu pak klikněte na tlačítko  Fork v pravé horní části.

  • Kopii projektu si naklonujte

    Na vlastním počítači proveďte následující příkazy:

    git clone ‹CLONED REPOSITORY URL›
cd ‹REPOSITORY›
git remote add upstream ‹ORIGINAL URL›

    Adresu vašeho repozitáře (‹CLONED URL›) i originálu (‹ORIGINAL URL›) naleznete na stránce projektu pod tlačítkem Clone. Pokud nemáte nastavený SSH klíč, použijte HTTP.

    Pokud již repozitář naklonovaný máte (např. chcete opravit další chybu), pak před každou další úpravou repozitář pro jistotu aktualizujte:

    git pull --rebase upstream ‹DEFAULT BRANCH›
git push

    U starších projektů uveďte místo ‹DEFAULT BRANCH› master, u novějších main. Kterou větev použít, zjistíte například z příkazu git branch.

    SSH klíč

    Pro použití git pull a git push bez nutnosti hesla si nastavte SSH klíč a pak na místě ‹… URL› použijte tu adresu, která začíná git@….

  • Proveďte navrhovanou opravu

    Větší změny se pokuste rozdělit do více logicky souvisejících celků, pro které pak proveďte git commit samostatně. Nezapomeňte před každým git commit zkontrolovat výstup git status! Návrhy, které budou obsahovat dočasné soubory editoru nebo IDE, budete muset před akceptováním opravit.

    Alternativně můžete větší změnu rozdělit pomocí git add --patch.

    Vizte také formát zpráv v git commit níže.

  • Nahrajte změny do GitLabu

    git push

  • Vytvořte Merge request

    Příkaz git push v terminálu by měl rovnou vypsat URL, které vás zavede na stránku s vytvořením Merge request:

    remote: To create a merge request for ‹BRANCH›, visit:
remote:     https://gitlab.fi.muni.cz/‹LOGIN›/‹PROJECT›/merge_requests/new?…

    Alternativně ve vlastní kopii projektu klikněte na levém panelu na Merge requests a pak New merge request.

    Nastavte nebo zkontrolujte následující:

    1. Pokud jste otevřeli URL z výstupu git push, na vrchu stránky ověřte, že vidíte řádek tvaru
      From ‹VÁŠ PROJEKT›/main into pb071/‹PROJEKT›:main.
      Pokud se tyto informace liší, klikněte na Change branches, jinak můžete pokračovat bodem 3.

    2. V nastavení větví vyberte jako Source branch větev, do které jste právě nahráli změny. Jako Target branch vyberte hlavní větev originálního projektu.

    3. Vyplňte Title a volitelně i Description. Dodržte, prosíme, stejné konvence jako pro hlášení (Issues).

    4. Nic jiného nastavovat nemusíte, klikněte na Create merge request.

  • Hotovo!

    Cvičící odpovědní za daný projekt se na změnu podívají. V případě, že naleznou nějaké nedostatky, s vámi dohodnou další postup.

Úpravy ve více větvech

Cvičící předmětu obvykle taky nemohou některé repozitáře upravovat přímo, ale změny navrhují ve vedlejších větvích. Pro zvídavé stručně popíšeme rozdíly oproti postupu výše. Můžete si však taky zkusit vytvořit změnu z jiné větve ve vlastní kopii projektu.

  • Kopie projektu není nutná

    Cvičící si mohou udělat kopii projektu jako v postupu výše, stačí jim však naklonovat hlavní projekt.

  • Vytvoření nové větve

    V lokálním klonu projektu pak vytvoří větev:

    git switch -c ‹BRANCH›

    kde ‹BRANCH› je obvykle odvozeno z extrémně stručného popisu toho, jakou změnu větev obsahuje, např. fix-typo-in-homeworks.

  • Provedení úprav a Merge request jako výše

  • Přepnutí na výchozí větev

    Je doporučeno ihned přepnout větev v klonu repozitáře zpátky na výchozí, aby nedošlo k dalším nežádoucím úpravám v navrhované změně:

    git switch ‹DEFAULT BRANCH›

Konvence projektů PB071

Když se zapojíte do projektu, na kterém pracuje více lidí, je nutné si dohodnout jednotný styl psaní kódu. Pokud si totiž každý zavede do projektu části kódu podle vlastního stylu, časem se zdrojový kód stane nepřehledný a obtížně udržovatelný.

Stejně tak se ve velkých projektech nad Gitem (nebo jinými verzovacími nástroji) zavádí konvence pro popis verzí (angl. Commit guidelines nebo Git guidelines).

Pokud se rozhodnete přispívat do projektů předmětu PB071, dodržte konvence pro zdrojový kód a následující konvence pro zprávy:

Obecné konvence

Shrnutí z postupů výše:

  • Jedna verze (commit) by měla představovat jednu logicky samostatnou změnu.

  • Větev, ze které Merge request provádíte, by měla být aktuální vůči té, kde chcete změnu zavést.

  • Mějte v Gitu nastavené svoje skutečné jméno a e-mail.

Konvence pro popis verzí

Zde jsou popsány konvence pro zprávy v git commit, ale lze je obecně použít i na Title a Description pro Issues nebo Merge requests. Rozdíly viz výše.

  • Zprávy pište pouze anglicky.

    U Issues a Merge requests můžete použít i češtinu nebo slovenštinu, pokud chcete.

  • Zprávu tvoří jediná stručná věta v rozkazovacím tvaru, s velkým prvním písmenem a bez tečky na konci.

    Pomůcka: Zpráva by měla syntakticky pasovat do věty „If this commit is applied, it will …“.

  • Volitelně může zpráva začínat ‹prefix›: pro nějakou logickou část projektu (tzv. Conventional commits).

  • Pokud potřebujete doplnit další informace, vytvořte commit pomocí editoru (tedy bez přepínače -m nebo --message). Za zprávou nechte jeden prázdný řádek a pod něj můžete napsat podrobnější popis verze.

Pokud se bojíte, že něco pokazíte, nezoufejte. Pokud správci projektu naleznou ve vašem návrhu problém, vysvětlí vám postup, jak jej opravit.

Příklady

Ukázky vyhovujících a špatných popisů z git log. Řádek Author: nastavuje Git, nepište jej do zprávy sami.

  • Author: Leonard Login <xlogin@fi.muni.cz>

Fix indentation in template source

    Správně nastavené jméno, stručná a popisná zpráva.

  • Author: Lenka Loginová <xlogin1@mail.muni.cz>

Enhance error handler in protocol implementation

The original error handler does not allow the rest of the module to provide
enough information for the user to debug the problem. The handler introduced
in this commit allows to pass more information, e.g.

* function name
* line
* generic context

Resolves #69

    Složitější ukázka s podrobným popisem.

    Poslední řádek má pro GitLab speciální význam, vizte GitLab closing patterns.

  • Author: xlogin <xlogin@aisa.fi.muni.cz>

Fixed description of function 'main()'.

    Chybí nastavení pro jméno a e-mail.

    Fixed → Fix

    Na konci nemá být tečka.

  • Author: Lenka Loginová <xlogin1@fi.muni.cz>

replace deprecated option '--add' in program synopsis with the new one '--include' that has been implemnted in the latest release

    První písmeno není velké.

    Zpráva je zbytečně dlouhá.

  • Author: Ludomysl Loginický <xlogin2@fi.muni.cz>

Fix bug

    Zpráva má téměř nulovou informační hodnotu.

Reference