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

หากคุณวางแผนที่จะเพิ่ม เปลี่ยนแปลง หรือนำฟีเจอร์ที่ผู้ใช้มองเห็นออก หรือทำการ เปลี่ยนแปลงสถาปัตยกรรมที่สำคัญกับ 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 คนเท่านั้น)
• สถานะปัจจุบัน (ฉบับร่าง อยู่ระหว่างตรวจสอบ ได้รับอนุมัติ ถูกปฏิเสธ อยู่ระหว่างการใช้งาน ใช้งานแล้ว)
• ลิงก์ไปยังกระทู้สนทนา (จะเพิ่มหลังจากประกาศ)

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

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

สร้างคำขอ Pull

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

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

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

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

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

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

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

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

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

อัปเดตสถานะ

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

หากต้องการยอมรับข้อเสนออย่างเป็นทางการ ผู้ตรวจสอบหลักจะอนุมัติคำขอ 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. เพิ่มความคิดเห็นลงในเอกสารเพื่ออธิบายเหตุผลที่การออกแบบไม่สามารถอนุมัติได้ในสถานะปัจจุบัน และระบุขั้นตอนถัดไป (หากมี) เช่น "กลับไปดูสมมติฐานที่ไม่ถูกต้องและส่งอีกครั้ง"