Share via

Tworzenie strony README dla repozytorium

  • Artykuł

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Repozytorium Git powinno mieć plik readme, aby osoby przeglądające wiedziały, co robi twój kod i jak mogą zacząć z niego korzystać. Twój readme powinien porozmawiać z następującymi odbiorcami:

  • Użytkownicy, którzy chcą tylko uruchomić kod.
  • Deweloperzy, którzy chcą kompilować i testować kod. Deweloperzy są również użytkownikami.
  • Współautorzy, którzy chcą przesyłać zmiany do kodu. Współautorzy to zarówno deweloperzy, jak i użytkownicy.

Zapisz plik readme w języku Markdown zamiast zwykłego tekstu. Język Markdown ułatwia formatowanie tekstu, dołączanie obrazów i linków zgodnie z potrzebami w celu uzyskania większej dokumentacji z pliku readme.

Oto kilka świetnych readmes, które używają tego formatu i rozmawiają ze wszystkimi trzema odbiorcami, aby uzyskać odwołanie i inspirację:

Tworzenie wprowadzenia

Zacznij od pliku readme z krótkim wyjaśnieniem opisującym projekt. Dodaj zrzut ekranu lub animowany plik GIF w intro, jeśli projekt ma interfejs użytkownika. Jeśli kod opiera się na innej aplikacji lub bibliotece, upewnij się, że te zależności znajdują się w intro lub bezpośrednio poniżej. Aplikacje i narzędzia, które działają tylko na określonych platformach, powinny mieć obsługiwane wersje systemu operacyjnego zanotowany w tej sekcji pliku readme.

Pomoc użytkownikom w rozpoczęciu pracy

Przeprowadzą użytkowników przez proces uruchamiania kodu we własnym systemie w następnej sekcji pliku readme. Bądź na bieżąco z podstawowymi krokami, aby rozpocząć pracę z kodem. Połącz się z wymaganymi wersjami dowolnego oprogramowania wstępnie wymaganego, aby użytkownicy mogli je łatwo uzyskać. Jeśli masz złożone kroki konfiguracji, udokumentuj te spoza pliku readme i połącz się z nimi.

Wskaż, gdzie uzyskać najnowszą wersję kodu. Instalator binarny lub instrukcje dotyczące używania kodu za pomocą narzędzi do tworzenia pakietów są najlepsze. Jeśli projekt jest biblioteką lub interfejsem interfejsu API, umieść fragment kodu przedstawiający podstawowe użycie i pokaż przykładowe dane wyjściowe dla kodu w tym fragmencie kodu.

Podawanie kroków kompilacji dla deweloperów

Użyj następnej sekcji pliku readme, aby pokazać deweloperom, jak skompilować kod z nowego klonu repozytorium i uruchomić wszystkie dołączone testy. Należy wykonać następujące czynności:

  • Podaj szczegółowe informacje o narzędziach potrzebnych do skompilowania kodu i udokumentowaniu kroków konfigurowania ich w celu uzyskania czystej kompilacji.
  • Podziel gęste lub złożone instrukcje kompilacji na oddzielną stronę w dokumentacji i w razie potrzeby połącz się z nią.
  • Wykonaj instrukcje podczas ich pisania, aby sprawdzić, czy instrukcje będą działać dla nowego współautora.

Pamiętaj, że deweloper korzystający z tych instrukcji może być po pewnym czasie nie pracować nad projektem.

Podaj polecenia, aby uruchamiać wszystkie przypadki testowe dostarczone z kodem źródłowym po pomyślnym zakończeniu kompilacji. Deweloperzy opierają się na tych przypadkach testowych, aby upewnić się, że nie przerywają kodu podczas wprowadzania zmian. Dobre przypadki testowe służą również jako przykłady, których deweloperzy mogą używać do tworzenia własnych przypadków testowych podczas dodawania nowych funkcji.

Pomóż użytkownikom współtworzyć

Ostatnia sekcja pliku readme ułatwia użytkownikom i deweloperom zaangażowanie w raportowanie problemów i sugerowanie pomysłów na lepsze tworzenie kodu. Użytkownicy powinni być połączeni z kanałami, w których mogą otwierać usterki, żądać funkcji lub uzyskać pomoc przy użyciu kodu.

Deweloperzy muszą wiedzieć, jakie reguły muszą przestrzegać, aby współtworzyć zmiany, takie jak wytyczne dotyczące kodowania/testowania i wymagania dotyczące żądań ściągnięcia. Jeśli chcesz, aby umowa współautora akceptowała żądania ściągnięcia lub wymusiła kodeks postępowania społeczności, ten proces powinien być połączony z lub udokumentowany w tej sekcji. Podaj licencję, w ramach której został wydany kod, i połącz się z pełnym tekstem licencji.