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

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

ตัวอย่างของการเปลี่ยนแปลงที่สำคัญมีดังนี้

• การเพิ่มหรือการลบกฎบิลด์เนทีฟ
• การเปลี่ยนแปลงกฎโฆษณาเนทีฟ
• การเปลี่ยนแปลงความหมายของกฎบิลด์แบบเนทีฟที่ส่งผลต่อลักษณะการทำงานของกฎมากกว่า 1 กฎ
• การเปลี่ยนแปลง API คำจำกัดความกฎของ Bazel
• การเปลี่ยนแปลง API ที่ Bazel ใช้เพื่อเชื่อมต่อกับระบบอื่นๆ
• การเปลี่ยนแปลงภาษา ความหมาย หรือ API ของ Starlark
• การเปลี่ยนแปลงที่อาจส่งผลกระทบเป็นวงกว้างต่อประสิทธิภาพการทำงานของ Bazel หรือการใช้หน่วยความจำ (เพื่อปรับปรุงหรือแย่ลง)
• การเปลี่ยนแปลงเกี่ยวกับ API ภายในที่ใช้กันอย่างแพร่หลาย
• การเปลี่ยนแปลงการติดธงและอินเทอร์เฟซบรรทัดคำสั่ง

เหตุผลในการตรวจสอบการออกแบบ

เมื่อคุณเขียนเอกสารการออกแบบ คุณจะสามารถประสานงานกับนักพัฒนาแอป Bazel คนอื่นๆ และขอคำแนะนำจากทีมหลักของ Bazel ตัวอย่างเช่น เมื่อข้อเสนอเพิ่ม นำออก หรือแก้ไขฟังก์ชันหรือออบเจ็กต์ที่มีอยู่ในไฟล์ BUILD, WORKSPACE หรือ bzl ให้เพิ่มทีม Starlark เป็นผู้ตรวจสอบ เอกสารการออกแบบจะได้รับการตรวจสอบก่อนส่งเนื่องจากเหตุผลต่อไปนี้

• Bazel เป็นระบบที่ซับซ้อนมาก การเปลี่ยนแปลงในท้องถิ่นที่ดูเหมือนจะไม่เป็นอันตรายอาจส่งผลกระทบที่สำคัญต่อระดับโลก
• ทีมได้รับคำขอฟีเจอร์จำนวนมากจากผู้ใช้ คำขอดังกล่าวต้องได้รับการประเมินทั้งในแง่ความเป็นไปได้ทางเทคนิค แต่ยังต้องให้ความสำคัญเกี่ยวกับคำขอฟีเจอร์อื่นๆ ด้วย
• ฟีเจอร์ของ Bazel มักจะดำเนินการโดยบุคคลภายนอกทีมหลัก ผู้มีส่วนร่วมดังกล่าวมีความเชี่ยวชาญของ Bazel ในหลายระดับอย่างกว้างขวาง
• ทีม Bazel เองก็มีความเชี่ยวชาญในระดับที่แตกต่างกัน สมาชิกในทีมคนใดคนหนึ่ง ไม่มีความรู้ความเข้าใจอย่างถ่องแท้ในทุกมุมของ Bazel
• การเปลี่ยนแปลง Bazel ต้องคำนึงถึงความเข้ากันได้แบบย้อนหลังและหลีกเลี่ยงไม่ให้การเปลี่ยนแปลงมีผล

นโยบายการตรวจสอบการออกแบบของ Bazel ช่วยเพิ่มโอกาสที่สิ่งใดต่อไปนี้

• คำขอฟีเจอร์ทั้งหมดจะได้รับการตรวจสอบในระดับพื้นฐาน
• คนที่เหมาะสมจะคำนึงถึงการออกแบบก่อนที่เราจะลงทุนใน การติดตั้งใช้งานซึ่งอาจไม่ได้ผล

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

เวิร์กโฟลว์ Contributor

ในฐานะผู้ร่วมให้ข้อมูล คุณสามารถเขียนเอกสารการออกแบบ ส่งคำขอพุล และ ขอให้ผู้ตรวจสอบข้อเสนอของคุณ

เขียนเอกสารการออกแบบ

เอกสารการออกแบบทั้งหมดต้องมีส่วนหัวที่ประกอบด้วย:

• ผู้เขียน
• วันที่เกิดการเปลี่ยนแปลงสำคัญล่าสุด
• รายชื่อผู้ตรวจสอบ ซึ่งรวมถึงผู้ตรวจสอบที่เป็นหัวหน้า 1 คน (เท่านั้น)
• สถานะปัจจุบัน (draft, อยู่ระหว่างการตรวจสอบ, อนุมัติแล้ว, ถูกปฏิเสธ, กำลังนำมาใช้งาน, เสร็จแล้ว)
• ลิงก์ไปยังชุดการสนทนา (จะเพิ่มภายหลัง)

คุณจะเขียนเอกสารนี้ได้เป็น Google เอกสารที่อ่านได้อย่างทั่วถึงหรือใช้มาร์กดาวน์ก็ได้ อ่านด้านล่างเกี่ยวกับการเปรียบเทียบมาร์กดาวน์ / Google เอกสาร

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

