เอกสารการออกแบบ

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

ตัวอย่างการเปลี่ยนแปลงที่สำคัญมีดังนี้

• การเพิ่มหรือลบกฎการสร้างเนทีฟ
• การเปลี่ยนแปลงที่ทำให้กฎเนทีฟใช้งานไม่ได้
• การเปลี่ยนแปลงความหมายของกฎการสร้างเนทีฟที่ส่งผลต่อลักษณะการทำงานของกฎมากกว่า 1 ข้อ
• การเปลี่ยนแปลง API คำจำกัดความของกฎของ Bazel
• การเปลี่ยนแปลง API ที่ Bazel ใช้เพื่อเชื่อมต่อกับระบบอื่นๆ
• การเปลี่ยนแปลงภาษา ความหมาย หรือ API ของ Starlark
• การเปลี่ยนแปลงที่อาจส่งผลกระทบอย่างกว้างขวางต่อประสิทธิภาพหรือการใช้หน่วยความจำของ Bazel (ไม่ว่าจะในทางที่ดีขึ้นหรือแย่ลง)
• การเปลี่ยนแปลง API ภายในที่ใช้กันอย่างแพร่หลาย
• การเปลี่ยนแปลงแฟล็กและอินเทอร์เฟซบรรทัดคำสั่ง

เหตุผลที่ต้องมีการตรวจสอบการออกแบบ

เมื่อเขียนเอกสารการออกแบบ คุณสามารถประสานงานกับนักพัฒนา Bazel คนอื่นๆ และขอคำแนะนำจากทีมหลักของ Bazel ได้ ตัวอย่างเช่น เมื่อข้อเสนอเพิ่ม นำออก หรือแก้ไขฟังก์ชันหรือออบเจ็กต์ใดๆ ที่มีอยู่ในไฟล์ BUILD, MODULE.bazel หรือ bzl ให้เพิ่มทีม Starlark เป็นผู้ตรวจสอบ เอกสารการออกแบบจะได้รับการตรวจสอบก่อนส่งเนื่องจากเหตุผลต่อไปนี้

• Bazel เป็นระบบที่ซับซ้อนมาก การเปลี่ยนแปลงในเครื่องที่ดูเหมือนไม่มีพิษภัยอาจส่งผลกระทบอย่างมากในระดับโลก
• ทีมได้รับคำขอฟีเจอร์มากมายจากผู้ใช้ ซึ่งคำขอเหล่านี้ต้องได้รับการประเมินไม่เพียงแต่ในด้านความเป็นไปได้ทางเทคนิคเท่านั้น แต่ยังต้องพิจารณาถึงความสำคัญเมื่อเทียบกับคำขอฟีเจอร์อื่นๆ ด้วย
• ฟีเจอร์ของ Bazel มักได้รับการพัฒนาโดยบุคคลภายนอกทีมหลัก ซึ่งผู้มีส่วนร่วมเหล่านี้มีความเชี่ยวชาญใน Bazel ในระดับที่แตกต่างกันอย่างมาก
• ทีม Bazel เองก็มีความเชี่ยวชาญในระดับที่แตกต่างกัน ไม่มีสมาชิกในทีมคนใดคนหนึ่งที่เข้าใจทุกแง่มุมของ Bazel อย่างสมบูรณ์
• การเปลี่ยนแปลง Bazel ต้องคำนึงถึงความเข้ากันได้แบบย้อนหลังและหลีกเลี่ยงการเปลี่ยนแปลงที่ทำให้ระบบใช้งานไม่ได้

นโยบายการตรวจสอบการออกแบบของ Bazel ช่วยเพิ่มโอกาสที่

• คำขอฟีเจอร์ทั้งหมดจะได้รับการตรวจสอบในระดับพื้นฐาน
• ผู้ที่เหมาะสมจะแสดงความคิดเห็นเกี่ยวกับการออกแบบก่อนที่เราจะลงทุนในการพัฒนาที่อาจไม่ได้ผล

