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