Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować się zalogować lub zmienić katalog.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022
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 plik readme powinien odnosić się do następujących odbiorców:
- 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 oraz linków do dodatkowej dokumentacji dostępnej w pliku readme.
Oto kilka świetnych „readmes”, które używają tego formatu i przemawiają do wszystkich trzech grup odbiorców, jako odniesienie i źródło inspiracji.
Wymagania wstępne
| Kategoria | Requirements |
|---|---|
| Dostęp do projektu | Członek projektu. |
| Uprawnienia | — Wyświetlanie kodu w projektach prywatnych: co najmniej dostęp podstawowy . — Klonowanie lub współtworzenie kodu w projektach prywatnych: członek grupy zabezpieczeń Współautorzy lub odpowiednie uprawnienia w projekcie. — Ustaw uprawnienia gałęzi lub repozytorium: Zarządzaj uprawnieniami dla gałęzi lub repozytorium. - Zmień gałąź domyślną: Edytuj uprawnienia zasad dla repozytorium. — Zaimportuj repozytorium: członek grupy zabezpieczeń Administratorzy projektu lub ustawienie uprawnienia Git Tworzenie repozytorium na Zezwalaj. Aby uzyskać więcej informacji, zobacz Ustawianie uprawnień repozytorium Git. |
| Services | Włączone repozytoria. |
| Narzędzia | Opcjonalny. Użyj poleceń az repos z Azure DevOps CLI. |
Uwaga / Notatka
W projektach publicznych użytkownicy z dostępem uczestników projektu mają pełny dostęp do usługi Azure Repos, w tym do wyświetlania, klonowania i współtworzenia kodu.
| Kategoria | Requirements |
|---|---|
| Dostęp do projektu | Członek projektu. |
| Uprawnienia | - Wyświetl kod: co najmniej dostęp podstawowy . — Możesz klonować lub współtworzyć kod, będąc członkiem grupy zabezpieczeń Contributors lub mając odpowiednie uprawnienia w projekcie. |
| Services | Włączone repozytoria. |
Stwórz wprowadzenie
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
Poprowadź użytkowników przez proces uruchamiania twojego kodu we własnym systemie w następnej sekcji pliku readme. Bądź na bieżąco z podstawowymi krokami, aby rozpocząć pracę z kodem. Udostępnij linki do wymaganych wersji wstępnego oprogramowania, aby użytkownicy mogli łatwo z nich korzystać. Jeśli masz złożone kroki konfiguracji, udokumentuj je poza dokumentem README i utwórz odnośnik do nich.
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żesz być ty sam, jeśli przez jakiś czas nie pracowałeś 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ą zgłaszać błędy, prosić o funkcje 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 wymagane jest podpisanie umowy współautorskiej w celu akceptowania żądań dodania lub egzekwowania kodeksu postępowania społeczności, ten proces powinien być połączony z dokumentacją w tej sekcji. Podaj licencję, w ramach której został wydany kod, i zamieść link do pełnego tekstu licencji.