หากต้องการเริ่มต้นใช้งาน โปรดดูเอกสารการออกแบบใน ที่เก็บข้อเสนอของ Bazel การออกแบบเป็นงานที่อยู่ระหว่างดำเนินการ ดังนั้นรายละเอียดการพัฒนาจึงอาจเปลี่ยนแปลงไปตามเวลาและตามความคิดเห็น เอกสารการออกแบบที่เผยแพร่จะแสดงการออกแบบเริ่มต้น ไม่ใช่การเปลี่ยนแปลงที่เกิดขึ้นอย่างต่อเนื่องขณะที่การออกแบบได้รับการพัฒนา โปรดดูคำอธิบายฟังก์ชันการทำงานปัจจุบันของ Bazel ในเอกสารประกอบเสมอ

เวิร์กโฟลว์ของผู้มีส่วนร่วม

ในฐานะผู้มีส่วนร่วม คุณสามารถเขียนเอกสารการออกแบบ ส่งคำขอ Pull และขอผู้ตรวจสอบสำหรับข้อเสนอของคุณได้

เขียนเอกสารการออกแบบ

เอกสารการออกแบบทั้งหมดต้องมีส่วนหัวซึ่งประกอบด้วยข้อมูลต่อไปนี้

• ผู้เขียน
• วันที่ที่มีการเปลี่ยนแปลงครั้งสำคัญล่าสุด
• รายชื่อผู้ตรวจสอบ ซึ่งรวมถึงผู้ตรวจสอบหลัก 1 คน (และมีได้เพียง 1 คนเท่านั้น) lead reviewer
• สถานะปัจจุบัน (ฉบับร่าง อยู่ระหว่างตรวจสอบ อนุมัติแล้ว ถูกปฏิเสธ อยู่ระหว่างการพัฒนา พัฒนาแล้ว)
• ลิงก์ไปยังกระทู้สนทนา (จะเพิ่มหลังจากประกาศ)

คุณสามารถเขียนเอกสารเป็น Google เอกสารที่ทุกคนอ่านได้ หรือ ใช้มาร์กดาวน์ก็ได้ โปรดอ่านข้อมูลด้านล่างเพื่อดูการเปรียบเทียบ มาร์กดาวน์กับ Google เอกสาร

ข้อเสนอที่ส่งผลกระทบต่อผู้ใช้ต้องมีส่วนที่ระบุผลกระทบต่อความเข้ากันได้แบบย้อนหลัง (และแผนการเปิดตัวหากจำเป็น)

สร้างคำขอ Pull

แชร์เอกสารการออกแบบโดยสร้าง Pull Request (PR) เพื่อเพิ่มเอกสารลงใน ดัชนีการออกแบบ เพิ่มไฟล์มาร์กดาวน์หรือลิงก์เอกสารลงในคำขอ Pull

เลือกผู้ตรวจสอบหลักและเพิ่มผู้ตรวจสอบคนอื่นๆ เป็นผู้รับสำเนา (CC) หากเป็นไปได้ หากคุณไม่ได้เลือกผู้ตรวจสอบหลัก ผู้ดูแล Bazel จะกำหนดผู้ตรวจสอบหลักให้กับคำขอ Pull ของคุณ

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

ประกาศข้อเสนอใหม่

ส่งประกาศไปยัง bazel-dev เมื่อ ส่งคำขอ Pull

คุณสามารถคัดลอกกลุ่มอื่นๆ (เช่น bazel-discuss ) เพื่อรับความคิดเห็นจากผู้ใช้ปลายทางของ Bazel

ทำซ้ำกับผู้ตรวจสอบ

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

การสนทนาควรเกิดขึ้นในกระทู้ประกาศ หากข้อเสนออยู่ใน Google เอกสาร คุณสามารถใช้ความคิดเห็นแทนได้ (โปรดทราบว่าระบบอนุญาตให้แสดงความคิดเห็นแบบไม่ระบุชื่อ)

อัปเดตสถานะ

สร้างคำขอ Pull ใหม่เพื่ออัปเดตสถานะของข้อเสนอเมื่อการทำซ้ำเสร็จสมบูรณ์ ส่งคำขอ Pull ไปยังผู้ตรวจสอบหลักคนเดิมและเพิ่มผู้ตรวจสอบคนอื่นๆ เป็นผู้รับสำเนา (CC)

