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

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

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

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

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

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

5. อัปเดตที่เก็บ

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

ปัญหาใน 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 ดูวิธีทำงานของไปป์ไลน์นี้ได้ที่นี่

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

1. สร้างความคิดเห็นในปัญหาใน GitHub เพื่อติดตามรายการความล้มเหลวและโปรเจ็กต์ปลายทางที่ต้องย้ายข้อมูล (ดูตัวอย่าง)

2. แจ้งปัญหาใน GitHub เพื่อแจ้งให้เจ้าของโปรเจ็กต์ปลายทางทุกโปรเจ็กต์ที่ได้รับผลกระทบจากการเปลี่ยนแปลงที่เข้ากันไม่ได้ทราบ (ดูตัวอย่าง)

3. ติดตามเพื่อให้แน่ใจว่าปัญหาทั้งหมดได้รับการแก้ไขก่อนวันที่เผยแพร่เป้าหมาย

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

1. ส่ง PR เพื่อแก้ไขโปรเจ็กต์ปลายทาง

2. ติดต่อชุมชน 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 ปิดลงเมื่อผสานการคอมมิต