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

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

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

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

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

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

5. เปลี่ยนการตั้งค่าสถานะที่ใช้ร่วมกันไม่ได้

ปัญหาเกี่ยวกับ GitHub

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

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

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

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

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

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

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

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

การใช้งาน

สร้างแฟล็กใหม่ใน Bazel ค่าเริ่มต้นต้องเป็น false ข้อความช่วยเหลือควรมี 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 ส่วนใหญ่แล้วมักจะขึ้นอยู่กับโครงการของ 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 โปรดพิจารณาตั้งค่าแฟล็กเป็น "เท็จ" ในไฟล์ blazerc ภายในเพื่อเลิกบล็อก Flag Flip การทำเช่นนี้ช่วยให้เรามั่นใจได้ว่าผู้ใช้ 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 เมื่อมีการรวมคอมมิต