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