Πραγματοποίηση σημαντικών αλλαγών στην τεκμηρίωση του Microsoft Learn

Σημαντικό

Όλα τα αποθετήρια δεδομένων που δημοσιεύουν στο Microsoft Learn έχουν υιοθετήσει είτε τον Κώδικα δεοντολογίας ανοιχτού κώδικα της Microsoft είτε τον Κώδικα δεοντολογίας του .NET Foundation. Για περισσότερες πληροφορίες, ανατρέξτε στις Συνήθεις ερωτήσεις για τον Κώδικα δεοντολογίας. Εναλλακτικά, επικοινωνήστε στη διεύθυνση opencode@microsoft.com ή conduct@dotnetfoundation.org με τυχόν ερωτήσεις ή σχόλια.

Οι δευτερεύουσες διορθώσεις ή διευκρινίσεις σε τεκμηρίωση και παραδείγματα κώδικα σε δημόσια αποθετήρια καλύπτονται από τους learn.microsoft.com Όρους χρήσης. Οποιεσδήποτε αλλαγές θα δημιουργήσουν ένα σχόλιο στο αίτημα έλξης, ζητώντας σας να υποβάλετε μια ηλεκτρονική άδεια συμβολής (CLA) αν δεν είστε υπάλληλος της Microsoft. Θα πρέπει να συμπληρώσετε την ηλεκτρονική φόρμα για να συγχωνευτεί το αίτημα έλξης.

Αυτό το άρθρο εξηγεί πώς μπορείτε να αλλάξετε ένα άρθρο του Microsoft Learn χρησιμοποιώντας τοπικά εργαλεία και είναι κατάλληλο για συμβάλλοντες που πρέπει να κάνουν μια σημαντική αλλαγή ή θα συμβάλλουν συχνά σε ένα αποθετήριο δεδομένων. Οι συχνοί συμβάλλοντες συνήθως έχουν συνεχείς ή μακροχρόνιες αλλαγές που περνούν από πολλαπλούς κύκλους δόμησης/επικύρωσης/προεργασίας ή εκτείνονται πολλές ημέρες πριν υπογράψουν το αίτημα έλξης (PR).

Παραδείγματα αυτών των τύπων συμβολής περιλαμβάνουν:

• Πραγματοποίηση μεγάλης συμβολής. Για παράδειγμα, η συμβολή σας (προσθήκες, αλλαγές ή διαγραφές) μπορεί να εκτείνεται σε πολλά άρθρα και πρέπει να δεσμευτούν και να ελεγχθούν ως μία μονάδα εργασίας σε ένα μόνο αίτημα έλξης.
• Δημιουργία και δημοσίευση νέου άρθρου, που συνήθως απαιτεί ένα ισχυρότερο τοπικό πρόγραμμα επεξεργασίας.
• Προσθήκη νέων εικόνων ή ενημέρωση εικόνων, που συνήθως απαιτεί να δημιουργήσετε ταυτόχρονα έναν νέο media υποκατάλογο, να δημιουργήσετε αρχεία εικόνας, να ενημερώσετε τις συνδέσεις εικόνας σε άρθρα και να κάνετε προεπισκόπηση αρχείων Markdown σε ένα τοπικό πρόγραμμα επεξεργασίας για να ελέγξετε την απόδοση της εικόνας.
• Ενημέρωση ενός άρθρου σε βάθος μερικών ημερών πριν από τη δημοσίευση. Σε αυτές τις περιπτώσεις, συνήθως χρειάζεται να ενσωματώνετε τακτικά άλλες αλλαγές που πραγματοποιούνται στην προεπιλεγμένη διακλάδωση. Αυτή η ενσωμάτωση είναι ευκολότερη μέσω του Git Bash και με τοπική επεξεργασία. Επίσης, διατρέχετε τον κίνδυνο να χάσετε τις αλλαγές σας εάν το κάνετε αυτό μέσω του προγράμματος επεξεργασίας Web GitHub και περιμένετε πριν δεσμεύσετε τις αλλαγές.
• Πραγματοποίηση συνεχών ενημερώσεων στο ίδιο άρθρο μετά το άνοιγμα ενός pr. Παρόλο που μπορείτε να χρησιμοποιήσετε το πρόγραμμα επεξεργασίας web GitHub για αυτόν το σκοπό, μπορεί να δημιουργήσετε πολλά εκκρεμή αιτήματα έλξης για το ίδιο αρχείο, τα οποία ενδέχεται να έρχονται σε διένεξη το ένα με το άλλο.

