Belangrijke wijzigingen aanbrengen in microsoft Learn-documentatie

Belangrijk

Alle opslagplaatsen die naar Microsoft Learn publiceren, hebben de Microsoft Open Source-gedragscode of de .NET Foundation-gedragscode aangenomen. Zie Veelgestelde vragen over de gedragscode voor meer informatie. Of neem contact op via opencode@microsoft.com of conduct@dotnetfoundation.org als u vragen of opmerkingen hebt.

Kleine correcties of verduidelijkingen van documentatie en codevoorbeelden in openbare opslagplaatsen vallen onder de learn.microsoft.com Gebruiksvoorwaarden. Wijzigingen genereren een opmerking in de pull-aanvraag, waarin u wordt gevraagd om een online licentieovereenkomst voor bijdragen (CLA) in te dienen als u geen werknemer van Microsoft bent. U moet het onlineformulier invullen voordat uw pull-aanvraag kan worden samengevoegd.

In dit artikel leest u hoe u een Microsoft Learn-artikel wijzigt met behulp van lokale hulpprogramma's en geschikt is voor een inzender die een belangrijke wijziging moet aanbrengen of een frequente bijdrager aan een opslagplaats moet zijn. Frequente inzenders hebben doorgaans doorlopende of langlopende wijzigingen die meerdere build-/validatie-/faseringscycli doorlopen of meerdere dagen duren voordat ze zich afmelden bij hun pull-aanvraag (PR).

Voorbeelden van dergelijke bijdragen zijn:

• Een grote bijdrage leveren. Uw bijdragen (toevoegingen, wijzigingen of verwijderingen) kunnen bijvoorbeeld meerdere artikelen omvatten en moeten worden doorgevoerd en getest als één werkeenheid in één pull-aanvraag.
• Een nieuw artikel maken en publiceren, waarvoor meestal een robuustere lokale editor nodig is.
• Als u nieuwe afbeeldingen toevoegt of afbeeldingen bijwerkt, moet u doorgaans tegelijkertijd een nieuwe media submap maken, afbeeldingsbestanden maken, koppelingen naar afbeeldingen bijwerken in artikelen en Markdown-bestanden bekijken in een lokale editor om de rendering van afbeeldingen te testen.
• Een artikel gedurende enkele dagen bijwerken voordat u het publiceert. In deze gevallen moet u doorgaans regelmatig andere wijzigingen integreren die plaatsvinden in de standaardbranch. Deze integratie gaat gemakkelijker via Git Bash en lokaal bewerken. U loopt ook het risico dat u uw bewerkingen kwijtraakt als u dit doet via de GitHub-webeditor en wacht voordat u de wijzigingen doorvoert.
• Continu updates aanbrengen in hetzelfde artikel nadat een pull-aanvraag is geopend. Hoewel u hiervoor de GitHub-webeditor kunt gebruiken, kunt u meerdere uitstekende PULL's maken voor hetzelfde bestand, wat kan conflicteren met elkaar.

Vereisten

• Identificeer de GitHub-opslagplaats waarin de documentatie wordt opgeslagen die u wilt bewerken.
• Maak een GitHub-account als u er nog geen hebt.
• Installeer Git- en Markdown-hulpprogramma's.
• Een lokale Git-opslagplaats instellen.
• Bekijk de basisprincipes van Git en GitHub (optioneel).

Uw werkbranch maken en uitchecken

Als u wilt beginnen, maakt u een nieuwe werkbranch in uw lokale opslagplaats om uw voorgestelde wijzigingen vast te leggen. Zie de basisprincipes van Git en GitHub voor meer achtergrondinformatie over vertakkingen.

In deze zelfstudie wordt gebruikgemaakt van Git Bash en Visual Studio Code, maar u kunt elke Gewenste Git-client en editor gebruiken.

1. Open in VS Code de opslagplaatsmap van uw lokale kloon. Selecteer in het menu Bestand de optie Map openen en navigeer naar de map op uw computer.

2. Selecteer Weergave in het bovenste menu en selecteer Terminal om de geïntegreerde terminal te openen.

3. Zorg ervoor dat u zich in de map met de opslagplaats bevindt in de geïntegreerde terminal.

4. Voordat u een werkvertakking maakt, moet u ervoor zorgen dat uw lokale hoofdvertakking actueel is met alles in de hoofdvertakking van de productieopslagplaats. Deze taak zorgt ervoor dat uw werkvertakking wijzigingen vastlegt die zijn aangebracht in de productieopslagplaats sinds de laatste keer dat u deze hebt gesynchroniseerd.

   1. Schakel over naar de hoofdbranch in uw lokale opslagplaats:

      git checkout main 
      

   2. Zorg ervoor dat uw lokale hoofdbranch actueel is:

      git pull upstream main 
      

5. Maak een lokale werkbranch op basis van de hoofdfunctie:

   git checkout -b <branch-name>
   

   <branch-name> is een tijdelijke aanduiding. Wanneer u de opdracht uitvoert, vervangt u deze door een unieke en zinvolle naam voor uw vertakking en verwijdert u de punthaken.

6. Push de lokale werkbranch naar de externe vertakking in uw GitHub-fork:

   git push origin <branch-name> -u
   

   De optie -u koppelt de lokale en externe vertakkingen. Met deze optie kunt u doorvoeringen naar uw fork pushen door alleen git push in te voeren in plaats van git push origin <branch-name>.

Het Markdown-bronbestand zoeken

