GitHub-bijdragewerkstroom voor kleine of onregelmatige wijzigingen

Belangrijk

Op alle opslagplaatsen die publiceren naar docs.microsoft.com is de Microsoft Open Source-gedragscode van toepassing. Zie Veelgestelde vragen over de gedragscode voor meer informatie. Of neem contact op met opencode@microsoft.com als u vragen of opmerkingen hebt.

Kleine correcties of verduidelijkingen voor de documentatie en codevoorbeelden in de openbare opslagplaatsen vallen onder de gebruiksvoorwaarden van docs.microsoft.com. Bij nieuwe inhoud of belangrijke wijzigingen wordt een opmerking gegenereerd in de pull-aanvraag, waarin u wordt gevraagd een online Contribution License Agreement (CLA) in te dienen als u geen werknemer van Microsoft bent. U moet het onlineformulier invullen voordat we uw pull-aanvraag kunnen accepteren.

Overzicht

Deze werkstroom is geschikt voor het aanbrengen van kleine of onregelmatige wijzigingen met de Markdown-webeditor van GitHub. U kunt met de GitHub-editor maar een beperkt aantal handelingen verrichten, omdat de gebruikersinterface geen ondersteuning biedt voor alle Git-bewerkingen en ontwerpscenario's. Als u grote bijdragen wilt leveren of ondersteuning nodig hebt voor geavanceerde Git-functies (zoals vertakkingsbeheer of geavanceerde oplossingen voor samenvoegingsconflicten), raadpleegt u de werkstroom voor belangrijke/langdurige wijzigingen.

Procedure voor het gebruik van de GitHub-editor om wijzigingen voor te stellen

  1. Blader naar de GitHub-opslagplaats en het Markdown-bestand dat bij het artikel behoort. U kunt een van de volgende methoden gebruiken:

    • Blader door de Markdown-bestanden in de betreffende GitHub-opslagplaats om naar het artikel te gaan.
    • Ga naar het artikel op docs.microsoft.com en selecteer de koppeling Bewerken in de rechterbovenhoek van de pagina.

      Locatie van de link Bewerken

      Belangrijk

      Als u een werknemer van Microsoft bent en in de privéopslagplaats moet werken, moet u het volgende doen voordat u naar de volgende stap gaat:

      1. Ga naar de adresbalk van uw browser en wijzig de koppeling zo dat deze doorverwijst naar de privéopslagplaats. In de meeste gevallen betekent dit dat u '-pr' moet toevoegen achter het opslagplaatsgedeelte van de URL. Zo wordt 'sql-docs' gewijzigd in 'sql-docs-pr', enzovoort.
      2. Als uw team wil dat u in een specifieke vertakking werkt, moet u er voor zorgen dat het vertakkingsgedeelte van de URL goed is ingesteld. Mogelijk moet u dit bijvoorbeeld wijzigen in 'master', 'live' of een uitgavevertakking.

      Vertakkingsverwijzing in URL

  2. Selecteer het potloodpictogram Edit this file om naar de bewerkingsmodus over te gaan:

    Locatie van het potloodpictogram

  3. Breng wijzigingen aan met Markdown op het tabblad Bestand bewerken en bekijk een voorbeeld van de aangebrachte wijzigingen op het tabblad Voorbeeld van wijzigingen. Het gebruik van de editor is redelijk eenvoudig. Als u echter hulp nodig hebt, raadpleegt u de volgende handleidingen:

  4. Scrol naar de onderkant van de pagina waar een van de volgende opties wordt weergegeven:

    • Bestandswijziging voorstellen: verschijnt als u alleen-lezentoegang hebt tot de opslagplaats, zoals bestanden bewerken in de opslagplaats van een andere gebruiker. In dit geval maakt GitHub een patchvertakking in uw kopie van de opslagplaats (en maakt deze automatisch een kopie als deze nog niet bestaat). Als u de knop Propose file change hebt geselecteerd, verschijnt de pagina Comparing changes, waar u uw wijzigingen kunt controleren. U selecteert vervolgens de knop Create pull request om de wijzigingen te verzenden naar de wachtrij voor pull-aanvragen en u gaat verder naar de volgende sectie.

    • Wijzigingen doorvoeren: verschijnt als u schrijftoegang hebt tot de opslagplaats zoals bestanden bewerken in uw eigen opslagplaats. In dit geval kunt u in GitHub op twee manieren de wijzigingen opslaan:

      • De wijzigingen rechtstreeks doorvoeren in de vertakking <branch-name> waar <branch-name> de naam is van de vertakking waar u zich bevond toen u de knop Bewerken hebt geselecteerd. Hierbij worden de wijzigingen rechtstreeks toegepast op de vertakking en wordt er geen pull-aanvraag gebruikt. Hiermee hebt u de bewerking voltooid.

      • Maak een nieuwe vertakking voor deze doorvoering en start een pull-aanvraag, waarbij u wordt gevraagd een nieuwe vertakking te maken en een standaardnaam wordt voorgesteld. Als u de knop Propose file change hebt geselecteerd, verschijnt de pagina Comparing changes, waar u uw wijzigingen kunt controleren. U selecteert vervolgens de knop Create pull request om de wijzigingen te verzenden naar de wachtrij voor pull-aanvragen en u gaat verder naar de volgende sectie.

