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

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

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

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

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

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

5. เปลี่ยนสถานะแฟล็กที่เข้ากันไม่ได้

ปัญหาใน GitHub

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

เราขอแนะนำให้คุณทำดังนี้

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

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

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

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

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

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

การใช้งาน

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

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

ในคำอธิบายการคอมมิต ให้เพิ่มข้อมูลสรุปสั้นๆ เกี่ยวกับแฟล็ก นอกจากนี้ ให้เพิ่ม 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 โปรเจ็กต์ส่วนใหญ่มักจะเป็นทรัพยากร Dependency ของโปรเจ็กต์ Bazel อื่นๆ ดังนั้นจึงควรย้ายข้อมูลโปรเจ็กต์เหล่านี้เพื่อปลดบล็อกการย้ายข้อมูลสำหรับชุมชนในวงกว้าง

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

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

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

การเปลี่ยนสถานะแฟล็ก

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

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

  ในไปป์ไลน์ bazelisk-plus-incompatible-flags, แฟล็กควรปรากฏในส่วน The following flags didn't break any passing Bazel team owned/co-owned projects

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

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

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

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

การนำแฟล็กออก

หลังจากเปลี่ยนสถานะแฟล็กที่ HEAD แล้ว ในที่สุดระบบก็จะนำแฟล็กออกจาก Bazel เมื่อวางแผนที่จะนำแฟล็กที่เข้ากันไม่ได้ออก ให้ดำเนินการดังนี้

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