Als u een artikel wilt bewerken, zoekt u het bronbestand voor het artikel in de kloon van uw lokale opslagplaats. Open in VS Code de Markdown-bestanden van de opslagplaats via de Verkenner (een documentpictogram in de zijbalk linksboven). De bestandsverkenner toont de mapstructuur van de opslagplaats en u kunt naar het bestand navigeren dat u wilt bewerken.

Als u het bestand niet kunt vinden, gaat u naar het artikel in Microsoft Learn en selecteert u het potloodpictogram bewerken . De relatieve maplocatie in de GitHub-opslagplaats wordt weergegeven in de URL. Hier volgt een voorbeeld van de URL van de koppeling Bewerken :

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Hier volgt een voorbeeld van een bestandslocatie voor deze URL.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Het bestand bewerken

1. Open het bestand in VS Code door het te selecteren.
2. Breng uw wijzigingen aan.
3. Sla uw wijzigingen op door Bestand>Opslaan te selecteren. Gebruik Alles opslaan om meerdere bestanden tegelijk op te slaan.

Uw wijzigingen doorvoeren en pushen

Als u aanzienlijke wijzigingen hebt aangebracht of een artikel hebt gecontroleerd op nieuwheid, werkt ms.date u dit bij in het metagegevensblok bovenaan het bestand. Maak de datum op als mm/dd/jjjj.

U kunt de VS Code-terminal of de VS Code-gebruikersinterface gebruiken om uw wijzigingen door te voeren en te pushen.

VS Code Terminal

1. Voer de git status opdracht uit om te controleren of alleen de bestanden die u hebt bewerkt, worden weergegeven in de lijst met gewijzigde bestanden.

   git status
   

2. Voer de git add opdracht uit, gevolgd door het bestandspad en de bestandsnaam om het bestand dat u hebt gewijzigd, klaar te maken.

   git add folder-name/file-name.md
   

   Als u meerdere bestanden hebt gewijzigd, voert u een git add opdracht in voor elk bestand.

   U kunt ook uitvoeren git add . (noteer de periode na add) om alle wijzigingen die u hebt aangebracht, automatisch te fasen. Deze methode is sneller, maar kan problemen veroorzaken door wijzigingen die u per ongeluk hebt aangebracht, op te slaan.

3. Voer git status opnieuw uit om te controleren welke wijzigingen zijn gefaseerd.

4. Voer de git commit opdracht uit, gevolgd door een doorvoerbericht om de wijzigingen op te slaan in uw lokale gekloonde opslagplaats.

   git commit -m "your commit message"
   

5. Voer deze opdracht uit git push om uw wijzigingen te pushen.

   git push
   

VS Code-gebruikersinterface

U kunt een doorvoering maken en pushen met behulp van Git-integratiefuncties van VS Code. Vergeet niet om uw werk op dezelfde computer voort te zetten. Als u van computer wisselt, beschikt u niet over de nieuwste versie van de werkbranch om door te gaan.

1. Zorg ervoor dat uw lokale opslagplaats nog steeds dezelfde werkvertakking heeft uitgecheckt. In de GEBRUIKERSinterface van VS Code wordt de vertakking weergegeven in de linkerbenedenhoek. De naam van de vertakking fungeert ook als een knop voor het schakelen tussen vertakkingen.

   

2. Selecteer in de zijbalk links van VS Code het hulpprogramma fork om het broncodebeheer te zien: Git-deelvenster .

   

   Het bestand dat u hebt bewerkt, wordt weergegeven onder Wijzigingen met een M aan de rechterkant om aan te geven dat het is gewijzigd. Nieuwe bestanden worden weergegeven met een U (niet-bijgehouden) en verwijderde bestanden worden weergegeven met een D.

3. Faseer de wijzigingen. Beweeg de muisaanwijzer over de regel Wijzigingen totdat een + pictogram wordt weergegeven. Selecteer dat pictogram. Deze actie is gelijk aan de git add opdracht. Het bestand wordt nu weergegeven in de sectie Gefaseerde wijzigingen .

4. Voer een doorvoerbericht in, zoals 'Datum van metagegevens bijwerken' in het tekstvak Bericht en selecteer het vinkje.

   

5. Push de doorvoering. Selecteer de knop Wijzigingen synchroniseren die onder het doorvoerberichtblok wordt weergegeven.

   

U bent klaar! Uw code bevindt zich nu in uw GitHub-opslagplaats en kunt u een pull-aanvraag openen.

Moet u iets herstellen dat u hebt ingediend? Het is makkelijk! Herhaal de bovenstaande stappen, te beginnen met Het bestand bewerken, om wijzigingen in dezelfde vertakking aan te brengen en doorvoeren en opnieuw te pushen (u hoeft de upstream-server niet in te stellen op volgende pushes van dezelfde vertakking). Over het algemeen worden vertakkingen gebruikt om werkstromen te scheiden, dus u hoeft geen nieuwe vertakking te maken, tenzij u klaar bent om aan iets anders te werken.

De volgende wijziging aanbrengen

Wilt u een andere wijziging aanbrengen, niet gerelateerd aan deze? Ga terug naar de standaardbranch, haal de upstream-opslagplaats op om uw fork bij te werken en bekijk een nieuwe vertakking. Voer de volgende opdrachten uit in Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

U bevindt zich nu in een nieuwe vertakking die is gekoppeld aan uw externe vertakking en u bent klaar om meer wijzigingen aan te brengen. Je bent goed op weg om een expert inzender te worden!

Volgende stappen

• Als u de bovenstaande stappen hebt voltooid, is het nu tijd om een pull-aanvraag te openen om uw wijzigingen samen te voegen in de hoofdbranch.
• Raadpleeg de Markdown-verwijzing voor meer informatie over onderwerpen zoals de syntaxis van Markdown- en Markdown-extensies.