README

Leiðbeiningar um hvað ætti að vera í README.md skrá í GitHub repo.

Inngangur að verkefninu

README.md er fyrsta skráin sem flestir sjá þegar þeir heimsækja GitHub repo. Hún ætti að veita skýra og gagnlega yfirsýn yfir verkefnið og leiðbeina notendum um hvernig á að nota það.

Sérstaða README.md

  • GitHub birtir sjálfkrafa README skrána á forsíðu geymslu.
  • Hægt er að nota annaðhvort README eða README.md, en .md endingin gerir skjalið auðlesanlegra með Markdown uppsetningu.
  • Gott Markdown snið eykur læsileika með fyrirsögnum, listum og kóðakössum.

Grundvallaratriði í README.md

Hér eru lykilatriðin sem ættu að vera í README.md:

1. Heiti og lýsing

  • Nafn verkefnisins – Stuttur titill efst í skjalinu.
  • Lýsing – Hvað gerir verkefnið og hver er tilgangur þess?

Dæmi:

# Gagnavinnslutól
Þetta er einfalt Python forrit sem hreinsar og umbreytir CSV gögn fyrir frekari úrvinnslu.

2. Uppsetning og notkun

Hvernig setja skal upp verkefnið og keyra það. Þetta ætti að innihalda:

  • Kerfiskröfur (t.d. Python 3.10, PostgreSQL, Node.js)
  • Uppsetningarleiðbeiningar (t.d. með pip install eða npm install)
  • Hvernig keyra á verkefnið

Dæmi:

## Uppsetning

### 1. Athugaðu Python-útgáfuna

Athugaðu fyrst hvaða útgáfa af Python er uppsett:

```sh
python --version
```

Verkefnið krefst **Python X.Y eða nýrra**.

> **Windows:** Ef `python` virkar ekki skaltu prófa:
> ```sh
> py --version
> ```

### 2. Klónaðu verkefnið

```sh
git clone https://github.com/owner/repo.git
cd your-repo
```

### 3. Settu upp nauðsynlega pakka

```sh
python -m pip install -r requirements.txt
```

Á Windows, ef þú notar `py`:

```sh
py -m pip install -r requirements.txt
```

Hér er gert ráð fyrir að python pakkarnir sem eru notaður séu útlistaðir í skjali sem kallast requirements.txt, sem lítur t.d. svona út:

requests==2.25.1
pandas==1.3.0

3. Dæmi um notkun

Hvernig á að nota verkefnið með dæmum.

## Notkun

Til að umbreyta CSV gögnum:
```sh
python process_data.py input.csv output.csv
```

4. Framlag frá öðrum

Ef verkefnið er opið fyrir framlag, skráðu:

  • Hvernig notendur geta lagt sitt af mörkum.
  • Hvaða vinnuflæði á að fylgja (t.d. git fork -> branch -> pull request).
## Framlag

Framlög eru velkomin! Vinsamlega fylgdu þessum skrefum:

1. Gerðu fork af geymslunni.
2. Búðu til nýjan branch: `git checkout -b feature-nafn`.
3. Gerðu breytingarnar og skráðu þær: `git commit -m "Lýsing á breytingu"`.
4. Ýttu breytingunum í þitt eigið repo: `git push origin feature-nafn`.
5. Sendu pull request.

5. Leyfi og höfundar

Hvaða leyfi gildir fyrir verkefnið (t.d. MIT, GPL)?

## Leyfi

Þetta verkefni er gefið út undir MIT leyfi – sjá [`LICENSE`](LICENSE) fyrir frekari upplýsingar.

Viðbótaratriði

Fyrir stærri verkefni má bæta við eftirfarandi:

  • Merki og tákn (t.d. CI/CD stöðu, niðurhalsfjölda)
  • Gögn um tengiliðaupplýsingar
  • Tengingar í frekari skjöl, t.d. Wiki eða API docs

Samantekt

Hluti Lýsing
Heiti & lýsing Hvað verkefnið gerir
Uppsetning Hvernig setja skal upp og keyra verkefnið
Notkun Dæmi um hvernig verkefnið er notað
Framlag Leiðbeiningar fyrir þá sem vilja leggja sitt af mörkum
Leyfi Hvaða leyfi verkefnið hefur

Skýr og vel skipulögð README.md skrá hjálpar lesanda að skilja hvað verkefnið gerir, hvernig á að keyra það og hvar helstu skrár eru.