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

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

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

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

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

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

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

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

ปัญหาเกี่ยวกับ 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,
      },

ในคำอธิบายการคอมมิต ให้เพิ่มสรุปสั้นๆ ของ Flag และเพิ่ม 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 ดูวิธีการทํางานของไปป์ไลน์นี้ได้ที่นี่

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

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

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

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

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

1. ส่ง PR เพื่อแก้ไขโปรเจ็กต์ดาวน์สตรีม

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