เป็นเรื่องหลีกเลี่ยงไม่ได้ที่เราจะทำการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบของ Bazel เราจะต้องเปลี่ยนดีไซน์และแก้ไขสิ่งที่ไม่ค่อยได้ผล อย่างไรก็ตาม เราต้องแน่ใจว่าชุมชนและระบบนิเวศของ Bazel จะก้าวไปพร้อมกันได้ ด้วยเหตุนี้ โปรเจ็กต์ Bazel จึงได้นำนโยบายความเข้ากันได้แบบย้อนหลังมาใช้ เอกสารนี้อธิบายกระบวนการที่ผู้ให้ข้อมูลร่วมกันของ Bazel ทำการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นใน Bazel เพื่อปฏิบัติตามนโยบายนี้
ปฏิบัติตามนโยบายเอกสารการออกแบบ
ปัญหาเกี่ยวกับ GitHub
ส่งไฟล์ปัญหาเกี่ยวกับ GitHub ในที่เก็บ Bazel ดูตัวอย่าง
เราขอแนะนำให้ทำดังนี้
ชื่อจะขึ้นต้นด้วยชื่อแฟล็ก (ชื่อแฟล็กจะขึ้นต้นด้วย
incompatible_
)คุณเพิ่มป้ายกำกับ
incompatible-change
คำอธิบายจะมีคำอธิบายการเปลี่ยนแปลงและลิงก์ไปยังเอกสารการออกแบบที่เกี่ยวข้อง
คำอธิบายจะมีสูตรการย้ายข้อมูลที่จะอธิบายให้ผู้ใช้ทราบว่าควรอัปเดตโค้ดอย่างไร หากเป็นการเปลี่ยนแปลงเชิงกลไก ให้ใส่ลิงก์ไปยังเครื่องมือย้ายข้อมูลด้วย
คำอธิบายมีตัวอย่างของข้อความแสดงข้อผิดพลาดที่ผู้ใช้จะได้รับหากไม่ย้ายข้อมูล ซึ่งจะทำให้ค้นพบปัญหา GitHub ได้ง่ายขึ้นจากเครื่องมือค้นหา ตรวจสอบว่าข้อความแสดงข้อผิดพลาดนั้นมีประโยชน์และดำเนินการได้ หากเป็นไปได้ ข้อความแสดงข้อผิดพลาดควรมีชื่อของ Flag ที่ใช้ร่วมกันไม่ได้
สำหรับเครื่องมือย้ายข้อมูล ให้พิจารณามีส่วนร่วมกับ Buildifier
สามารถใช้การแก้ไขอัตโนมัติกับไฟล์ BUILD
, WORKSPACE
และ .bzl
นอกจากนี้ยังอาจรายงานคำเตือนด้วย
การใช้งาน
สร้าง Flag ใหม่ใน Bazel ค่าเริ่มต้นคือ false ข้อความช่วยเหลือควรมี URL ของปัญหา GitHub เนื่องจากชื่อแฟล็กขึ้นต้นด้วย incompatible_
จึงต้องมีแท็กข้อมูลเมตาดังนี้
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
เพิ่มข้อมูลสรุปคร่าวๆ เกี่ยวกับ Flag ในคำอธิบายของคอมมิต
และเพิ่ม 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 โปรดพิจารณาตั้งค่า Flag เป็น "เท็จ" ในไฟล์ blazerc
ภายในเพื่อเลิกบล็อกการพลิกธง วิธีนี้ทำให้เรามั่นใจได้ว่าผู้ใช้ Bazel จะใช้ลักษณะการทำงานใหม่โดยค่าเริ่มต้นโดยเร็วที่สุด
เมื่อเปลี่ยนค่าเริ่มต้นของแฟล็กเป็น "จริง" โปรดทำดังนี้
- ใช้
RELNOTES[INC]
ในคำอธิบายของคอมมิตโดยใช้รูปแบบต่อไปนี้RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details
คุณสามารถใส่ข้อมูลเพิ่มเติมได้ในคำอธิบายสัญญาผูกมัดส่วนที่เหลือ - ใช้
Fixes #xyz
ในคำอธิบายเพื่อปิดปัญหา GitHub เมื่อผสานคอมมิตแล้ว - ตรวจสอบและอัปเดตเอกสารหากจำเป็น
- ยื่น
#abc
ฉบับใหม่เพื่อติดตามการนำธงออก
การนำธงออก
หลังจากพลิกธงที่ HEAD แล้ว ควรนำออกจาก Bazel ในที่สุด สิ่งที่จะเกิดขึ้นเมื่อคุณนำการแจ้งว่าไม่เหมาะสมออกคือ
- คุณควรให้เวลาผู้ใช้ย้ายข้อมูลนานขึ้นหากเป็นการเปลี่ยนแปลงครั้งใหญ่ที่เข้ากันไม่ได้ โดยหลักการแล้ว Flag ควรพร้อมใช้งานในรุ่นหลักอย่างน้อย 1 รุ่น
- สำหรับคอมมิตที่นำ Flag ออก ให้ใช้
Fixes #abc
ในคำอธิบายเพื่อปิดปัญหา GitHub เมื่อรวมคอมมิตแล้ว