สร้างคำขอพุล

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

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

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

ประกาศข้อเสนอใหม่

ส่งประกาศไปที่ bazel-dev เมื่อส่ง PR

คุณอาจคัดลอกกลุ่มอื่นๆ (เช่น Bazel-discuss เพื่อรับความคิดเห็นจากผู้ใช้ปลายทาง Bazel)

ทำซ้ำด้วยผู้ตรวจสอบ

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

การสนทนาควรเกิดขึ้นในชุดข้อความประกาศ หากข้อเสนอนี้อยู่ใน Google เอกสาร ระบบอาจใช้ความคิดเห็นแทน (โปรดทราบว่าเราอนุญาตการแสดงความคิดเห็นแบบไม่ระบุตัวตน)

อัปเดตสถานะ

สร้างการประชาสัมพันธ์ใหม่เพื่ออัปเดตสถานะของข้อเสนอเมื่อการปรับปรุงเสร็จสมบูรณ์ ส่งการประชาสัมพันธ์ให้ผู้ตรวจสอบที่เป็นหัวหน้าคนเดียวกันและส่งสําเนาถึงผู้ตรวจสอบคนอื่นๆ

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

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

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

การเลือกผู้ตรวจสอบที่เป็นผู้มีโอกาสเป็นลูกค้า

ผู้ตรวจสอบที่เป็นผู้มีโอกาสเป็นลูกค้าควรเป็นผู้เชี่ยวชาญด้านโดเมนที่มีคุณสมบัติดังนี้

• มีความรอบรู้เกี่ยวกับระบบย่อยที่เกี่ยวข้อง
• เป็นวัตถุประสงค์และสามารถให้ความคิดเห็นเชิงสร้างสรรค์
• พร้อมให้บริการตลอดระยะเวลาการตรวจสอบเพื่อนําเข้าสู่กระบวนการ

ลองตรวจสอบรายชื่อติดต่อสำหรับป้ายกำกับทีมต่างๆ

มาร์กดาวน์ เทียบกับ Google เอกสาร

ตัดสินใจว่าอะไรเหมาะกับคุณมากที่สุด เนื่องจากเรายอมรับทั้งสองรูปแบบ

ประโยชน์ของการใช้ Google เอกสาร

• มีประสิทธิภาพสำหรับการระดมความคิดเนื่องจากเริ่มต้นได้ง่าย
• การแก้ไขร่วมกัน
• ทำซ้ำอย่างรวดเร็ว
• แนะนำการแก้ไขได้ง่ายๆ

ประโยชน์ของการใช้ไฟล์มาร์กดาวน์

• URL ที่เป็นระเบียบเพื่อทำการลิงก์
• บันทึกการแก้ไขที่ชัดเจน
• รวมถึงอย่าลืมตั้งค่าสิทธิ์เข้าถึงก่อนการเผยแพร่ลิงก์ด้วย
• ค้นหาได้ง่ายด้วยเครื่องมือค้นหา
• รับประกันได้ในอนาคต: ข้อความธรรมดาไม่จำเป็นต้องใช้เครื่องมือใดเป็นพิเศษและไม่จำเป็นต้องมีการเชื่อมต่ออินเทอร์เน็ต
• และสามารถอัปเดตข้อมูลได้แม้ว่าผู้เขียนจะไม่อยู่กับคุณแล้ว
• เพราะสามารถรับการประมวลผลโดยอัตโนมัติ (อัปเดต/ตรวจหาลิงก์ที่ใช้งานไม่ได้ ดึงรายชื่อผู้เขียน ฯลฯ)

คุณสามารถเลือกทำซ้ำในเอกสารใน Google เอกสารก่อน แล้วจึงแปลงเป็นมาร์กดาวน์สำหรับลำดับรุ่นหลัง

การใช้ Google เอกสาร

ใช้เทมเพลตเอกสารการออกแบบสไตล์บาเซลเพื่อความสอดคล้อง ซึ่งมีส่วนหัวที่จำเป็นและสร้างความสอดคล้องกัน กับเอกสารอื่นๆ ที่เกี่ยวข้องกับ Bazel โดยคลิกไฟล์ > ทำสำเนา หรือคลิกลิงก์นี้เพื่อทำสำเนาเทมเพลตเอกสารการออกแบบ

หากต้องการให้คนทั้งโลกอ่านเอกสารได้ ให้คลิกแชร์ > ขั้นสูง > เปลี่ยน... แล้วเลือก "เปิด - ทุกคนที่มีลิงก์" หากคุณอนุญาตให้แสดงความคิดเห็นในเอกสาร ทุกคนจะแสดงความคิดเห็นแบบไม่ระบุตัวตนได้ แม้จะไม่มีบัญชี Google ก็ตาม

การใช้มาร์กดาวน์

เอกสารจะจัดเก็บอยู่ใน GitHub และใช้เวอร์ชัน GitHub ของ Markdown (ข้อกำหนด)

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

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

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

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

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

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

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

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

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

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

ความรับผิดชอบของผู้รีวิวที่เป็นหัวหน้า

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

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

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

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

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

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

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