Wypełnij krótki formularz i dostań schludny README.md z krokami instalacji, użyciem, konfiguracją i licencją albo CHANGELOG.md w formacie Keep a Changelog. Zobacz wynik podczas pisania. Wszystko powstaje w Twojej przeglądarce i nic, co wpiszesz, nie jest przesyłane. Jest darmowe.
Jak zrobić README, krok po kroku
- Wybierz README.md u góry.
- W sekcji O projekcie wpisz Nazwę projektu, Podsumowanie w jednym zdaniu, Opis oraz Funkcje i Wymagania, po jednym w wierszu.
- W sekcji Instalacja i użycie wybierz Menedżer pakietów, taki jak npm, pip lub Cargo, dodaj URL repozytorium i napisz Użycie. Wybierz Język użycia, aby kod był poprawnie sformatowany.
- Dodaj polecenia Ustawień i Programowania, jeśli dotyczą.
- Wybierz Licencję i Właściciela praw autorskich i w razie potrzeby włącz Spis treści, Odznakę licencji lub sekcję Współtworzenie.
- Naciśnij Kopiuj Markdown lub Pobierz README.md.
Co sprawia, że README jest dobre
Powiedz, co projekt robi, w jednym wierszu, a potem pokaż, jak go zainstalować, i najmniejszy działający przykład. Czytelnicy decydują w kilka sekund, czy projekt im pasuje, więc dalej idą funkcje i wymagania, potem ustawienia, polecenia deweloperskie, jak współtworzyć i licencja. Sekcje, które zostawisz puste, są pomijane.
Changelogi, które ludzie mogą czytać
Changelog podąża za Keep a Changelog: najnowsze wydanie pierwsze, każde z datą i zmianami pogrupowanymi jako Dodano, Zmieniono, Wycofano, Usunięto, Naprawiono i Bezpieczeństwo. Trzymaj sekcję Unreleased na górze dla zmian, które jeszcze nie wyszły. Z adresem repozytorium każda wersja linkuje do porównania z poprzednią. Możesz dodać starsze wydanie ręcznie albo zbudować wpisy z komunikatów commitów.
Wskazówki
- Umieść działające polecenie instalacji i krótki przykład użycia blisko góry.
- Nazwij licencję wyraźnie, aby inni wiedzieli, jak mogą używać Twojego kodu.
- Opis niech mówi o tym, co projekt robi dla czytelnika, a nie jak go zbudowałeś.
- Aktualizuj changelog przy każdym wydaniu, a nie tylko na końcu.
Aby trzymać sekrety i pliki budowania poza repozytorium, użyj generatora gitignore i generatora pliku env example.
Pytania
Czy mogę zacząć od historii commitów?
Tak. Wklej wynik git log --oneline w sekcji Z komunikatów commitów. Commity zapisane jako feat:, fix:, perf: i tak dalej są sortowane do właściwych grup, a zmiany łamiące oznaczone wykrzyknikiem są opisane. Potem edytuj brzmienie; komunikaty commitów pisze się dla programistów, a changelogi dla użytkowników.
Czy dodaje tekst licencji?
Dodaje sekcję Licencja, która podaje nazwę licencji i wskazuje na plik LICENSE. Umieść pełny tekst licencji w tym pliku; znajdziesz go na oficjalnej stronie licencji.
Gdzie umieścić pliki?
Pobierz zapisuje README.md lub CHANGELOG.md na Twoim urządzeniu. Umieść plik na najwyższym poziomie repozytorium, a hostingi kodu pokażą go na stronie projektu.
Jakie licencje mogę wybrać?
MIT, Apache 2.0, GPL 3.0, BSD 3-Clause, ISC, MPL 2.0, Unlicense lub Wszelkie prawa zastrzeżone, albo pomiń sekcję.