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