หากวางแผนที่จะเพิ่ม เปลี่ยนแปลง หรือนำฟีเจอร์ที่ผู้ใช้มองเห็นออก หรือทำการเปลี่ยนแปลงสถาปัตยกรรมที่สำคัญใน 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
เวิร์กโฟลว์ของ Contributor
ในฐานะผู้ร่วมให้ข้อมูล คุณสามารถเขียนเอกสารการออกแบบ ส่งคำขอผสานรวม และ ขอให้ผู้ตรวจสอบพิจารณาข้อเสนอของคุณ
เขียนเอกสารการออกแบบ
เอกสารการออกแบบทั้งหมดต้องมีส่วนหัวซึ่งประกอบด้วยข้อมูลต่อไปนี้
- ผู้เขียน
- วันที่เปลี่ยนแปลงครั้งล่าสุด
- รายชื่อผู้ตรวจสอบ รวมถึงหัวหน้าผู้ตรวจสอบ 1 คน (และมีได้เพียงคนเดียว)
- สถานะปัจจุบัน (ฉบับร่าง อยู่ระหว่างตรวจสอบ อนุมัติแล้ว ถูกปฏิเสธ กำลังดำเนินการ ดำเนินการแล้ว)
- ลิงก์ไปยังชุดข้อความสนทนา (จะเพิ่มหลังจากประกาศ)
คุณเขียนเอกสารเป็นเอกสาร Google ที่อ่านได้ทั่วโลก หรือใช้มาร์กดาวน์ก็ได้ อ่านข้อมูลด้านล่างเกี่ยวกับการเปรียบเทียบมาร์กดาวน์ / Google เอกสาร
ข้อเสนอที่มีผลกระทบที่ผู้ใช้มองเห็นได้ต้องมีส่วนที่บันทึกผลกระทบต่อความเข้ากันได้แบบย้อนหลัง (และแผนการเปิดตัวหากจำเป็น)
สร้างคำขอพุล
แชร์เอกสารการออกแบบโดยสร้างคำขอผสานรวม (PR) เพื่อเพิ่มเอกสารลงในดัชนีการออกแบบ เพิ่ม ไฟล์มาร์กดาวน์หรือลิงก์เอกสารไปยังคำขอส่งรวม (PR)
หากเป็นไปได้ ให้เลือกผู้ตรวจสอบนำ และส่งสำเนาถึงผู้ตรวจสอบคนอื่นๆ หากคุณไม่เลือกผู้ตรวจสอบนำ Bazel ผู้ดูแลจะกำหนดผู้ตรวจสอบนำให้กับ PR ของคุณ
หลังจากสร้างคำขอส่งรวมแล้ว ผู้ตรวจสอบจะแสดงความคิดเห็นเบื้องต้นได้ในระหว่างการตรวจสอบโค้ด เช่น ผู้วิจารณ์หลักสามารถแนะนำผู้วิจารณ์เพิ่มเติมหรือ ชี้ให้เห็นข้อมูลที่ขาดหายไป ผู้ตรวจสอบหลักจะอนุมัติ PR เมื่อเห็นว่ากระบวนการตรวจสอบสามารถเริ่มต้นได้ ซึ่งไม่ได้หมายความว่าข้อเสนอจะสมบูรณ์แบบ หรือจะได้รับอนุมัติ แต่หมายความว่าข้อเสนอมีข้อมูลเพียงพอที่จะ เริ่มการสนทนา
ประกาศข้อเสนอใหม่
ส่งประกาศไปยัง bazel-dev เมื่อ ส่ง PR
คุณอาจคัดลอกกลุ่มอื่นๆ (เช่น bazel-discuss เพื่อรับความคิดเห็นจากผู้ใช้ปลายทางของ Bazel)
ทำงานร่วมกับผู้ตรวจสอบ
ทุกคนที่สนใจจะแสดงความคิดเห็นในข้อเสนอของคุณได้ พยายามตอบคำถาม ชี้แจงข้อเสนอ และตอบข้อกังวล
การสนทนาควรเกิดขึ้นในเธรดประกาศ หากข้อเสนออยู่ใน Google เอกสาร คุณอาจใช้ความคิดเห็นแทนได้ (โปรดทราบว่าระบบอนุญาตให้แสดงความคิดเห็นแบบไม่ระบุตัวตน)
อัปเดตสถานะ
สร้างคำขอส่งการเปลี่ยนแปลงใหม่เพื่ออัปเดตสถานะของข้อเสนอเมื่อการทำซ้ำเสร็จสมบูรณ์ ส่งคำขอให้ตรวจสอบไปยังผู้ตรวจสอบนำคนเดิมและสำเนาถึงผู้ตรวจสอบคนอื่นๆ
หากต้องการยอมรับข้อเสนออย่างเป็นทางการ ผู้นำทีมตรวจสอบจะอนุมัติคำขอส่ง (PR) หลังจาก ตรวจสอบว่าผู้ตรวจสอบคนอื่นๆ เห็นด้วยกับการตัดสินใจ
ต้องมีระยะเวลาอย่างน้อย 1 สัปดาห์ระหว่างการประกาศครั้งแรกกับการอนุมัติ ข้อเสนอ ซึ่งจะช่วยให้ผู้ใช้มีเวลาเพียงพอในการอ่านเอกสารและ แชร์ข้อกังวล
คุณสามารถเริ่มติดตั้งใช้งานได้ก่อนที่จะยอมรับข้อเสนอ เช่น เป็น การพิสูจน์แนวคิดหรือการทดลอง อย่างไรก็ตาม คุณจะส่งการเปลี่ยนแปลงไม่ได้ จนกว่าการตรวจสอบจะเสร็จสมบูรณ์
การเลือกผู้ตรวจสอบนำ
นักรีวิวหลักควรเป็นผู้เชี่ยวชาญในโดเมนที่มีคุณสมบัติดังนี้
- มีความรู้เกี่ยวกับระบบย่อยที่เกี่ยวข้อง
- มีวัตถุประสงค์และสามารถให้ข้อเสนอแนะที่สร้างสรรค์ได้
- พร้อมให้บริการตลอดระยะเวลาการตรวจสอบเพื่อเป็นผู้นำในกระบวนการ
ลองตรวจสอบรายชื่อติดต่อเพื่อหาป้ายกำกับทีมต่างๆ
มาร์กดาวน์เทียบกับ Google เอกสาร
เลือกวิธีที่เหมาะกับคุณที่สุด เนื่องจากทั้ง 2 วิธีนี้ใช้ได้
ประโยชน์ของการใช้ Google เอกสาร
- มีประสิทธิภาพในการระดมความคิดเนื่องจากเริ่มต้นใช้งานได้ง่าย
- การแก้ไขร่วมกัน
- การทำซ้ำอย่างรวดเร็ว
- วิธีง่ายๆ ในการแนะนำให้แก้ไข
ประโยชน์ของการใช้ไฟล์มาร์กดาวน์มีดังนี้
- URL ที่เป็นระเบียบสำหรับการลิงก์
- บันทึกการแก้ไขที่ชัดเจน
- อย่าลืมตั้งค่าสิทธิ์การเข้าถึงก่อนเผยแพร่ลิงก์
- ค้นหาได้ง่ายด้วยเครื่องมือค้นหา
- พร้อมใช้งานในอนาคต: ข้อความธรรมดาไม่ได้ขึ้นอยู่กับเครื่องมือใดเครื่องมือหนึ่ง และไม่จำเป็นต้องเชื่อมต่ออินเทอร์เน็ต
- คุณสามารถอัปเดตได้แม้ว่าผู้เขียนจะไม่ได้ใช้งานแล้วก็ตาม
- ระบบจะประมวลผลโดยอัตโนมัติ (อัปเดต/ตรวจหาลิงก์ที่เสีย ดึงข้อมูล รายชื่อผู้เขียน ฯลฯ)
คุณสามารถเลือกที่จะทำซ้ำใน Google เอกสารก่อน แล้วค่อยแปลงเป็น Markdown เพื่อเก็บไว้ในภายหลัง
การใช้ Google เอกสาร
ใช้เทมเพลตเอกสารการออกแบบ Bazel เพื่อให้สอดคล้องกัน ซึ่งรวมถึงส่วนหัวที่จำเป็นและสร้างความสอดคล้องด้านภาพ กับเอกสารอื่นๆ ที่เกี่ยวข้องกับ Bazel โดยคลิกไฟล์ > ทำสำเนา หรือคลิกลิงก์นี้เพื่อทำสำเนาเทมเพลต เอกสารการออกแบบ
หากต้องการให้เอกสารอ่านได้ทั่วโลก ให้คลิก แชร์ > ขั้นสูง > เปลี่ยน… แล้ว เลือก "เปิด - ทุกคนที่มีลิงก์" หากอนุญาตให้แสดงความคิดเห็นในเอกสาร ทุกคนจะแสดงความคิดเห็นโดยไม่ระบุตัวตนได้ แม้จะไม่มีบัญชี Google ก็ตาม
การใช้มาร์กดาวน์
เอกสารจะจัดเก็บไว้ใน GitHub และใช้ รูปแบบ Markdown ของ GitHub (ข้อกำหนด)
สร้างคำขอให้ดึงข้อมูลเพื่ออัปเดตเอกสารที่มีอยู่ การเปลี่ยนแปลงที่สำคัญควรได้รับการตรวจสอบโดยผู้ตรวจสอบเอกสาร การเปลี่ยนแปลงเล็กน้อย (เช่น การสะกดผิด การจัดรูปแบบ) สามารถอนุมัติได้โดยทุกคน
เวิร์กโฟลว์ของผู้ตรวจสอบ
ผู้ตรวจสอบแสดงความคิดเห็น ตรวจสอบ และอนุมัติเอกสารการออกแบบ
ความรับผิดชอบทั่วไปของผู้ตรวจสอบ
คุณมีหน้าที่รับผิดชอบในการตรวจสอบเอกสารการออกแบบ ขอข้อมูลเพิ่มเติมหากจำเป็น และอนุมัติการออกแบบที่ผ่านกระบวนการตรวจสอบ
เมื่อคุณได้รับข้อเสนอใหม่
- ดูเอกสารอย่างรวดเร็ว
- แสดงความคิดเห็นหากมีข้อมูลสำคัญขาดหายไป หรือหากการออกแบบไม่สอดคล้องกับเป้าหมายของโปรเจ็กต์
- แนะนำผู้ตรวจสอบเพิ่มเติม
- อนุมัติ PR เมื่อพร้อมสำหรับการตรวจสอบ
ในระหว่างกระบวนการตรวจสอบ
- พูดคุยกับผู้เขียนการออกแบบเกี่ยวกับปัญหาที่ทำให้เกิดปัญหา หรือต้องมีการชี้แจง
- หากเหมาะสม ให้เชิญผู้ที่ไม่ได้เป็นผู้ตรวจสอบซึ่งควรทราบ การออกแบบมาแสดงความคิดเห็น
- ตัดสินใจว่าผู้เขียนต้องจัดการกับความคิดเห็นใดก่อนจึงจะ อนุมัติได้
- เขียนว่า "LGTM" (Looks Good To Me) ในเธรดการสนทนาเมื่อคุณพอใจกับสถานะปัจจุบันของข้อเสนอ
ทำตามกระบวนการนี้สำหรับคำขอตรวจสอบการออกแบบทั้งหมด อย่าอนุมัติการออกแบบ ที่มีผลต่อ Bazel หากไม่ได้อยู่ในดัชนีการออกแบบ
ความรับผิดชอบของผู้ตรวจสอบนำ
คุณมีหน้าที่รับผิดชอบในการตัดสินใจว่าจะดำเนินการตามการออกแบบที่รอดำเนินการหรือไม่ หากทำไม่ได้ คุณควรระบุ ผู้รับมอบสิทธิ์ที่เหมาะสม (มอบหมาย PR ให้ผู้รับมอบสิทธิ์อีกครั้ง) หรือมอบหมายข้อบกพร่องให้ ผู้จัดการ Bazel อีกครั้งเพื่อดำเนินการต่อไป
ในระหว่างกระบวนการตรวจสอบ
- ตรวจสอบว่ากระบวนการแสดงความคิดเห็นและการออกแบบซ้ำดำเนินไปอย่างสร้างสรรค์
- ก่อนที่จะได้รับอนุมัติ โปรดตรวจสอบว่าข้อกังวลจากผู้ตรวจสอบคนอื่นๆ ได้รับการแก้ไขแล้ว
หลังจากผู้ตรวจสอบทุกคนอนุมัติแล้ว
- โปรดตรวจสอบว่าประกาศใน รายชื่ออีเมลผ่านมาแล้วอย่างน้อย 1 สัปดาห์
- ตรวจสอบว่า PR อัปเดตสถานะ
- อนุมัติคำขอ Pull Request ที่ผู้เขียนข้อเสนอส่งมา
ปฏิเสธการออกแบบ
- ตรวจสอบว่าผู้เขียน PR ส่ง PR หรือส่ง PR ให้ผู้เขียน
- PR จะอัปเดตสถานะของเอกสาร
- เพิ่มความคิดเห็นในเอกสารเพื่ออธิบายสาเหตุที่อนุมัติการออกแบบในสถานะปัจจุบันไม่ได้ และระบุขั้นตอนถัดไป (หากมี เช่น "ทบทวนสมมติฐานที่ไม่ถูกต้องและส่งอีกครั้ง")