Προαπαιτούμενα στοιχεία

• Προσδιορίστε το αποθετήριο GitHub που αποθηκεύει την τεκμηρίωση που θέλετε να επεξεργαστείτε.
• Δημιουργήστε έναν λογαριασμό GitHub, εάν δεν έχετε λογαριασμό.
• Εγκαταστήστε τα εργαλεία Git και Markdown.
• Ρυθμίστε ένα τοπικό αποθετήριο δεδομένων Git.
• Εξετάστε τα βασικά στοιχεία του Git και του GitHub (προαιρετικό).

Δημιουργία και ανάληψη ελέγχου του κλάδου εργασίας σας

Για να ξεκινήσετε, δημιουργήστε έναν νέο κλάδο εργασίας στο τοπικό αποθετήριο δεδομένων για να καταγράψετε τις προτεινόμενες αλλαγές. Για περισσότερες πληροφορίες σχετικά με τους κλάδους, ανατρέξτε στα βασικά στοιχεία του Git και του GitHub.

Αυτή η εκμάθηση χρησιμοποιεί το Git Bash και τον Κώδικα Visual Studio, αλλά μπορείτε να χρησιμοποιήσετε οποιοδήποτε πρόγραμμα-πελάτη και πρόγραμμα επεξεργασίας Git προτιμάτε.

1. Στον κώδικα VS, ανοίξτε τον φάκελο αποθετηρίου του τοπικού κλώνου σας. Από το μενού Αρχείο , επιλέξτε Άνοιγμα φακέλου και μεταβείτε στον φάκελο στον υπολογιστή σας.

2. Επιλέξτε Προβολή από το επάνω μενού και, στη συνέχεια, επιλέξτε Τερματικό για να ανοίξετε το ενσωματωμένο τερματικό.

3. Στο ενσωματωμένο τερματικό, βεβαιωθείτε ότι βρίσκεστε στον φάκελο του αποθετηρίου.

4. Προτού δημιουργήσετε έναν κλάδο εργασίας, βεβαιωθείτε ότι ο τοπικός κύριος κλάδος είναι τρέχων με όλα τα στοιχεία στον κύριο κλάδο του αποθετηρίου παραγωγής. Αυτή η εργασία εξασφαλίζει ότι ο κλάδος εργασίας σας καταγράφει τυχόν αλλαγές που έχουν συμβεί στο αποθετήριο δεδομένων παραγωγής από την τελευταία φορά που συγχρονίσατε με αυτό.

   1. Μεταβείτε στον κύριο κλάδο στο τοπικό αποθετήριο δεδομένων σας:

      git checkout main 
      

   2. Βεβαιωθείτε ότι ο τοπικός κύριος κλάδος είναι τρέχων:

      git pull upstream main 
      

5. Δημιουργήστε έναν τοπικό κλάδο εργασίας με βάση την κύρια:

   git checkout -b <branch-name>
   

   <branch-name> Το είναι ένα σύμβολο κράτησης θέσης. Όταν εκτελείτε την εντολή, αντικαταστήστε τη με ένα μοναδικό και χαρακτηριστικό όνομα για τη διακλάδωση και καταργήστε τις γωνιακές αγκύλες.

6. Προωθήστε τον τοπικό κλάδο εργασίας στον απομακρυσμένο κλάδο στη διακλάδωση του GitHub:

   git push origin <branch-name> -u
   

   Η επιλογή -u συνδέει τους τοπικούς και απομακρυσμένους κλάδους. Αυτή η επιλογή σάς επιτρέπει να προωθείτε δεσμεύσεις στη διακλάδωση σας, καταχωρώντας απλώς git push αντί git push origin <branch-name>για .

Εύρεση του αρχείου Markdown προέλευσης

