หากวางแผนที่จะเพิ่ม เปลี่ยนแปลง หรือนําฟีเจอร์ที่แสดงต่อผู้ใช้ออก หรือทําการเปลี่ยนแปลงสถาปัตยกรรมที่สําคัญใน Bazel คุณต้องต้องเขียนเอกสารการออกแบบและส่งให้ตรวจสอบก่อนจึงจะส่งการเปลี่ยนแปลงได้
ตัวอย่างการเปลี่ยนแปลงที่สําคัญมีดังนี้
- การเพิ่มหรือลบกฎการสร้างแบบดั้งเดิม
- การเปลี่ยนแปลงที่สำคัญเกี่ยวกับกฎของเนทีฟ
- การเปลี่ยนแปลงความหมายของกฎการสร้างแบบเนทีฟที่ส่งผลต่อลักษณะการทํางานของกฎมากกว่า 1 รายการ
- การเปลี่ยนแปลง API คำจำกัดความของกฎของ Bazel
- การเปลี่ยนแปลง API ที่ Bazel ใช้เพื่อเชื่อมต่อกับระบบอื่นๆ
- การเปลี่ยนแปลงภาษา Starlark, ความหมาย หรือ API
- การเปลี่ยนแปลงที่อาจส่งผลต่อประสิทธิภาพหรือการใช้หน่วยความจำของ Bazel อย่างมาก (ไม่ว่าจะดีขึ้นหรือแย่ลง)
- การเปลี่ยนแปลง API ภายในที่ใช้กันอย่างแพร่หลาย
- การเปลี่ยนแปลงเกี่ยวกับ Flag และอินเทอร์เฟซบรรทัดคำสั่ง
เหตุผลในการตรวจสอบการออกแบบ
เมื่อเขียนเอกสารการออกแบบ คุณสามารถประสานงานกับนักพัฒนาซอฟต์แวร์ Bazel คนอื่นๆ และขอคำแนะนำจากทีมหลักของ Bazel เช่น เมื่อการเสนอเพิ่ม นำออก หรือแก้ไขฟังก์ชันหรือออบเจ็กต์ที่มีอยู่ในไฟล์ BUILD, MODULE.bazel หรือ bzl ให้เพิ่มทีม Starlark เป็นผู้ตรวจสอบ เอกสารการออกแบบจะได้รับการตรวจสอบก่อนส่งเนื่องจากเหตุผลต่อไปนี้
- Bazel เป็นระบบที่ซับซ้อนมาก การเปลี่ยนแปลงในเครื่องที่ดูเหมือนจะไม่เป็นอันตรายอาจส่งผลร้ายแรงทั่วโลก
- ทีมได้รับคำขอฟีเจอร์จากผู้ใช้จำนวนมาก คำขอดังกล่าวต้องได้รับการประเมินไม่เพียงว่ามีความเป็นไปได้ทางเทคนิคเพียงอย่างเดียว แต่ยังต้องประเมินความสำคัญเมื่อเทียบกับคำขอฟีเจอร์อื่นๆ ด้วย
- ผู้ใช้ภายนอกทีมหลักมักจะนำฟีเจอร์ของ Bazel ไปใช้ โดยผู้มีส่วนร่วมเหล่านี้มีความเชี่ยวชาญด้าน Bazel ในหลากหลายระดับ
- ทีม Bazel เองก็มีความเชี่ยวชาญในระดับที่แตกต่างกัน สมาชิกในทีมไม่มีคนใดที่เข้าใจ Bazel อย่างถ่องแท้
- การเปลี่ยนแปลง Bazel ต้องคำนึงถึงความเข้ากันได้แบบย้อนหลังและหลีกเลี่ยงการเปลี่ยนแปลงที่ทำให้เกิดข้อขัดข้อง
นโยบายการตรวจสอบการออกแบบของ Bazel จะช่วยเพิ่มโอกาสให้สิ่งต่อไปนี้เกิดขึ้นมากที่สุด
- คำขอฟีเจอร์ทั้งหมดจะได้รับการตรวจสอบในระดับพื้นฐาน
- บุคคลที่เหมาะสมจะพิจารณาการออกแบบก่อนที่จะลงทุนในการใช้งานที่อาจไม่ได้ผล
โปรดดูเอกสารการออกแบบในที่เก็บโปรเจ็กต์ Bazel เพื่อช่วยในการเริ่มต้นใช้งาน การออกแบบเป็นงานที่อยู่ระหว่างดำเนินการ ดังนั้นรายละเอียดการใช้งานจึงอาจมีการเปลี่ยนแปลงเมื่อเวลาผ่านไปและตามความคิดเห็นที่ได้รับ เอกสารการออกแบบที่เผยแพร่จะบันทึกการออกแบบขั้นต้น และไม่ใช่การเปลี่ยนแปลงที่เกิดขึ้นอย่างต่อเนื่องเมื่อนำการออกแบบไปใช้งาน โปรดไปที่เอกสารประกอบเพื่อดูคำอธิบายฟังก์ชันการทำงานของ Bazel ปัจจุบันเสมอ
เวิร์กโฟลว์สำหรับผู้มีส่วนร่วม
ในฐานะผู้มีส่วนร่วม คุณสามารถเขียนเอกสารการออกแบบ ส่งคำขอดึง และขอให้ผู้ตรวจสอบตรวจสอบข้อเสนอของคุณได้
เขียนเอกสารการออกแบบ
เอกสารการออกแบบทั้งหมดต้องมีส่วนหัวที่มีข้อมูลต่อไปนี้
- ผู้เขียน
- วันที่เกิดการเปลี่ยนแปลงครั้งใหญ่ครั้งล่าสุด
- รายชื่อผู้ตรวจสอบ ซึ่งรวมถึงผู้ตรวจสอบหลัก 1 คน (เพียงคนเดียว)
- สถานะปัจจุบัน (ฉบับร่าง อยู่ระหว่างตรวจสอบ อนุมัติแล้ว ถูกปฏิเสธ อยู่ระหว่างใช้งาน ใช้งานแล้ว)
- ลิงก์ไปยังชุดข้อความสนทนา (จะเพิ่มหลังจากประกาศ)
เอกสารจะเขียนเป็น Google เอกสารที่ทุกคนอ่านได้หรือใช้ Markdown ก็ได้ อ่านการเปรียบเทียบ Markdown กับ Google เอกสารได้ที่ด้านล่าง
โปรเจ็กต์ที่ส่งผลต่อผู้ใช้ต้องมีส่วนแสดงผลกระทบต่อความเข้ากันได้แบบย้อนหลัง (และแผนการเปิดตัว หากจำเป็น)
สร้างคำขอดึงข้อมูล
แชร์เอกสารการออกแบบโดยสร้างคำขอดึงข้อมูล (PR) เพื่อเพิ่มเอกสารลงในดัชนีการออกแบบ เพิ่มไฟล์ Markdown หรือลิงก์เอกสารลงใน PR
เลือกผู้ตรวจสอบหลักหากเป็นไปได้ และส่งสำเนาถึงผู้ตรวจสอบคนอื่นๆ หากคุณไม่ได้เลือกผู้ตรวจสอบหลัก ผู้ดูแล Bazel จะเป็นผู้กำหนดผู้ตรวจสอบหลักให้กับ PR ของคุณ
หลังจากสร้าง PR แล้ว ผู้ตรวจสอบจะแสดงความคิดเห็นเบื้องต้นระหว่างการตรวจสอบโค้ดได้ เช่น ผู้ตรวจสอบหลักสามารถแนะนำผู้ตรวจสอบคนอื่นๆ หรือชี้ให้เห็นข้อมูลที่ขาดหายไป ผู้ตรวจสอบระดับอาวุโสจะอนุมัติ PR เมื่อเชื่อว่ากระบวนการตรวจสอบจะเริ่มได้ สถานะนี้ไม่ได้หมายความว่าข้อเสนอสมบูรณ์แบบหรือจะได้รับอนุมัติ แต่หมายความว่าข้อเสนอมีข้อมูลเพียงพอที่จะเริ่มต้นการสนทนา
ประกาศข้อเสนอใหม่
ส่งประกาศไปยัง bazel-dev เมื่อส่ง PR แล้ว
คุณสามารถคัดลอกกลุ่มอื่นๆ ได้ (เช่น bazel-discuss เพื่อรับความคิดเห็นจากผู้ใช้ปลายทางของ Bazel)
ตรวจสอบกับผู้ตรวจสอบ
ทุกคนที่สนใจสามารถแสดงความคิดเห็นเกี่ยวกับข้อเสนอของคุณได้ พยายามตอบคําถาม ชี้แจงข้อเสนอ และแก้ไขข้อกังวล
การพูดคุยควรเกิดขึ้นในชุดข้อความประกาศ หากข้อเสนออยู่ใน Google เอกสาร ก็อาจใช้ความคิดเห็นแทน (โปรดทราบว่าระบบอนุญาตให้แสดงความคิดเห็นแบบไม่ระบุตัวตนได้)
อัปเดตสถานะ
สร้าง PR ใหม่เพื่ออัปเดตสถานะของข้อเสนอเมื่อการปรับปรุงเสร็จสมบูรณ์ ส่ง PR ไปยังผู้ตรวจสอบหลักคนเดิมและส่งสำเนาถึงผู้ตรวจสอบคนอื่นๆ
หากต้องการยอมรับข้อเสนออย่างเป็นทางการ ผู้ตรวจสอบระดับหัวหน้าต้องอนุมัติ PR หลังจากที่ตรวจสอบว่าผู้ตรวจสอบคนอื่นๆ เห็นด้วยกับการตัดสินใจแล้ว
คุณต้องเว้นระยะเวลาอย่างน้อย 1 สัปดาห์ระหว่างการประกาศครั้งแรกกับการอนุมัติข้อเสนอ ซึ่งจะช่วยให้ผู้ใช้มีเวลาเพียงพอในการอ่านเอกสารและแชร์ข้อกังวล
การติดตั้งใช้งานสามารถเริ่มได้ก่อนที่ข้อเสนอจะได้รับอนุมัติ เช่น เป็นการพิสูจน์แนวคิดหรือการทดสอบ อย่างไรก็ตาม คุณจะส่งการเปลี่ยนแปลงไม่ได้จนกว่าการตรวจสอบจะเสร็จสมบูรณ์
การเลือกผู้ตรวจสอบหลัก
ผู้รีวิวหลักควรเป็นผู้เชี่ยวชาญด้านโดเมนที่มีคุณสมบัติดังนี้
- มีความรู้เกี่ยวกับระบบย่อยที่เกี่ยวข้อง
- เป็นกลางและให้ความคิดเห็นที่สร้างสรรค์
- พร้อมให้บริการตลอดระยะเวลาการตรวจสอบเพื่อนำกระบวนการ
ลองตรวจสอบรายชื่อติดต่อเพื่อหาป้ายกำกับทีมต่างๆ
Markdown กับ Google เอกสาร
โปรดเลือกวิธีที่เหมาะกับคุณที่สุด เนื่องจากระบบยอมรับทั้ง 2 วิธี
ประโยชน์ของการใช้ Google เอกสาร
- มีประสิทธิภาพในการระดมความคิดเนื่องจากเริ่มต้นใช้งานได้ง่ายๆ
- การแก้ไขแบบร่วมมือ
- การทำซ้ำอย่างรวดเร็ว
- วิธีแนะนำการแก้ไขที่ง่ายดาย
ประโยชน์ของการใช้ไฟล์มาร์กดาวน์
- URL ที่เป็นระเบียบสำหรับการลิงก์
- บันทึกการแก้ไขที่ชัดเจน
- อย่าลืมตั้งค่าสิทธิ์เข้าถึงก่อนเผยแพร่ลิงก์
- ค้นหาได้ง่ายด้วยเครื่องมือค้นหา
- ใช้ได้ในอนาคต: ข้อความธรรมดาไม่จําเป็นต้องใช้เครื่องมือใดๆ โดยเฉพาะและไม่ต้องเชื่อมต่ออินเทอร์เน็ต
- คุณสามารถอัปเดตได้แม้ว่าผู้เขียนจะไม่ได้อยู่อีกต่อไป
- โดยระบบจะประมวลผลโดยอัตโนมัติ (อัปเดต/ตรวจหาลิงก์ที่ใช้งานไม่ได้ ดึงข้อมูลรายชื่อผู้แต่ง ฯลฯ)
คุณเลือกที่จะแก้ไขใน Google เอกสารก่อน แล้วแปลงเป็น Markdown เพื่อเก็บไว้ใช้อ้างอิงในอนาคตได้
การใช้ Google เอกสาร
ใช้เทมเพลตเอกสารการออกแบบ Bazel เพื่อให้สอดคล้องกัน โดยจะมีส่วนหัวที่จำเป็นและสร้างความสอดคล้องของภาพกับเอกสารอื่นๆ ที่เกี่ยวข้องกับ Bazel โดยคลิกไฟล์ > ทําสําเนา หรือคลิกลิงก์นี้เพื่อทําสําเนาเทมเพลตเอกสารการออกแบบ
หากต้องการให้ทุกคนอ่านเอกสารได้ ให้คลิกแชร์ > ขั้นสูง > เปลี่ยน… แล้วเลือก "เปิด - ทุกคนที่มีลิงก์" หากคุณอนุญาตให้แสดงความคิดเห็นในเอกสาร ทุกคนจะแสดงความคิดเห็นแบบไม่ระบุตัวตนได้ แม้จะไม่มีบัญชี Google ก็ตาม
การใช้ Markdown
เอกสารจะจัดเก็บไว้ใน GitHub และใช้ Markdown รูปแบบ GitHub (ข้อกำหนด)
สร้าง PR เพื่ออัปเดตเอกสารที่มีอยู่ ผู้ตรวจสอบเอกสารควรตรวจสอบการเปลี่ยนแปลงที่สำคัญ การเปลี่ยนแปลงเล็กน้อย (เช่น การพิมพ์ผิด การจัดรูปแบบ) จะอนุมัติได้โดยทุกคน
เวิร์กโฟลว์ของผู้ตรวจสอบ
ผู้ตรวจสอบจะแสดงความคิดเห็น ตรวจสอบ และอนุมัติเอกสารการออกแบบ
ความรับผิดชอบของผู้ตรวจสอบทั่วไป
คุณมีหน้าที่ตรวจสอบเอกสารการออกแบบ ขอข้อมูลเพิ่มเติมหากจำเป็น และอนุมัติการออกแบบที่ผ่านกระบวนการตรวจสอบ
เมื่อคุณได้รับข้อเสนอใหม่
- มาดูเอกสารกันอย่างรวดเร็ว
- แสดงความคิดเห็นหากขาดข้อมูลสำคัญ หรือการออกแบบไม่สอดคล้องกับเป้าหมายของโปรเจ็กต์
- แนะนำผู้ตรวจสอบเพิ่มเติม
- อนุมัติ PR เมื่อพร้อมสําหรับการตรวจสอบ
ในระหว่างกระบวนการตรวจสอบ
- พูดคุยกับผู้เขียนการออกแบบเกี่ยวกับปัญหาที่พบหรือต้องการคำชี้แจง
- หากเหมาะสม ให้เชิญให้บุคคลที่ไม่ใช่ผู้รีวิวซึ่งควรทราบเกี่ยวกับการออกแบบแสดงความคิดเห็น
- ตัดสินใจว่าผู้เขียนต้องจัดการกับความคิดเห็นใดบ้าง ซึ่งเป็นข้อกําหนดเบื้องต้นในการอนุมัติ
- เขียนว่า "LGTM" (Looks Good To Me) ในชุดข้อความสนทนาเมื่อคุณพอใจกับสถานะปัจจุบันของข้อเสนอ
ทำตามกระบวนการนี้สำหรับคำขอตรวจสอบการออกแบบทั้งหมด อย่าอนุมัติการออกแบบที่ส่งผลต่อ Bazel หากไม่ได้อยู่ในดัชนีการออกแบบ
ความรับผิดชอบของผู้ตรวจสอบระดับอาวุโส
คุณมีหน้าที่ตัดสินใจว่าจะใช้งานการออกแบบที่รอดำเนินการหรือไม่ หากดำเนินการไม่ได้ คุณควรระบุผู้รับมอบสิทธิ์ที่เหมาะสม (มอบหมาย PR ให้ผู้รับมอบสิทธิ์อีกครั้ง) หรือมอบหมายข้อบกพร่องให้ผู้จัดการ Bazel เพื่อดำเนินการต่อ
ในระหว่างกระบวนการตรวจสอบ
- ตรวจสอบว่ากระบวนการแสดงความคิดเห็นและการปรับปรุงการออกแบบเดินหน้าไปอย่างสร้างสรรค์
- ก่อนได้รับอนุมัติ โปรดตรวจสอบว่าข้อกังวลจากผู้ตรวจสอบรายอื่นได้รับการแก้ไขแล้ว
หลังจากผู้ตรวจสอบทุกคนอนุมัติแล้ว
- ตรวจสอบว่าผ่านไปอย่างน้อย 1 สัปดาห์นับตั้งแต่การประกาศในจดหมายข่าว
- ตรวจสอบว่า PR อัปเดตสถานะแล้ว
- อนุมัติการเผยแพร่ข่าวที่ส่งโดยผู้เขียนข้อเสนอ
การปฏิเสธการออกแบบ
- ตรวจสอบว่าผู้เขียนฝ่ายประชาสัมพันธ์ส่งข่าวประชาสัมพันธ์ หรือส่งข่าวประชาสัมพันธ์ให้
- PR จะอัปเดตสถานะของเอกสาร
- เพิ่มความคิดเห็นในเอกสารที่อธิบายสาเหตุที่การออกแบบไม่ได้รับอนุมัติในสถานะปัจจุบัน และระบุขั้นตอนถัดไป (หากมี) (เช่น "ตรวจสอบสมมติฐานที่ไม่ถูกต้องอีกครั้งและส่งอีกครั้ง")