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