หากต้องการยอมรับข้อเสนออย่างเป็นทางการ ผู้ตรวจสอบหลักจะอนุมัติคำขอ Pull หลังจากตรวจสอบว่าผู้ตรวจสอบคนอื่นๆ เห็นด้วยกับการตัดสินใจ

ต้องมีระยะเวลาอย่างน้อย 1 สัปดาห์ระหว่างการประกาศครั้งแรกกับการอนุมัติข้อเสนอ เพื่อให้ผู้ใช้มีเวลาเพียงพอในการอ่านเอกสารและแชร์ข้อกังวล

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

การเลือกผู้ตรวจสอบหลัก

ผู้ตรวจสอบหลักควรเป็นผู้เชี่ยวชาญในโดเมนซึ่งมีคุณสมบัติดังนี้

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

โปรดตรวจสอบรายชื่อติดต่อสำหรับป้ายกำกับทีมต่างๆ

มาร์กดาวน์เทียบกับ Google เอกสาร

เลือกสิ่งที่เหมาะกับคุณที่สุด เนื่องจากระบบยอมรับทั้ง 2 รูปแบบ

ข้อดีของการใช้ Google เอกสาร

• มีประสิทธิภาพสำหรับการระดมความคิด เนื่องจากเริ่มต้นใช้งานได้ง่าย
• การแก้ไขร่วมกัน
• การทำซ้ำอย่างรวดเร็ว
• วิธีแนะนำการแก้ไขที่ง่าย

ข้อดีของการใช้ไฟล์มาร์กดาวน์

• URL ที่เป็นระเบียบสำหรับการลิงก์
• บันทึกการแก้ไขที่ชัดเจน
• ไม่ต้องกังวลว่าจะลืมตั้งค่าสิทธิ์เข้าถึงก่อนเผยแพร่ลิงก์
• ค้นหาได้ง่ายด้วยเครื่องมือค้นหา
• รองรับการใช้งานในอนาคต: ข้อความธรรมดาไม่ได้ขึ้นอยู่กับเครื่องมือใดเครื่องมือหนึ่งและไม่จำเป็นต้องเชื่อมต่ออินเทอร์เน็ต
• คุณสามารถอัปเดตข้อความได้แม้ว่าผู้เขียนจะไม่อยู่แล้วก็ตาม
• ระบบสามารถประมวลผลข้อความได้โดยอัตโนมัติ (อัปเดต/ตรวจหาลิงก์เสีย ดึงรายชื่อผู้เขียน ฯลฯ)

คุณสามารถเลือกที่จะทำซ้ำใน Google เอกสารก่อน แล้วจึงแปลงเป็นมาร์กดาวน์เพื่อเก็บไว้ในภายหลัง

การใช้ Google เอกสาร

ใช้เทมเพลตเอกสารการออกแบบของ Bazel เพื่อให้สอดคล้องกัน เทมเพลตนี้มีส่วนหัวที่จำเป็นและสร้างความสอดคล้องด้านภาพกับเอกสารอื่นๆ ที่เกี่ยวข้องกับ Bazel

หากต้องการให้เอกสารอ่านได้สำหรับทุกคน ให้คลิก แชร์ > ขั้นสูง > เปลี่ยน... แล้ว เลือก "เปิด - ทุกคนที่มีลิงก์" หากคุณอนุญาตให้แสดงความคิดเห็นในเอกสาร ทุกคนจะแสดงความคิดเห็นแบบไม่ระบุชื่อได้ แม้ว่าจะไม่มีบัญชี Google ก็ตาม

การใช้มาร์กดาวน์

เอกสารจะจัดเก็บไว้ใน GitHub และใช้ มาร์กดาวน์เวอร์ชัน GitHub (ข้อกำหนดเฉพาะ)

สร้างคำขอ Pull เพื่ออัปเดตเอกสารที่มีอยู่ การเปลี่ยนแปลงที่สำคัญควรได้รับการตรวจสอบโดยผู้ตรวจสอบเอกสาร ทุกคนสามารถอนุมัติการเปลี่ยนแปลงเล็กน้อย (เช่น การพิมพ์ผิด การจัดรูปแบบ) ได้

