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

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

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

2. แจ้งปัญหาเกี่ยวกับ GitHub

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

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

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

ปัญหาใน GitHub

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

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

• ชื่อจะขึ้นต้นด้วยชื่อแฟล็ก (ชื่อแฟล็กจะขึ้นต้นด้วย incompatible_)

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

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

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

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

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

การใช้งาน

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

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

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

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

ป้ายกำกับ

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

หากพบปัญหากับแฟล็กและผู้ใช้ยังไม่คาดว่าจะย้ายข้อมูล: ให้นำแฟล็ก 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)

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

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

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

  ในไปป์ไลน์ 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 ฉบับใหม่เพื่อติดตามการนำธงออก

การนำธงออก

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

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