Udělejte svůj první PR (pull request - žádost o změnu)

Tento popis je pouze pro editaci anglické dokumentace. All new information must be added in English first. Pokud chcete přeložit wiki do jiných jazyků (děkujeme), použijte prosím crowdin.

For hints how to format text (headline, bold...) and set links please see the “code syntax” section of this page.

Obecné

For any questions, feedback or new ideas you can contact the documentation team via gitter. Vytvoření PR není obtížné, ale můžeme vám pomoci editovat dokumentaci.

V určitém okamžiku bude doporučeno, abyste udělali PR. PR je zkratka pro pull request a je to způsob, jak přidat nebo editovat informace uložené v GitHubu. Ve skutečnosti není příliš těžké udělat takový krok a je to skvělý způsob, jak přispět. Tato dokumentace je zde proto, že lidé, jako jste vy, udělali svůj PR. Nebojte se, že uděláte chybu nebo nějak editujete špatné dokumenty. Před sloučením změn do „formálního“ repositáře dokumentace AndroidAPS je zde vždy proces přezkumu. Nějakou chybou nemůžete originál poškodit. Obecný proces je:

  • Edituje a vylepšuje kód nebo dokumentaci editací stávajícího obsahu.
  • Zkontrolujte, že vaše úpravy vypadají dobře.
  • Udělejte několik poznámek o tom, co je změněno, aby lidé mohli porozumět editacím.
  • Vytvořte PR, která žádá správce, aby se tyto změny použily.
  • Ten provede přezkum a buď (1) sloučí vaše změny, (2) přidá komentář k vašim změnám, nebo (3) založí nový dokument s vašimi změnami.

(Side note: If you are a visual learner, there is a YouTube video here showing the PR workflow.)

Například: chystáme se upravit AndroidAPSdocs. To není nutné dělat v linuxovém prostředí. To lze udělat na jakémkoli Windows PC, Mac atd. (libovolném počítači s připojením k internetu).

  1. Jděte na https://github.com/openaps/AndroidAPSdocs a kliněte na Fork v horním rohu, abyste si vytvořili vlastní kopii repozitáře.

Klonování repozitoře

  1. Jděte na http://androidaps.readthedocs.io/en/latest/Getting-Started/Safety-first.html nebo podobné a přejděte na stránku, kterou chcete editovat. Klikněte na černou oblast dole na stránce se zeleným slovem “v: latest” nebo podobné. In the pop up window that appears, click the word “edit” for editing in GitHub.

edit doc

 Or you can click on the "Edit in Github" link in the upper right corner, and then click the pencil icon that appears in the top bar of the page contents to be edited.

RTD io

  1. Libovolnou možností v kroku 2 vytvoříte nový branch ve svém repozitáři, kde budou uloženy vaše změny. Udělejte své úpravy do souboru.

Be aware that we use different file extensions: .rst (ReStructuredText) and .md (Markdown) and the syntax varies a little bit between the two. Take care to use the correct syntax as described below.

Upravit větev

  1. Pracujete v záložce “<>Edit file”. Vyberte záložku “Preview changes” pro nový náhled, abyste zjistili, že vše, co jste změnili, je to, co jste chtěli. Pokud vidíte, že je potřeba další zlepšení, vraťte se zpět na záložku editace a pokračujte.

režim náhledu

  1. Když jste dokončili své úpravy, přesuňte se do dolní části stránky. V obdélníku dole napište komentář do textového pole “Add an optional extended description...”. Výchozí název má jméno souboru. Zkuste přidat větu s vysvětlením důvodu změny. Pomůže to při kontrole, o jakou změnu se pokoušíte.

potvrdit komentáře

  1. Klikněte na zelené tlačítko “Propose file changes” nebo “Commit changes”. Na stránce se pak objeví tlačítko “Create Pull Request” a znovu na další stránce klepněte na tlačítko “Create Pull Request”.

vytvořit žádost o přijetí změn

  1. Tím dokončíte žádost PR. GitHub přiděluje PR číslo, které se nachází za názvem a hashovou značkou. Vraťte se na tuto stránku, abyste zkontrolovali zpětnou vazbu (nebo pokud došla notifikace e-mailem). Žádost o změnu bude nyní na seznamu PR, který bude tým přezkoumávat a případně poskytne zpětnou vazbu před tím, než začlení změnu do hlavní dokumentace pro AndroidAPS! Pokud chcete zkontrolovat pokrok ve zpracování PR, můžete kliknout na symbol zvonku v horním pravém rohu svého účtu na GitHub a uvidíte všechny své PR.

