Jak przesyłać pull requesty

Aby wprowadzić zmiany w zawartości, prześlij pull request ze swojego forka. Zanim można scalić żądanie ściągnięcia, musi ono zostać przejrzane. Aby uzyskać najlepsze wyniki, zapoznaj się z listą kontrolną redakcyjną przed przesłaniem pull request.

Korzystanie z gałęzi usługi Git

Domyślną gałęzią dla PowerShell-Docs jest gałąź main. Zmiany wprowadzone w gałęziach roboczych są scalane do gałęzi main przed ich opublikowaniem. Gałąź main jest scalona z gałęzią live każdego dnia tygodnia o godzinie 15:00 (czas pacyficzny). Gałąź live zawiera zawartość opublikowaną w pliku learn.microsoft.com.

Przed rozpoczęciem wprowadzania zmian utwórz gałąź roboczą w lokalnej kopii repozytorium PowerShell-Docs. Podczas pracy lokalnie przed utworzeniem gałęzi roboczej pamiętaj o zsynchronizowaniu repozytorium lokalnego. Gałąź robocza powinna zostać utworzona z kopii main gałęzi z datą up-to.

Wszystkie żądania pobrania powinny być kierowane do main gałęzi. Nie przesyłaj zmian do branchu live. Zmiany wprowadzone w gałęzi main są scalane z live, zastępując wszelkie zmiany wprowadzone w live.

Ulepsz działanie pull requestu dla wszystkich

Im bardziej uprościsz i skoncentrujesz swoje żądanie ściągnięcia, tym szybciej można je przejrzeć i połączyć.

Unikaj żądań ściągnięcia, które aktualizują dużą liczbę plików lub zawierają niepowiązane zmiany

Unikaj tworzenia pull requestów, które zawierają niepowiązane zmiany. Oddziel drobne aktualizacje istniejących artykułów od nowych artykułów lub głównych przeredagowań. Pracuj nad tymi zmianami w oddzielnych gałęziach roboczych.

Zbiorcze zmiany tworzą żądania ściągnięcia z dużą liczbą zmienionych plików. Ogranicz PR do maksymalnie 50 zmienionych plików. Duże prośby o wciągnięcie są trudne do przejrzenia i są bardziej podatne na błędy.

Zmiana nazwy lub usuwanie plików

Podczas zmiany nazwy lub usuwania plików powinien być problem związany z pull requestem. Należy omówić tę kwestię związaną z koniecznością zmiany nazwy lub usunięcia plików.

Unikaj mieszania dodawania lub zmiany zawartości z nazwami i usuwaniem plików. Do odpowiedniego pliku przekierowania musisz dodać każdy plik, którego nazwę zmieniłeś lub usunąłeś. Jeśli to możliwe, zaktualizuj wszystkie pliki, które łączą się z zmienioną lub usuniętą zawartością, w tym wszystkie pliki spisu treści.

Unikanie edytowania plików konfiguracji repozytorium

Unikaj modyfikowania plików konfiguracji repozytorium. Ogranicz zmiany, jeśli to możliwe, do plików zawartości markdown i wszystkich plików obrazów pomocniczych potrzebnych do zawartości.

Nieprawidłowe modyfikacje plików konfiguracji repozytorium mogą przerwać kompilację, wprowadzić luki w zabezpieczeniach lub problemy z ułatwieniami dostępu lub naruszać standardy organizacyjne. Pliki konfiguracji repozytorium to wszystkie pliki zgodne z co najmniej jednym z następujących wzorców:

• *.yml
• .github/**
• .localization-config
• .openpublishing*
• LICENSE*
• reference/docfx.json
• reference/mapping/**
• tests/**
• ThirdPartyNotices
• tools/**

W celu zapewnienia bezpieczeństwa i ochrony nie należy zmieniać tych plików. Jeśli uważasz, że jeden z tych plików powinien zostać zmieniony, zgłoś problem. Po sklasyfikowaniu problemu przez konserwatorów zostaną wprowadzone odpowiednie zmiany.

Użyj szablonu Pull Request

Gdy tworzysz PR, szablon jest automatycznie wstawiany do treści PR. Wygląda na to:

# PR Summary

<!--
    Delete this comment block and summarize your changes and list
    related issues here. For example:

    This changes fixes problem X in the documentation for Y.

    - Fixes #1234
    - Resolves #1235
-->

## PR Checklist

<!--
    These items are mandatory. For your PR to be reviewed and merged,
    ensure you have followed these steps. As you complete the steps,
    check each box by replacing the space between the brackets with an
    x or by clicking on the box in the UI after your PR is submitted.
-->

- [ ] **Descriptive Title:** This PR's title is a synopsis of the changes it proposes.
- [ ] **Summary:** This PR's summary describes the scope and intent of the change.
- [ ] **Contributor's Guide:** I have read the [contributors guide][contrib].
- [ ] **Style:** This PR adheres to the [style guide][style].

<!--
    If your PR is a work in progress, please mark it as a draft or
    prefix it with "(WIP)" or "WIP:"

    This helps us understand whether or not your PR is ready to review.
-->

[contrib]: /powershell/scripting/community/contributing/overview
[style]: /powershell/scripting/community/contributing/powershell-style-guide

W sekcji "Podsumowanie PR" napisz krótkie podsumowanie swoich zmian i wymień powiązane problemy według ich numeru, na przykład #1234. Jeśli twoje PR naprawi lub rozwiąże problem, użyj funkcji GitHub autozamykania, aby problem został automatycznie zamknięty po scaleniu PR.

Przejrzyj elementy w sekcji "Lista kontrolna PR" i odhacz je po zakończeniu każdego z nich. Musisz postępować zgodnie z instrukcjami i sprawdzić wszystkie punkty, aby zespół zaakceptował pull request.

Jeśli żądanie ściągnięcia jest w toku, ustaw jego status na tryb roboczy lub poprzedź tytuł żądania ściągnięcia poleceniem WIP.

Komentarz oczekiwania

Po przesłaniu pull request, doda bot komentarz do twojego pull request. Komentarz zawiera zasoby i określa oczekiwania dotyczące pozostałej części procesu. Możemy okresowo aktualizować ten komentarz, więc zawsze przeglądać komentarz, nawet jeśli nie jest to twój pierwszy wkład.

Usługa weryfikacji Pull Request dla Docs

Usługa weryfikacji pull requestów Docs to aplikacja GitHub, która uruchamia reguły sprawdzania poprawności Twoich zmian. Należy naprawić wszelkie błędy lub ostrzeżenia zgłoszone przez usługę walidacji.

Dalsze kroki opisują zachowanie weryfikacji:

1. Przesyłasz PR.

2. W komentarzu na GitHubie wskazującym status „kontroli” włączonych w repozytorium. W tym przykładzie są włączone dwa kontrole: "Commit Validation" i "OpenPublishing.Build":

   

   Kompilacja może przejść nawet wtedy, gdy walidacja zatwierdzenia zakończy się niepowodzeniem.

3. Wybierz pozycję Szczegóły , aby uzyskać więcej informacji. Na stronie Szczegóły są wyświetlane wszystkie testy poprawności, które zakończyły się niepowodzeniem, oraz informacje o sposobie rozwiązywania problemów.

4. Po pomyślnym zakończeniu walidacji do pull requestu zostanie dodany następujący komentarz:

   

Uwaga

Jeśli jesteś współautorem zewnętrznym (a nie pracownikiem firmy Microsoft), nie masz dostępu do szczegółowych raportów kompilacji ani linków do wersji zapoznawczej.

Po przejrzeniu PR możesz zostać poproszony o wprowadzenie zmian lub usunięcie komunikatów ostrzegawczych dotyczących walidacji. Zespół PowerShell-Docs może pomóc zrozumieć błędy walidacji i wymagania redakcyjne.

Funkcja GitHub Actions

Kilka różnych funkcji GitHub Actions jest uruchamianych względem zmian w celu zweryfikowania i udostępnienia kontekstu dla Ciebie i recenzentów.

Weryfikacja listy kontrolnej

Jeśli Twoje PR nie jest w trybie roboczym i nie jest poprzedzone prefiksem WIP, akcja GitHub sprawdza PR, aby zweryfikować, czy wybrano każdy element z listy kontrolnej szablonu PR. Opiekunowie nie będą przeglądać ani scalać twojego PR, dopóki nie ukończysz listy kontrolnej. Elementy listy kontrolnej są obowiązkowe.

Weryfikacja autoryzacji

Jeśli Twoje żądanie ściągnięcia dotyczy konkretnej gałęzi live lub modyfikuje pliki konfiguracyjne w repozytorium, akcja usługi GitHub weryfikuje Twoje uprawnienia, aby upewnić się, że masz zgodę na przesyłanie tych zmian.

Tylko administratorzy repozytorium mają uprawnienia do ukierunkowywania gałęzi live lub modyfikowania plików konfiguracji repozytorium.

Raportowanie zmian zawartości według wersji

Jeśli pull request dodaje, usuwa lub modyfikuje jakąkolwiek wersjonowaną zawartość, akcja GitHub analizuje te zmiany i zapisuje raport podsumowujący typy zmian wprowadzonych w wersjonowanej zawartości.

Ten raport może pokazać, czy istnieją inne wersje plików, które należy zaktualizować w tym pull request.

Aby znaleźć raport zawartości w wersji dla żądania ściągnięcia:

1. Wybranie karty "Sprawdzanie" na stronie żądania ściągnięcia.
2. Wybierz zadanie "Raportowanie" z listy zadań.
3. Wybierz przycisk "..." w prawym górnym rogu.
4. Wybierz pozycję "Wyświetl podsumowanie zadania".

Następne kroki

przewodnik PowerShell-Docs po stylu

Dodatkowe zasoby

Zarządzanie pull requestami