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

เราจะทำการเปลี่ยนแปลงที่ทำให้เกิดการหยุดทำงานของ 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 และ ดูวิธีทำงานของไปป์ไลน์นี้ได้ที่นี่

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

1. แจ้งปัญหาใน GitHub เพื่อแจ้งให้เจ้าของโปรเจ็กต์ดาวน์สตรีมที่ได้รับผลกระทบจากการเปลี่ยนแปลงที่ไม่เข้ากันทราบ
2. ส่งคำขอดึงข้อมูลเพื่อแก้ไขโปรเจ็กต์ดาวน์สตรีม
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 ปิดลงเมื่อผสานการคอมมิต