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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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