Για να επεξεργαστείτε ένα άρθρο, βρείτε το αρχείο προέλευσης για το άρθρο στον τοπικό κλώνο αποθετηρίου δεδομένων. Εντός του VS Code, αποκτήστε πρόσβαση στα αρχεία Markdown του αποθετηρίου μέσω της εξερεύνησης αρχείων (ένα εικονίδιο εγγράφου στην επάνω αριστερή πλαϊνή γραμμή). Η εξερεύνηση αρχείων εμφανίζει τη δομή φακέλων του αποθετηρίου δεδομένων και μπορείτε να μεταβείτε στο αρχείο που θέλετε να επεξεργαστείτε.

Εάν δεν μπορείτε να βρείτε το αρχείο, επισκεφθείτε το άρθρο στο Microsoft Learn και επιλέξτε το εικονίδιο μολυβιού Επεξεργασία . Η θέση σχετικού φακέλου στο αποθετήριο δεδομένων GitHub εμφανίζεται στη διεύθυνση URL. Ακολουθεί ένα παράδειγμα διεύθυνσης URL επεξεργασίας σύνδεσης:

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

Ακολουθεί ένα παράδειγμα τοποθεσίας αρχείου για αυτήν τη διεύθυνση URL.

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

Επεξεργασία του αρχείου

1. Ανοίξτε το αρχείο στο VS Code επιλέγοντάς το.
2. Κάντε τις αλλαγές σας.
3. Αποθηκεύστε τις αλλαγές σας επιλέγοντας Αρχείο>Αποθήκευση. Χρησιμοποιήστε την Αποθήκευση όλων για να αποθηκεύσετε πολλά αρχεία ταυτόχρονα.

Δέσμευση και προώθηση των αλλαγών σας

Εάν κάνατε σημαντικές αλλαγές ή εξετάσατε ένα άρθρο για ενημέρωση, ενημερώστε ms.date το στο μπλοκ μετα-δεδομένων στο επάνω μέρος του αρχείου. Μορφοποιήστε την ημερομηνία ως μμ/ηη/εεεε.

Μπορείτε να χρησιμοποιήσετε το τερματικό VS Code ή το περιβάλλον εργασίας χρήστη του VS Code για να υποβάλετε και να προωθήσετε τις αλλαγές σας.

VS Code Terminal

1. Εκτελέστε την git status εντολή για να επαληθεύσετε ότι εμφανίζονται μόνο τα αρχεία που επεξεργαστατε στη λίστα των τροποποιημένων αρχείων.

   git status
   

2. Εκτελέστε την git add εντολή ακολουθούμενη από τη διαδρομή αρχείου και το όνομα αρχείου για να δημιουργήσετε ένα στάδιο του αρχείου που αλλάξατε.

   git add folder-name/file-name.md
   

   Εάν αλλάξατε πολλά αρχεία, πληκτρολογήστε μια git add εντολή για κάθε αρχείο.

   Εναλλακτικά, μπορείτε να εκτελέσετε git add . (σημειώστε την περίοδο μετά addτο ) για να οργανώσετε αυτόματα όλες τις αλλαγές που κάνατε. Αυτή η μέθοδος είναι ταχύτερη, αλλά μπορεί να προκαλέσει προβλήματα συμπεριλαμβάνοντας αλλαγές που κάνατε κατά λάθος.

3. Εκτελέστε git status ξανά για να επιβεβαιώσετε ποιες αλλαγές έχουν πραγματοποιηθεί.

4. Εκτελέστε την git commit εντολή ακολουθούμενη από ένα μήνυμα δέσμευσης για να αποθηκεύσετε τις αλλαγές στο τοπικό κλωνοποιημένο αποθετήριο δεδομένων σας.

   git commit -m "your commit message"
   

5. Εκτελέστε το git push για να προωθήσετε τις αλλαγές σας.

   git push
   

Περιβάλλον εργασίας χρήστη vs code

Μπορείτε να δημιουργήσετε και προωθήσετε μια δέσμευση χρησιμοποιώντας τις δυνατότητες ενοποίησης Git του VS Code. Θυμηθείτε να συνεχίσετε την εργασία σας στον ίδιο υπολογιστή. Εάν κάνετε εναλλαγή μηχανών, δεν θα έχετε την πιο πρόσφατη έκδοση του κλάδου εργασίας για να συνεχίσετε.