Sledování PR

PS: Your fork and branch will still be sitting on your own personal GitHub account. Po oznámení, že Váš PR byl sloučený, můžete odstranit branch, pokud do něj nechcete dělat další změny (V kroku 8 bude odkaz na odstranění branche, jakmile bude PR uzavřen nebo sloučen). Pro budoucí úpravy, pokud budete následovat tento postup, budou změny vždy začínat aktualizovanou verzí repozitáře AndroidAPSdocs. Pokud se rozhodnete použít jinou metodu pro vytvoření PR žádosti (např. editace začínající z vaší kopie repozitáře), budete muset zajistit, aby Váš repozitář byl aktuální, a to nejprve provedením “Compare” a sloučením všech aktualizací, které se udály od doby, kdy jste naposledy aktualizovali svůj repozitář. Protože lidé často zapomínají aktualizovat svůj repozitář, doporučujeme použít pro PR proces popsaný výše, dokud se neseznámíte s detaily fungování “Compare”.

Code syntax

At the moment there are two languages used for docs pages:

  • Markdown (.md) - the markup language originally used for docs pages
  • reStructuredText (.rst) - the new markup language

We will change all docs pages from Markdown to reStructuredText bit by bit. In the meantime it is important that you use the correct syntax when formatting text or linking. If you are not sure just have a look at format / link codes on existing pages.

Image size

If using images please use reasonable sizes. Screenshot images should be 250 pixels wide.

.md files

Text format

  • bold: **text**
  • italic: *text*
  • Headline 1: # headline
  • Headline 2: ## headline
  • Headline 3: ### headline

Images

  • images: ![alt text](../images/file.png)

.rst files

Text format

  • bold: **text**

  • italic: *text*

  • Headline 1:

    headline*****

  • Headline 2:

    headline=====

  • Headline 3:

    headline-----

Images

  • images:

    .. image:: ../images/modules.png:alt: alt text

Adding multiple images to documentation

Pokud plánujete provést mnoho editací včetně přidání obrázků, které by pomohly vylepšit části dokumentace (děkujeme Vám!), můžete použít následující postup:

  • Postupně uložte screenshoty, přejmenujte je na popisný název - ale nepoužívejte mezery, protože to GitHub mate. Naopak používejte podtržítka. Jako např. Example_batch_images_upload.png místo “Example batch images upload.png”.

  • Please use reasonable sizes. Screenshot images should be 250 pixels wide.

  • Můžete snadno nahrát obrázky v dávkách:

    1. Přejděte do složky obrázků (https: //github.com/openaps/AndroidAPSdocs/tree/master/docs/EN/images -ale ujistěte se, že jste ve vašem forku/kopii složky Images, abyste mohli tuto akci provést (nahraďte “openaps” v URL svým jménem na Github)).
    2. Klepněte na pravý horní roh, kde se nachází “Upload files”
    3. Přetáhěte snímky na obrazovku pomocí myši
    4. Potvrďte (Commit) tyto informace
    5. Nyní můžete vyhledat adresu URL a relativní cestu ke každému souboru a použít je při přidávání obrázků do stránky v dokumentaci.
    6. Chcete-li zobrazit příklady, jak přidat obrázky, můžete se podívat na “zdrojový” kód stránky a podívat se na příklad ze stránky, která již má obrázky vložené úspěšně. Make sure you use the correct code for the page type you are on (.md or .rst). The main thing is to have a plain text description, followed by a link with a relative path to the image, like this:
    • For .md pages: ![Example of uploading images in batches](../images/Example_batch_images_upload.png) (That code is exactly how the image below is embedded to be displayed.)
    • For .rst pages: .. image:: ../images/Example_batch_images_upload.png:alt: Example of uploading images in batches

Příklad přenosu obrázků v dávkách

  1. Po přidání obrázků nebo provedení úprav můžete odeslat PR (Pull request) do hlavní větve AndroidAPSdocs.