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

รายงานปัญหา ดูแหล่งที่มา

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

สร้างการประชาสัมพันธ์เพื่ออัปเดตเอกสารที่มีอยู่ การเปลี่ยนแปลงที่สำคัญควรได้รับการตรวจสอบ โดยผู้ตรวจสอบเอกสาร ทุกคนมีสิทธิ์อนุมัติการเปลี่ยนแปลงเล็กๆ น้อยๆ (เช่น การพิมพ์ผิด การจัดรูปแบบ)

เวิร์กโฟลว์ของผู้รีวิว

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

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

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

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

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

ระหว่างขั้นตอนการตรวจสอบ

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

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

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

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

ระหว่างขั้นตอนการตรวจสอบ

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

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

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

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

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