1. Βεβαιωθείτε ότι το τοπικό αποθετήριο δεδομένων εξακολουθεί να έχει επιλεγμένο τον ίδιο κλάδο εργασίας. Στο περιβάλλον εργασίας χρήστη του VS Code, η διακλάδωση εμφανίζεται στην κάτω αριστερή γωνία. Το όνομα της διακλάδωσης λειτουργεί επίσης ως κουμπί για την εναλλαγή διακλαδώσεις.

   

2. Στην αριστερή πλαϊνή γραμμή του VS Code, επιλέξτε το εργαλείο διακλάδωμα για να δείτε το τμήμα παραθύρου Στοιχείο ελέγχου προέλευσης: Τμήμα παραθύρου Git .

   

   Το αρχείο που επεξεργαστατε εμφανίζεται στην περιοχή Αλλαγές με ένα M στη δεξιά πλευρά για να υποδείξετε ότι έχει τροποποιηθεί. Τα νέα αρχεία εμφανίζονται με ένα U (χωρίς παρακολούθηση) και τα διαγραμμένα αρχεία εμφανίζονται με ένα D.

3. Οργανώστε τις αλλαγές. Τοποθετήστε τον δείκτη του ποντικιού πάνω στη γραμμή Αλλαγές μέχρι να εμφανιστεί ένα + εικονίδιο. Επιλέξτε αυτό το εικονίδιο. Αυτή η ενέργεια ισοδυναμεί με την git add εντολή. Το αρχείο εμφανίζεται τώρα στην ενότητα Στάδιο αλλαγών .

4. Εισαγάγετε ένα μήνυμα δέσμευσης, όπως "ενημέρωση ημερομηνίας μετα-δεδομένων" στο πλαίσιο κειμένου Μήνυμα και επιλέξτε το σημάδι ελέγχου.

   

5. Προωθήστε την δέσμευση. Επιλέξτε το κουμπί Συγχρονισμός αλλαγών που εμφανίζεται κάτω από το μπλοκ δέσμευσης μηνύματος.

   

Τα καταφέρατε! Ο κώδικάς σας βρίσκεται πλέον στο αποθετήριο δεδομένων GitHub και είναι έτοιμος για να ανοίξετε ένα αίτημα έλξης.

Θέλετε να διορθώσετε κάτι που έχετε υποβάλει; Είναι εύκολο! Απλώς επαναλάβετε τα παραπάνω βήματα, ξεκινώντας με την Επεξεργασία του αρχείου, για να κάνετε αλλαγές στον ίδιο κλάδο και, στη συνέχεια, πραγματοποιήστε δέσμευση και προώθηση ξανά (δεν χρειάζεται να ρυθμίσετε τον διακομιστή upstream σε επόμενες ωθήσεις του ίδιου κλάδου). Γενικά, οι κλάδοι χρησιμοποιούνται για τον διαχωρισμό των ροών εργασίας, επομένως δεν χρειάζεται να δημιουργήσετε έναν νέο κλάδο, εκτός εάν είστε έτοιμοι να εργαστείτε σε κάτι άλλο.

Κάντε την επόμενη αλλαγή σας

Είστε έτοιμοι να κάνετε άλλη μια αλλαγή, που δεν σχετίζεται με αυτήν; Επιστρέψτε στον προεπιλεγμένο κλάδο, κάντε έλξη από το αποθετήριο upstream για να ενημερώσετε τη διακλάδωση και κάντε ανάληψη ελέγχου ενός νέου κλάδου. Εκτελέστε τις ακόλουθες εντολές στο Git Bash:

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

Βρίσκεστε τώρα σε έναν νέο κλάδο που συνδέεται με τον απομακρυσμένο κλάδο σας και είστε έτοιμοι να κάνετε περισσότερες αλλαγές. Είστε σε καλή πορεία για να γίνετε ειδικός συνεισφέρων!

Επόμενα βήματα

• Εάν έχετε ολοκληρώσει τα παραπάνω βήματα, τώρα είναι ώρα να ανοίξετε ένα αίτημα έλξης για να συγχωνευθούν οι αλλαγές σας στον κύριο κλάδο.
• Για να μάθετε περισσότερα σχετικά με το Markdown και τη σύνταξη επεκτάσεων Markdown, εξετάστε την αναφορά Markdown.