Pull Requests – MRTK2

  • Artikel

Voraussetzungen

Wenn Sie zuvor noch nicht an einem Microsoft-Projekt mitgewirkt haben, werden Sie möglicherweise aufgefordert, einen Lizenzvertrag für Mitwirkende (Contributor License Agreement) zu unterschreiben. Ein Kommentar in dem PR informiert Sie darüber.

Wichtig

Wenn Sie Mitarbeiter von Microsoft und kein Mitglied der Microsoft-Organisation auf GitHub sind, verknüpfen Sie Ihre Microsoft- und GitHub-Konten auf Corpnet, indem Sie Open Source bei Microsoft besuchen, bevor Sie mit dem Pull Request beginnen. Es gibt einige Verarbeitungsschritte, die Sie vorab ausführen müssen.

Erstellen eines Pull Requests

Wenn Sie bereit sind, einen Pull Request zu übermitteln, erstellen Sie einen Pull Request für den Standard Branch. Für Fehlerbehebungen während eines Releasestabilisierungszeitraums suchen Sie nach dem neuesten prerelease/* Branch. Neue Features sollten immer in eingefügt werden main.

Lesen Sie die Richtlinien, und stellen Sie sicher, dass Ihr Pull Request diese erfüllt.

  • Stellen Sie sicher, dass Sie auf alle Probleme/Featureanforderungen oder Aufgaben verweisen, auf die sich der PR bezieht.
  • Überprüfen Sie, ob der Pull Request nur Dateien/Änderungen enthält, die sich auf den PR beziehen.
  • Überprüfen Sie, ob die Dokumentation aktuell und enthalten ist. Überprüfen Sie, ob alle öffentlichen Felder über Kommentare verfügen.
  • Wenn Sie ein neues Feature hinzufügen, überprüfen Sie, ob Tests zum Überprüfen des Features enthalten sind (siehe UnitTests (Komponententests)).
  • Wenn Sie einen Fehler korrigieren, schreiben Sie einen Test, um die Fehlerbehebung überprüfen zu können.

Die Projektverwalter überprüfen Ihre Änderungen. Unser Anspruch ist es, alle Änderungen innerhalb von drei Werktagen zu überprüfen. Adressieren Sie alle Überprüfungskommentare, pushen Sie in Ihren Themen-Branch, und posten Sie einen Kommentar, um uns zu informieren, dass es etwas Neues zu überprüfen gibt.

Hinweis

Alle an das Projekt übermittelten PRs werden auch gemäß dem MRTK-Handbuch für Programmierstandards überprüft. Überprüfen Sie diese also vor dem Übermitteln Ihres PR, um einen reibungslosen Ablauf zu gewährleisten.

Richtlinien für Pull Requests

Diese Richtlinien basieren auf den Entwicklungspraktiken von Google.

Halten Sie Pull Requests klein.

Kleinere PRs werden schneller und gründlicher überprüft, führen mit geringerer Wahrscheinlichkeit Fehler ein, ein Rollback ist einfacher, und sie lassen sich einfacher zusammenführen.

Ein Pull Request sollte so klein sein, dass ein Techniker ihn in weniger als 30 Minuten überprüfen kann. Versuchen Sie, lediglich eine minimale Änderung vorzunehmen, die nur eine Aktion behandelt. Wenn Sie einen großen PR erstellen müssen, teilen Sie ihn in mehrere PRs auf, die entweder in Ihren lokalen Branch oder in einen Feature-Branch von MRTK gelangen. Vermeiden Sie das Hinzufügen neuer Objekte (z. B. FBX-, OBJ-Dateien), und versuchen Sie stattdessen, vorhandene Objekte wiederzuverwenden.

Tests sollten mit Ausnahme von Notfällen im selben PR wie Ihr Fix/Feature hinzugefügt werden.

Tests sind die beste Möglichkeit, um sicherzustellen, dass der vorhandene Code von den Änderungen nicht verschlechtert wird. Es ist jedoch auch leicht, bei der Übermittlung von Pull Requests die Tests zu vergessen. Anzufordern, dass Tests in Ihren PR einfließen müssen, ist eine gute Möglichkeit, um sicherzustellen, dass die Tests geschrieben werden.

Allen Features und Fehlerbehebungen sollten Tests zugeordnet sein. Wenn Sie nicht über das Fachwissen oder die Zeit zum Schreiben eines Tests verfügen, erstellen Sie ein Problem, um die Tests zu schreiben, und markieren Sie es mit der Bezeichnung Für aktuelle Iteration berücksichtigen.

Die Dokumentation sollte im selben Pull Request hinzugefügt werden wie ein Fix/Feature.

Die meisten Entwickler sehen sich zunächst die Dokumentation und nicht den Code an, wenn sie wissen möchten, wie eine Funktion zu verwenden ist. Die Sicherstellung, dass die Dokumentation auf dem neuesten Stand ist, erleichtert Benutzern die Nutzung von MRTK erheblich. Die Dokumentation sollte immer mit dem zugehörigen Pull Request gebündelt werden, um sicherzustellen, dass die Elemente aktuell und konsistent bleiben.

Stellen Sie sicher, dass jedes öffentliche Feld sowie jede Methode und Eigenschaft über Zusammenfassungskommentare mit dreifachen Schrägstrichen verfügt, damit unsere docfx-Site Beschreibungen für Felder/Methoden generieren kann. Aktualisieren Sie bei Bedarf markdown-Dateien im Dokumentationsordner.

Beschreibungen von Pull Requests sollten Änderungen eindeutig und vollständig beschreiben.

Klare und vollständige Beschreibungen von Pull Requests stellen sicher, dass Prüfer verstehen, was Sie überprüfen.

Fügen Sie beim Hinzufügen von Features, die UX enthalten, ein Bild/GIF des Features hinzu, das Sie ändern. Hier sehen Sie ein gutes Beispiel. Ein anderer Vorschlag besteht darin, eine Vorher-/Nachher-GIF zu haben, z. B. in diesem Pull Request. Ein Tool, das wir zum Erstellen von GIFs aus Screenshots empfehlen, ist ScreenToGif.