คำแนะนำในการเปิดตัวการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

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

1. ปฏิบัติตามนโยบายเอกสารการออกแบบ

2. แจ้งปัญหาใน GitHub

3. ใช้การเปลี่ยนแปลง

4. อัปเดตป้ายกำกับ

5. พลิกธง "ใช้ร่วมกันไม่ได้"

ปัญหาใน GitHub

แจ้งปัญหาใน GitHub ที่เก็บ Bazel ดูตัวอย่าง

เราขอแนะนําให้ทําดังนี้

• ชื่อจะขึ้นต้นด้วยชื่อของ Flag (ชื่อ Flag จะขึ้นต้นด้วย incompatible_)

• คุณเพิ่มป้ายกำกับ incompatible-change

• คำอธิบายมีคำอธิบายการเปลี่ยนแปลงและลิงก์ไปยังเอกสารการออกแบบที่เกี่ยวข้อง

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

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

สําหรับเครื่องมือย้ายข้อมูล ให้ลองมีส่วนร่วมใน Buildifier โดยสามารถแก้ไขไฟล์ BUILD, WORKSPACE และ .bzl ได้โดยอัตโนมัติ และอาจรายงานคำเตือนด้วย

การใช้งาน

สร้าง Flag ใหม่ใน Bazel ค่าเริ่มต้นต้องเป็น False ข้อความช่วยเหลือควรมี URL ของปัญหาใน GitHub เนื่องจากชื่อ Flag ขึ้นต้นด้วย incompatible_ จึงต้องมีแท็กข้อมูลเมตา ดังนี้

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

ในคำอธิบายการคอมมิต ให้เพิ่มสรุปสั้นๆ ของการตั้งค่าสถานะ และเพิ่ม RELNOTES: ในรูปแบบต่อไปนี้ RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

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

ป้ายกำกับ

เมื่อผสานคอมมิตและพร้อมที่จะนำการเปลี่ยนแปลงที่เข้ากันไม่ได้ไปใช้แล้ว ให้เพิ่มป้ายกำกับ migration-ready ลงในปัญหา GitHub

หากพบปัญหาเกี่ยวกับ Flag และยังไม่ต้องการให้ผู้ใช้ย้ายข้อมูล ให้นำ Flag ออก migration-ready

หากคุณวางแผนที่จะเปิดใช้การตั้งค่าในรุ่นหลักถัดไป ให้เพิ่มป้ายกำกับ "breaking-change-X.0" ลงในปัญหา

การอัปเดตที่เก็บ

Bazel CI จะทดสอบรายการโปรเจ็กต์สำคัญใน Bazel@HEAD + Downstream ส่วนใหญ่มักเป็นแพ็กเกจที่ต้องพึ่งพาของโปรเจ็กต์ Bazel อื่นๆ จึงจำเป็นต้องย้ายข้อมูลเพื่อปลดล็อกการย้ายข้อมูลสำหรับชุมชนในวงกว้าง

หากต้องการตรวจสอบสถานะการย้ายข้อมูลของโปรเจ็กต์เหล่านั้น ให้ใช้bazelisk-plus-incompatible-flagsไปป์ไลน์ โดยดูวิธีการทำงานของไปป์ไลน์นี้ได้ที่นี่

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

1. รายงานปัญหาใน Github เพื่อแจ้งให้เจ้าของโปรเจ็กต์ดาวน์สตรีมทราบถึงการเปลี่ยนแปลงที่เข้ากันไม่ได้ซึ่งทำให้โปรเจ็กต์ใช้งานไม่ได้
2. ส่ง PR เพื่อแก้ไขโปรเจ็กต์ดาวน์สตรีม
3. ติดต่อชุมชน Bazel เพื่อขอความช่วยเหลือเกี่ยวกับการย้ายข้อมูล (เช่น Bazel Rules Authors SIG)

การพลิกสถานะ

โปรดตรวจสอบสิ่งต่อไปนี้ก่อนเปลี่ยนค่าเริ่มต้นของ Flag เป็น "จริง"

• ระบบจะย้ายข้อมูลที่เก็บข้อมูลหลักในระบบนิเวศ

  ในไปป์ไลน์ bazelisk-plus-incompatible-flags รายการที่แจ้งว่าไม่เหมาะสมควรปรากฏใต้ The following flags didn't break any passing Bazel team owned/co-owned projects

• ข้อกังวลและคำถามของผู้ใช้ได้รับการแก้ไขแล้ว

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

เมื่อเปลี่ยนค่าเริ่มต้นของแฟล็กเป็น "จริง" โปรดทำดังนี้

• ใช้ RELNOTES[INC] ในคำอธิบายการคอมมิต โดยมีรูปแบบดังนี้ RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details คุณใส่ข้อมูลเพิ่มเติมในส่วนที่เหลือของคำอธิบายการคอมมิตได้
• ใช้ Fixes #xyz ในคำอธิบายเพื่อให้ระบบปิดปัญหาใน GitHub เมื่อผสานการคอมมิต
• ตรวจสอบและอัปเดตเอกสารประกอบ หากจำเป็น
• โปรดแจ้งปัญหาใหม่ #abc เพื่อติดตามการนําการแจ้งว่าไม่เหมาะสมออก

การนำการแจ้งว่าไม่เหมาะสมออก

หลังจากเปิดใช้ Flag ที่ HEAD แล้ว ก็ควรนํา Flag นั้นออกจาก Bazel ในท้ายที่สุด สิ่งที่จะเกิดขึ้นเมื่อคุณวางแผนที่จะนำการแจ้งว่าเข้ากันไม่ได้ออก

• พิจารณาให้เวลาผู้ใช้ในการย้ายข้อมูลนานขึ้นหากเป็นการเปลี่ยนแปลงที่สำคัญซึ่งเข้ากันไม่ได้ โดยควรมี Flag อยู่ในรุ่นหลักอย่างน้อย 1 รุ่น
• สำหรับคอมมิตที่นําการแจ้งว่าไม่สําคัญออก ให้ใช้ Fixes #abc ในคําอธิบายเพื่อให้ปัญหาใน GitHub ปิดเมื่อผสานคอมมิต