ทําการเปลี่ยนแปลงที่สําคัญกับเอกสาร Microsoft Learn

  • บทความ

สำคัญ

ที่เก็บทั้งหมดที่เผยแพร่ไปยัง Microsoft Learn ได้นําแนวทางปฏิบัติของ Microsoft Open Source หรือ แนวทางปฏิบัติของ .NET Foundation มาใช้อย่างใดอย่างหนึ่ง สำหรับข้อมูลเพิ่มเติม ดูคำถามที่ถามบ่อยเกี่ยวกับแนวทางปฏิบัติ หรือติดต่อopencode@microsoft.com หรือ conduct@dotnetfoundation.orgเมื่อมีคำถามหรือข้อคิดเห็นใดๆ

การแก้ไขหรือการชี้แจงเล็กน้อยกับเอกสารประกอบและตัวอย่างโค้ดในที่เก็บสาธารณะครอบคลุมโดย ข้อกําหนดการใช้งาน learn.microsoft.com การเปลี่ยนแปลงใดๆ จะสร้างข้อคิดเห็นในคําขอดึงข้อมูล ที่ขอให้คุณส่งข้อตกลงสิทธิ์การใช้งานผลงาน (CLA) แบบออนไลน์ถ้าคุณไม่ใช่พนักงานของ Microsoft คุณจะต้องกรอกฟอร์มออนไลน์ก่อนที่จะสามารถผสานคำขอดึงข้อมูลของคุณ

บทความนี้แสดงวิธีการเปลี่ยนบทความ Microsoft Learn โดยใช้เครื่องมือภายในเครื่อง และเหมาะสําหรับผู้ร่วมสร้างที่ต้องการทําการเปลี่ยนแปลงที่สําคัญ หรือจะเป็นผู้สนับสนุนที่เก็บบ่อย โดยทั่วไปผู้สนับสนุนที่ใช้บ่อยจะมีการเปลี่ยนแปลงที่ดําเนินอยู่หรือใช้เวลานานผ่านวงจรการสร้าง/การตรวจสอบความถูกต้อง/การแบ่งระยะหรือครอบคลุมหลายวันก่อนที่จะลงชื่อออกในคําขอดึงข้อมูล (PR)

ตัวอย่างของชนิดของการจัดสรรเหล่านี้ได้แก่:

  • สร้างผลงานขนาดใหญ่ ตัวอย่างเช่น การจัดสรรของคุณ (เพิ่ม เปลี่ยนแปลง หรือลบ) อาจครอบคลุมหลายบทความ และจําเป็นต้องได้รับการบันทึกและทดสอบว่าเป็นงานหน่วยหนึ่งใน PR เดียว
  • สร้างและตีพิมพ์บทความใหม่ ซึ่งโดยทั่วไปจะต้องใช้ตัวแก้ไขภายในเครื่องที่มีประสิทธิภาพมากขึ้น
  • เพิ่มรูปภาพใหม่หรืออัปเดตรูปภาพ ซึ่งโดยปกติแล้วคุณจะต้องสร้างไดเรกทอรีย่อยใหม่ media สร้างไฟล์รูปภาพ อัปเดตลิงก์รูปภาพในบทความ และไฟล์ Markdown ตัวอย่างในตัวแก้ไขภายในเครื่องในเวลาเดียวกันเพื่อทดสอบการแสดงภาพ
  • อัปเดตบทความในช่วงหลายวันก่อนที่คุณจะตีพิมพ์ ในกรณีเหล่านี้ โดยทั่วไปแล้ว คุณจําเป็นต้องรวมการเปลี่ยนแปลงอื่นๆ ที่เกิดขึ้นในสาขาเริ่มต้นตามปกติ การรวมแบบนี้ทำได้ง่ายขึ้นด้วย Git Bash และการแก้ไขระดับท้องถิ่น นอกจากนี้ คุณยังเสี่ยงต่อการสูญเสียการแก้ไขของคุณหากคุณทําเช่นนี้ผ่านตัวแก้ไขเว็บ GitHub และรอก่อนที่คุณจะบันทึกการเปลี่ยนแปลง
  • ทําการอัปเดตบทความเดียวกันอย่างต่อเนื่องหลังจากเปิด PR แล้ว แม้ว่าคุณจะสามารถใช้ตัวแก้ไขเว็บ GitHub เพื่อวัตถุประสงค์นี้ได้ แต่คุณอาจสร้าง PR ที่โดดเด่นหลายรายการสําหรับไฟล์เดียวกันซึ่งอาจมีความขัดแย้งกันระหว่างกัน

ข้อกำหนดเบื้องต้น

สร้างและตรวจสอบสาขาการทํางานของคุณ