Verwerking van pull-aanvragen

In de vorige sectie werd uitgelegd hoe u voorgestelde wijzigingen kunt indienen door deze in een nieuwe pull-aanvraag te bundelen die wordt toegevoegd aan de wachtrij voor pull-aanvragen in de doelopslagplaats. Met een pull-aanvraag wordt het samenwerkingsmodel van GitHub ingeschakeld door de wijzigingen uit uw werkvertakking te 'trekken' (pull) en samen te voegen met een andere vertakking. Die andere vertakking is meestal de standaard 'hoofdvertakking' in de hoofdopslagplaats.

Validatie

Voordat uw pull-aanvraag kan worden samengevoegd met de doelvertakking, moeten er misschien één of meer pull-aanvraagvalidaties worden uitgevoerd. Validaties kunnen verschillend zijn, afhankelijk van de omvang van voorgestelde wijzigingen en de regels van de doelopslagplaats. Nadat uw pull-aanvraag is ingediend, kunnen er één of meer van de volgende dingen gebeuren:

  • Samenvoegbaarheid: Er wordt eerst een GitHub-basistest voor samenvoegbaarheid uitgevoerd om te controleren of de voorgestelde wijzigingen in uw vertakking conflicteren met de doelvertakking. Als de pull-aanvraag aangeeft dat dit inderdaad het geval is, moet u de inhoud die het samenvoegingsconflict veroorzaakt, afstemmen voordat de verwerking kan worden hervat.
  • CLA: Als u bijdraagt aan een openbare opslagplaats en geen Microsoft-werknemer bent, wordt u afhankelijk van de omvang van de voorgestelde wijzigingen misschien gevraagd een korte CLA (Contribution License Agreement) in te vullen wanneer u voor het eerst een pull-aanvraag bij deze opslagplaats indient. Nadat de CLA-stap is goedgekeurd, wordt uw pull-aanvraag verwerkt.
  • Labeling: Er worden automatisch labels op uw pull-aanvraag toegepast om de status van uw pull-aanvraag aan te geven terwijl deze de validatiewerkstroom doorloopt. Nieuwe pull-aanvragen kunnen bijvoorbeeld automatisch het label 'niet-samenvoegen' krijgen, wat aangeeft dat de pull-aanvraag de stappen voor validatie, controle en goedkeuring nog niet heeft doorlopen.
  • Validatie en build: Uw wijzigingen worden door geautomatiseerde controles onderzocht om te controleren of ze de validatietests doorstaan. De validatietests kunnen waarschuwingen of fouten opleveren, waardoor u één of meer bestanden in uw pull-aanvraag moet wijzigen voordat deze kan worden samengevoegd. De resultaten van de validatietests worden als een opmerking in uw pull-aanvraag toegevoegd, zodat u deze kunt controleren, en kunnen ook per e-mail naar u worden gestuurd.
  • Fasering: De artikelpagina’s die worden beïnvloed door uw wijzigingen, kunnen automatisch in een faseringsomgeving worden geïmplementeerd voor controle na een succesvolle validatie en build. Voorbeeld-URL’s worden in een pull-aanvraagopmerking weergegeven.
  • Automatische samenvoeging: De pull-aanvraag kan automatisch worden samengevoegd als deze de validatietests doorstaat en aan bepaalde criteria voldoet. In dat geval hoeft u verder niets meer te doen.

Controle en goedkeuring

