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