# Szablon README

Strona podaje szablon pliku `README.md` repozytorium i mówi, jak go wypełniać. Jest dla osób, które zakładają repozytorium albo uzupełniają jego README.

README odpowiada na pytania: co to jest, na czym działa i jak to uruchomić. Opisy wykraczające poza to trafiają do `docs/` repozytorium.

## Zasady wypełniania

| Sekcja | Co zawiera |
| --- | --- |
| tytuł i pierwszy akapit | nazwa repozytorium i jedno zdanie o tym, co robi i dla kogo |
| Stos | tabela z językiem, frameworkiem, wersją runtime, bazą danych i innymi usługami |
| Wymagania | narzędzia z numerami wersji, które trzeba zainstalować przed pracą |
| Uruchomienie | polecenia od klonowania do działającej aplikacji |
| Konfiguracja | zmienne środowiskowe i pliki konfiguracyjne, ze wskazaniem `.env.example` |
| Testy i budowanie | polecenia testów, lintu i budowania artefaktu |
| Dokumentacja | link do witryny repozytorium i odsyłacz do `CONTRIBUTING.md` |

Reguły stylu z [Zasad dokumentacji](<https://docs.logintegra.com/zasady-dokumentacji/index.md>) obowiązują także README. Dotyczy to zwłaszcza polskiego języka, zdania w osobnej linii, kodu w `znakach` i bloków kodu z podanym językiem.

Sekcja bez treści dla danego repozytorium dostaje zdanie "Nie dotyczy.", a nie jest pomijana. Dzięki temu czytelnik wie, że niczego nie brakuje.

Repozytorium techniczne, którego nikt nie uruchamia ani nie rozwija, MOŻE nie mieć README. Obecnie wyjątkiem jest `apollo/ci-test`.

## Szablon

````
# <nazwa-repozytorium>

<Jedno zdanie: co robi repozytorium i dla kogo.>

## Stos

| Element | Wartość |
|---|---|
| Język | <Kotlin 1.9> |
| Framework | <Spring Boot 3> |
| Runtime | <JDK 17> |
| Baza danych | <PostgreSQL 15> |
| Usługi zewnętrzne | <RabbitMQ, Redis> |

## Wymagania

- <narzędzie i wersja>

## Uruchomienie

```bash
git clone git@bitbucket.org:logintegraspzoo/<nazwa-repozytorium>.git
cd <nazwa-repozytorium>
<polecenie uruchamiające>
```

Po uruchomieniu aplikacja odpowiada pod adresem `<adres>`.

## Konfiguracja

| Zmienna | Znaczenie | Domyślnie |
|---|---|---|
| `<NAZWA>` | <opis> | `<wartość>` |

Wzór pliku ze zmiennymi: `.env.example`.

## Testy i budowanie

```bash
<polecenie testów>
<polecenie lintu>
<polecenie budowania>
```

## Dokumentacja

Dokumentacja tego repozytorium: <link do witryny w dokumentacji workspace'u>.
Zasady pracy nad kodem opisuje [CONTRIBUTING.md](CONTRIBUTING.md).
````

## Kolejność wypełniania

1. Skopiować szablon do korzenia repozytorium.
2. Zastąpić każdy symbol `<...>` prawdziwą wartością.
3. Uruchomić polecenia z sekcji "Uruchomienie" i "Testy i budowanie" na czystym klonie.
4. Usunąć z README treść, którą przenosi się do `docs/`, i zostawić na jej miejscu link.