หากต้องการเริ่มต้น ให้สร้างสาขาการทํางานใหม่ในที่เก็บภายในเครื่องของคุณเพื่อจับการเปลี่ยนแปลงที่เสนอของคุณ สําหรับข้อมูลพื้นฐานเพิ่มเติมเกี่ยวกับสาขา ดู พื้นฐานของ Git และ GitHub

บทช่วยสอนนี้ใช้ Git Bash และ Visual Studio Code แต่คุณสามารถใช้ไคลเอ็นต์ Git และตัวแก้ไขที่คุณต้องการ

  1. ใน VS Code ให้เปิดโฟลเดอร์ที่เก็บข้อมูลของโคลนภายในเครื่องของคุณ จากเมนูไฟล์ เลือกเปิดโฟลเดอร์และนําทางไปยังโฟลเดอร์บนเครื่องของคุณ

  2. เลือก มุมมอง จากเมนูด้านบน จากนั้นเลือก เทอร์มินัล เพื่อเปิดเทอร์มินัลที่รวมอยู่

  3. ในเทอร์มินัลที่รวมกัน ตรวจสอบให้แน่ใจว่า คุณอยู่ในโฟลเดอร์ที่เก็บ

  4. ก่อนที่คุณจะสร้างสาขาการทํางาน ตรวจสอบให้แน่ใจว่าสาขาหลักในเครื่องของคุณเป็นปัจจุบันด้วยทุกอย่างในสาขาหลักของที่เก็บการผลิต งานนี้ช่วยให้มั่นใจได้ว่าสาขาการทํางานของคุณจะรวบรวมการเปลี่ยนแปลงใด ๆ ที่เกิดขึ้นในที่เก็บการผลิตตั้งแต่ครั้งสุดท้ายที่คุณซิงค์กับ repo

    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 ของ repo ผ่านตัวสํารวจไฟล์ (ไอคอนเอกสารในแถบด้านข้างด้านบนซ้าย) ตัวสํารวจไฟล์จะแสดงโครงสร้างโฟลเดอร์ของ repo และคุณสามารถนําทางไปยังไฟล์ที่คุณต้องการแก้ไข

ถ้าคุณไม่พบไฟล์ ไปที่บทความใน 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 UI เพื่อยืนยันและส่งการเปลี่ยนแปลงของคุณ

  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

คุณทำเสร็จแล้ว! ขณะนี้รหัสของคุณมีอยู่ในที่เก็บ GitHub ของคุณและพร้อมให้คุณเปิด PR

ต้องการแก้ไขบางสิ่งที่คุณส่งไปหรือไม่ ง่ายมากๆ เพียงทําซ้ําขั้นตอนข้างต้น โดยเริ่มต้นด้วย แก้ไขไฟล์ เพื่อทําการเปลี่ยนแปลงในสาขาเดียวกัน จากนั้นให้ยอมรับและส่งอีกครั้ง (ไม่จําเป็นต้องตั้งค่าเซิร์ฟเวอร์อัพสตรีมในการส่งในภายหลังของสาขาเดียวกัน) โดยทั่วไปแล้ว สาขาจะใช้เพื่อแยกสตรีมของงานคุณจึงไม่จําเป็นต้องสร้างสาขาใหม่เว้นแต่ว่าคุณพร้อมที่จะทํางานในสิ่งอื่น

ทําการเปลี่ยนแปลงครั้งต่อไปของคุณ

พร้อมที่จะทําการเปลี่ยนแปลงอื่น ที่ไม่เกี่ยวข้องกับสิ่งนี้หรือไม่ สลับกลับไปยังสาขาเริ่มต้น ดึงจากที่เก็บต้นทางเพื่ออัปเดตสําเนาของคุณ และตรวจสอบสาขาใหม่ เรียกใช้คำสั่งต่อไปนี้ใน Git Bash:

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

ตอนนี้คุณอยู่ในสาขาใหม่ที่เชื่อมโยงกับสาขาระยะไกลของคุณ แล้วคุณก็พร้อมที่จะทําการเปลี่ยนแปลงเพิ่มเติม คุณดีในแบบของคุณที่จะเป็นผู้สนับสนุนผู้เชี่ยวชาญ!

ขั้นตอนถัดไป

  • หากคุณทําตามขั้นตอนข้างต้นเสร็จแล้ว ในตอนนี้ก็ถึงเวลาที่จะต้อง เปิด PR เพื่อรับการเปลี่ยนแปลงของคุณที่ผสานเข้ากับสาขาหลักแล้ว
  • เมื่อต้องการเรียนรู้เพิ่มเติมเกี่ยวกับหัวข้อต่างๆ เช่น Markdown และไวยากรณ์ส่วนขยาย Markdown ให้ตรวจสอบ การอ้างอิง Markdown