ebSkola

1. tēma / 1.5

1.5 Dokumentēšana, README un Licences

Stundas uzdevums: Izvēlēties un pievienot atvērtā pirmkoda licenci savai krātuvei, pielietot Markdown valodu un sastādīt profesionālu projekta aprakstu (README).

2.4.6. Plāno un dokumentē programmatūras izstrādes procesu. 2.4.8. Dokumentē kodu un ievero koda noformēšanas vadlīnijas.

70 min plāns: Teorija un paraugs (~10 min) · 1. uzdevums (~15 min) - pievieno MIT licenci · 2. uzdevums (~25 min) - uzraksti README ar Markdown · 3. uzdevums (~20 min) - pārbaudi, kā README izskatās GitHub, un salabo formatējumu. Papildu uzdevumu sāc tikai tad, ja pārējie trīs ir gatavi.

Pirms sāc: atver savu krātuvi gan pārlūkā, gan VS Code - licenci ērtāk pievienot pārlūkā, bet README rakstīsi datorā.

Teorija: Koda tiesības un Dokumentācija

Kad tu publicē kodu internetā (pat publiskā GitHub krātuvē), citi cilvēki to drīkst tikai lasīt. Lai citi drīkstētu tavu kodu izmantot, pārveidot vai dalīties ar to, tev ir jāpievieno Licence.

  • Bez licences: Kods ir pilnībā aizsargāts ar autortiesībām (Exclusive Copyright). Neviens cits to nedrīkst kopēt vai izmantot savos projektos.
  • MIT Licence: Vispopulārākā atvērtā pirmkoda licence. Ļauj citiem darīt ar tavu kodu jebko (arī pārdot), ja vien viņi norāda tevi kā sākotnējo autoru.
  • GPL (GNU General Public) Licence: Ļauj citiem izmantot tavu kodu, bet ar stingru nosacījumu - jebkurš jauns projekts, kas izmanto tavu kodu, arī ir jāpublicē kā atvērtais pirmkods.
  • README.md: Projekta "seja". Fails, kas automātiski parādās tavas GitHub krātuves sākumlapā. Faila paplašinājums .md nozīmē Markdown - vieglu teksta formatēšanas valodu.

Praktiskie uzdevumi

1. uzdevums -

Pievieno MIT licenci

Beigās citi drīkstēs likumīgi izmantot tavu kodu, ja norādīs tevi kā autoru.

  1. Atver savu krātuvi pārlūkā un nospied Add file -> Create new file.
  2. Ieraksti faila nosaukumu LICENSE bez paplašinājuma.
  3. Nospied pogu Choose a license template, kas parādās labajā pusē.
  4. Izvēlies sarakstā MIT License.
  5. Ieraksti gadu un savu vārdu norādītajos laukos.
  6. Nospied Review and submit un pēc tam Commit changes.

Gatavs, kad: krātuves sākumlapā blakus nosaukumam parādās uzraksts MIT license.

2. uzdevums -

Uzraksti README ar Markdown

Beigās tava krātuves sākumlapa izskatīsies kā īsts projekta apraksts.

  1. Atver failu README.md VS Code.
  2. Izdzēs veco saturu un ieraksti virsrakstu ar vienu režģi: # Programmēšana - pamatkurss.
  3. Pievieno rindu Autors: **Vārds Uzvārds** ar savu vārdu.
  4. Pievieno apakšvirsrakstu ar diviem režģiem: ## Kā palaist.
  5. Uzskaiti zem tā ar domuzīmēm divus soļus, kā palaist tavu programmu.
  6. Pievieno apakšvirsrakstu ## Licence un vienu teikumu par MIT.
  7. Saglabā failu un veic commit ar ziņu Papildina README.

Gatavs, kad: failā ir vismaz viens # virsraksts, viens ## apakšvirsraksts un saraksts ar domuzīmēm.

3. uzdevums -

Pārbaudi, kā README izskatās GitHub, un salabo formatējumu

Beigās tu redzēsi atšķirību starp Markdown pierakstu un to, ko redz lasītājs.

  1. Nospied Push origin un atver savu krātuvi pārlūkā.
  2. Salīdzini, kā izskatās virsraksts lapā un kā tas rakstīts failā.
  3. Atrodi vietu, kur formatējums nesanāca, piemēram, saraksts palika vienā rindā.
  4. Salabo to: pirms saraksta jābūt tukšai rindai, bet aiz domuzīmes - atstarpei.
  5. Pievieno vienu vārdu treknrakstā ar diviem zvaigznīšu pāriem.
  6. Veic commit un push un pārbaudi rezultātu vēlreiz.
  7. Pieraksti vienu secinājumu: kāpēc .md fails nav parasts teksta fails.

Gatavs, kad: GitHub lapā virsraksts ir liels, saraksts ir ar punktiem un treknraksts tiešām ir trekns.

Papildu uzdevums - Salīdzini MIT un GPL

Ja pamatdarbs ir gatavs, noskaidro, ar ko abas licences atšķiras.

  1. Atver lapu choosealicense.com.
  2. Izlasi MIT licences aprakstu un pieraksti vienu tās prasību.
  3. Izlasi GPL licences aprakstu un pieraksti vienu tās prasību.
  4. Pievieno README failā sadaļu ## Kāpēc MIT.
  5. Uzraksti tajā divus teikumus, kāpēc izvēlējies tieši šo licenci.

Gatavs, kad: README ir tavs skaidrojums, kurā minēta vismaz viena atšķirība starp MIT un GPL.

Biežākās kļūdas (un kā tās labot):

  • Licence nesaglabājas: Ja GitHub mājaslapā failu nenosauksi precīzi par LICENSE (ar lielajiem burtiem), sistēma nepiedāvās "Choose a license template" pogu.
  • Konflikti (Merge Conflicts): Ja izmainīsi README.md GitHub mājaslapā un vienlaicīgi izmainīsi to pašu failu savā datorā (VS Code), mēģinot sinhronizēt radīsies konflikts. Risinājums: Vienmēr taisi Fetch origin pirms sāc strādāt!
  • Markdown virsraksti nestrādā: Starp tēmturi # un pašu tekstu OBLIGĀTI jāatstāj atstarpe. (#Virsraksts = parasts teksts, # Virsraksts = liels virsraksts).

Koda piemērs: README faila izejkods

# Mans Superīgais Projekts

Šī ir programma, kas atrisina visas pasaules problēmas.

## Kā to lietot?
Vienkārši palaid `main.py` failu savā terminālī. Tas izskatās šādi:
```python
print("Projekts darbojas!")
Noteikumi
Projektam ir MIT Licence, kas nozīmē, ka vari to izmantot brīvi! Vairāk lasi failā LICENSE.
Izmantojot backticks (`), tekstā var integrēt kodu (Inline code), bet ar trim backticks (```) var izveidot veselus koda blokus, ko GitHub iekrāsos atbilstoši valodai.