เวิร์กโฟลว์ของผู้ตรวจสอบ

ผู้ตรวจสอบจะแสดงความคิดเห็น ตรวจสอบ และอนุมัติเอกสารการออกแบบ

ความรับผิดชอบทั่วไปของผู้ตรวจสอบ

คุณมีหน้าที่รับผิดชอบในการตรวจสอบเอกสารการออกแบบ ขอข้อมูลเพิ่มเติมหากจำเป็น และอนุมัติการออกแบบที่ผ่านกระบวนการตรวจสอบ

เมื่อได้รับข้อเสนอใหม่

1. ดูเอกสารอย่างรวดเร็ว
2. แสดงความคิดเห็นหากมีข้อมูลสำคัญขาดหายไป หรือหากการออกแบบไม่สอดคล้องกับเป้าหมายของโปรเจ็กต์
3. แนะนำผู้ตรวจสอบเพิ่มเติม
4. อนุมัติคำขอ Pull เมื่อพร้อมสำหรับการตรวจสอบ

ระหว่างกระบวนการตรวจสอบ

1. พูดคุยกับผู้เขียนการออกแบบเกี่ยวกับปัญหาที่อาจเกิดขึ้นหรือต้องมีการชี้แจง
2. เชิญผู้ที่ไม่ใช่ผู้ตรวจสอบซึ่งควรทราบการออกแบบให้แสดงความคิดเห็น หากเหมาะสม
3. ตัดสินใจว่าผู้เขียนต้องแก้ไขความคิดเห็นใดบ้างก่อนที่จะอนุมัติ
4. เขียน "LGTM" (Looks Good To Me) ในชุดข้อความสนทนาเมื่อคุณพอใจกับสถานะปัจจุบันของข้อเสนอ

ทำตามกระบวนการนี้สำหรับคำขอตรวจสอบการออกแบบทั้งหมด อย่าอนุมัติการออกแบบ ที่ส่งผลต่อ Bazel หากการออกแบบนั้นไม่ได้อยู่ใน ดัชนีการออกแบบ

ความรับผิดชอบของผู้ตรวจสอบหลัก

คุณมีหน้าที่รับผิดชอบในการตัดสินใจว่าจะดำเนินการหรือไม่ดำเนินการพัฒนาการออกแบบที่รอดำเนินการ หากคุณไม่สามารถดำเนินการนี้ได้ คุณควรระบุผู้รับมอบหมายที่เหมาะสม (มอบหมายคำขอ Pull ให้ผู้รับมอบหมาย) หรือมอบหมายข้อบกพร่องให้กับผู้จัดการ Bazel เพื่อดำเนินการต่อไป

ระหว่างกระบวนการตรวจสอบ

1. ตรวจสอบว่ากระบวนการแสดงความคิดเห็นและการทำซ้ำการออกแบบดำเนินไปอย่างสร้างสรรค์
2. ตรวจสอบว่าข้อกังวลจากผู้ตรวจสอบคนอื่นๆ ได้รับการแก้ไขแล้วก่อนที่จะอนุมัติ

หลังจากผู้ตรวจสอบทุกคนอนุมัติแล้ว

1. ตรวจสอบว่ามีการประกาศในรายชื่ออีเมลอย่างน้อย 1 สัปดาห์แล้ว
2. ตรวจสอบว่าคำขอ Pull อัปเดตสถานะแล้ว
3. อนุมัติคำขอ Pull ที่ส่งโดยผู้เขียนข้อเสนอ

การปฏิเสธการออกแบบ

1. ตรวจสอบว่าผู้เขียนคำขอ Pull ส่งคำขอ Pull แล้ว หรือส่งคำขอ Pull ให้ผู้เขียน
2. คำขอ Pull อัปเดตสถานะของเอกสาร
3. เพิ่มความคิดเห็นลงในเอกสารเพื่ออธิบายเหตุผลที่การออกแบบไม่สามารถอนุมัติได้ในสถานะปัจจุบัน และระบุขั้นตอนถัดไป (หากมี) เช่น "กลับไปดูสมมติฐานที่ไม่ถูกต้องและส่งอีกครั้ง"