Skopiuj ten szablon README w Markdown
To autorski szablon początkowy, a nie działający przykład oprogramowania. Zastąp tekst w nawiasach kwadratowych, sprawdź, czy wskazane pliki istnieją, i usuń niepotrzebne sekcje. Poniższe wiersze instalacji i uruchamiania są komentarzami, aby nie można było przypadkowo wykonać poleceń zastępczych.
# [Nazwa projektu]
[Jedno zdanie: problem, docelowy użytkownik i rezultat.]
## Przykład
[Pokaż niewielkie dane wejściowe i oczekiwany wynik lub dodaj zrzut ekranu.]
## Szybki start
Wymagania: [środowisko/wersja i wymagane usługi].
```sh
# Zastąp sprawdzonym poleceniem instalacji.
# Zastąp najprostszym poleceniem dającym przydatny wynik.
```
Oczekiwany rezultat: [co powinien zobaczyć czytelnik].
## Konfiguracja
[Wymagane ustawienia, bezpieczne przykładowe wartości i miejsce na sekrety.]
## Kiedy używać
- [Konkretny przypadek użycia]
- [Drugi przypadek użycia]
## Ograniczenia
[Nieobsługiwane dane, dojrzałość projektu, wydajność lub ograniczenia platform.]
## Dokumentacja i pomoc
[Link do dokumentacji i wyjaśnienie, gdzie zadawać pytania.]
## Współtworzenie
Zobacz [CONTRIBUTING.md](CONTRIBUTING.md).
Odtwarzalne problemy zgłaszaj w zakładce Issues repozytorium.
## Licencja
Zobacz [LICENSE](LICENSE).Dostosuj przykład do rodzaju repozytorium
W przypadku narzędzia wiersza poleceń pokaż plik wejściowy, polecenie i krótki wynik. Dla biblioteki przedstaw najmniejszy kompletny przykład importu i wywołania, wraz z oczekiwaną wartością zwrotną. Dla aplikacji internetowej pokaż główny przebieg pracy i wyjaśnij, czy dostępne jest demo online, czy instalacja lokalna.
Nie wyjaśniaj API wyłącznie zrzutem ekranu: odbiorca powinien móc skopiować kod. Z kolei w aplikacji wizualnej przydatny jest zrzut z jasnym opisem wykonywanej czynności. Używaj rzeczywistych przykładów z obecnie udostępnianej wersji.
- Biblioteka: instalacja, obsługiwane środowisko i jedno kompletne wywołanie funkcji.
- CLI: dane wejściowe, polecenie, wynik i sposób zgłaszania błędów.
- Aplikacja internetowa: link do demo lub instalacja lokalna, konfiguracja i zrzut głównego zadania.
- Zbiór danych: pochodzenie, format, licencja i niewielki przykładowy rekord.
Sprawdź README przed udostępnieniem
Przetestuj szybki start w czystym środowisku, a nie na maszynie już skonfigurowanej do programowania. Sprawdź, czy potrzebny jest niewymieniony pakiet globalny, prywatny rejestr lub lokalny plik. Jeśli konfiguracja wymaga konta lub płatnej usługi, poinformuj o tym przed pierwszym poleceniem.
Otwórz linki do dokumentacji i obrazów ze strony repozytorium. Upewnij się, że nazwy plików z instrukcją współtworzenia i licencją są poprawne, oraz usuń niedziałające linki. Krótki, rzetelny README jest lepszy niż efektowny szablon pełen niezrealizowanych obietnic.
- Usuń pola zastępcze i niepotwierdzone twierdzenia.
- Nie umieszczaj w przykładach prawdziwych tokenów, haseł ani prywatnych adresów URL.
- Sprawdź, czy oczekiwany wynik odpowiada opublikowanej wersji.
- Wyjaśnij, jakie informacje należy dołączyć do zgłoszenia problemu.
Wykorzystaj README jako podstawę ogłoszenia
Po uzupełnieniu szablonu wyodrębnij krótkie wprowadzenie: jedno zdanie o problemie, jeden przykład wyniku i jeden link do wypróbowania projektu. Będzie to punkt wyjścia do wpisu w społeczności. README pozostaje szczegółowym źródłem informacji, a każde wprowadzenie dostosuj do odbiorców zamiast wszędzie powtarzać ten sam akapit promocyjny.
Częste pytania
Czy to README repozytorium, czy profilu?
Ten szablon dotyczy repozytorium oprogramowania. README profilu przedstawia osobę i wymaga innych sekcji, na przykład o jej pracy i preferowanych sposobach kontaktu.
Czy na początku dodać odznaki z liczbą gwiazdek?
Tylko jeśli pomagają czytelnikowi. Cel projektu i szybki start powinny pozostać dobrze widoczne. Odznaka nie zastępuje wyjaśnienia działania projektu.
Czy mogę użyć tego szablonu w prywatnym projekcie?
Tak. Zastąp publiczne linki pomocy rzeczywistymi kanałami zespołu, wyjaśnij wymagania dostępu i nie umieszczaj danych uwierzytelniających w dokumencie.