Nadat de pull-aanvraagverwerking is voltooid, moet u de resultaten (pull-aanvraagopmerkingen, voorbeeld-URL’s enz.) controleren om te bepalen of de bestanden ervan nog verder moeten worden gewijzigd voordat u de pull-aanvraag goedkeurt voor samenvoeging. Als een revisor voor pull-aanvragen uw pull-aanvraag heeft gecontroleerd, geeft deze misschien ook feedback via opmerkingen als er uitstaande problemen/vragen zijn die moeten worden opgelost voordat de pull-aanvraag wordt samengevoegd.

Door middel van automatisering van opmerkingen kunnen gebruikers op leesniveau (gebruikers die geen schrijfmachtigingen in een opslagplaats hebben) een actie op schrijfniveau uitvoeren door het desbetreffende label aan een pull-aanvraag (PR) toe te wijzen. Als u in een opslagplaats werkt waar automatisering van opmerkingen is geïmplementeerd, gebruikt u de hashtag-opmerkingen in de volgende tabel om labels toe te wijzen of te wijzigen, of een pull-aanvraag te sluiten. Microsoft-medewerkers krijgen ook via e-mail een melding over het controleren en goedkeuren van openbare opslagplaats-PR's als er wijzigingen worden voorgesteld voor artikelen waarvan u de auteur bent.

Hashtag-opmerking Gevolg Beschikbaarheid in opslagplaats
#sign-off Als de auteur van een artikel de opmerking #sign-off in de opmerkingenstream typt, wordt het label ready-to-merge toegewezen. Met dit label weten de revisoren in de opslagplaats wanneer een pull-aanvraag klaar is om te worden gecontroleerd of samengevoegd. Openbare en persoonlijk
#sign-off Als een bijdrager die niet als auteur vermeld staat, zich bij een openbare pull-aanvraag wil afmelden met de opmerking #sign-off, wordt er een bericht voor de pull-aanvraag geschreven waarin staat aangegeven dat alleen de auteur het label kan toewijzen. Openbaar
#hold-off Een auteur kan #hold-off in een PR-opmerking typen om het label ready-to-merge te verwijderen voor het geval zij of hij van gedachten verandert of een fout heeft gemaakt. In de persoonlijke opslagplaats wordt hierdoor het label do-not-merge toegewezen. Openbare en persoonlijk
#please-close Een auteur kan #please-close in de opmerkingenstream typen om de pull-aanvraag te sluiten als zij of hij besluit de wijzigingen niet te willen samenvoegen. Openbaar

Als de pull-aanvraag probleemvrij en goedgekeurd is, worden uw wijzigingen weer samengevoegd met de bovenliggende vertakking en wordt de pull-aanvraag gesloten.

Publicatie

Vergeet niet dat uw pull-aanvraag moet worden samengevoegd door een revisor voor pull-aanvragen voordat de wijzigingen kunnen worden opgenomen in de volgende geplande publicatie. Pull-aanvragen worden gewoonlijk gecontroleerd/samengevoegd in de volgorde waarin deze zijn ingediend. Als uw pull-aanvraag moet worden samengevoegd voor een bepaalde publicatie, moet u van tevoren met uw revisor voor pull-aanvragen overleggen en samenwerken om ervoor te zorgen dat de samenvoeging vóór de publicatie plaatsvindt.

Nadat uw bijdragen zijn goedgekeurd en samengevoegd, worden ze opgepikt door het Docs.Microsoft.Com-publicatieproces. Publicatiemomenten kunnen variëren, afhankelijk van het team dat de opslagplaats beheert waaraan u bijdraagt. Artikelen die onder de volgende paden worden gepubliceerd, worden gewoonlijk maandag t/m vrijdag om ongeveer 10:30 uur en 15:30 uur Pacific Time geïmplementeerd:

Het kan tot 45 minuten duren voordat artikelen online verschijnen nadat ze zijn gepubliceerd. Nadat uw artikel is gepubliceerd, kunt u uw wijzigingen controleren via de desbetreffende URL: http://docs.microsoft.com/<path-to-your-article-without-the-md-extension>.

Volgende stappen

  • Raadpleeg Aanbevolen procedures voor pull-aanvragen voor meer informatie over de procedure voor pull-aanvragen.

  • Ga verder naar de artikelen Belangrijke aspecten van het schrijven voor meer informatie over Markdown, de syntaxis van Markdown-extensies en meer.