เราจำเป็นต้องทำการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบใน Bazel เราจะต้องเปลี่ยนการออกแบบและแก้ไขปัญหาที่ไม่ทำงาน แต่เราจำเป็นต้อง เพื่อให้มั่นใจว่าชุมชนและระบบนิเวศของ Bazel จะเดินตามไปด้วยได้ ด้วยเหตุนี้ โปรเจ็กต์ Bazel จึงใช้นโยบายความเข้ากันได้แบบย้อนหลัง เอกสารนี้อธิบายขั้นตอนสำหรับผู้มีส่วนร่วมใน Bazel เพื่อทำการเปลี่ยนแปลงที่ก่อให้เกิดข้อขัดข้องใน Bazel เพื่อให้เป็นไปตามนโยบายนี้
ปฏิบัติตามนโยบายเอกสารการออกแบบ
ปัญหาเกี่ยวกับ GitHub
แจ้งปัญหาเกี่ยวกับ GitHub ในที่เก็บ Bazel ดูตัวอย่าง
เราขอแนะนําให้ทําดังนี้
ชื่อเรื่องเริ่มต้นด้วยชื่อของ Flag (ชื่อธงจะขึ้นต้นด้วย
incompatible_
)คุณเพิ่มป้ายกำกับ
incompatible-change
คำอธิบายจะมีคำอธิบายการเปลี่ยนแปลงและมีลิงก์ไปยัง เอกสารการออกแบบ
คําอธิบายมีวิธีการย้ายข้อมูลเพื่ออธิบายให้ผู้ใช้ทราบถึงวิธีอัปเดตโค้ด ตามหลักการแล้ว เมื่อการเปลี่ยนแปลงเป็นกลไก ให้ใส่ลิงก์ไปยัง เครื่องมือย้ายข้อมูล
คำอธิบายมีตัวอย่างข้อความแสดงข้อผิดพลาดที่ผู้ใช้จะได้รับหากไม่ย้ายข้อมูล ซึ่งจะทำให้ค้นพบปัญหา GitHub ได้ง่ายขึ้นจาก เครื่องมือค้นหา ตรวจสอบว่าข้อความแสดงข้อผิดพลาดมีประโยชน์และนําไปใช้ได้จริง ข้อความแสดงข้อผิดพลาดควรระบุชื่อของ Flag ที่เข้ากันไม่ได้ หากเป็นไปได้
สำหรับเครื่องมือย้ายข้อมูล ให้พิจารณาการมีส่วนร่วม
Buildifier
โดยสามารถแก้ไขไฟล์ BUILD
, WORKSPACE
และ .bzl
ได้โดยอัตโนมัติ
นอกจากนี้ยังอาจรายงานคำเตือนด้วย
การใช้งาน
สร้าง Flag ใหม่ใน 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
หากพบปัญหาเกี่ยวกับ Flag และยังไม่ต้องการให้ผู้ใช้ย้ายข้อมูล ให้นำ Flag ออก migration-ready
หากคุณวางแผนที่จะพลิกธงในรุ่นหลักรุ่นถัดไป ให้เพิ่มป้ายกำกับ "breaking-change-X.0" ต่อประเด็นปัญหา
กำลังอัปเดตที่เก็บ
Bazel CI ได้ทดสอบรายการโปรเจ็กต์สำคัญที่
Bazel@HEAD + Downstream ส่วนใหญ่มัก
ทรัพยากร Dependency ของโปรเจ็กต์ Bazel อื่นๆ ดังนั้นจึงเป็นสิ่งสำคัญที่ต้องย้ายข้อมูลโปรเจ็กต์เหล่านั้นเพื่อเลิกบล็อกการย้ายข้อมูลสำหรับชุมชนในวงกว้าง หากต้องการตรวจสอบสถานะการย้ายข้อมูลของโปรเจ็กต์เหล่านั้น ให้ใช้ไปป์ไลน์ bazelisk-plus-incompatible-flags
ดูวิธีการทํางานของไปป์ไลน์นี้ได้ที่นี่
ทีมสนับสนุนนักพัฒนาซอฟต์แวร์ของเราจะตรวจสอบป้ายกำกับ migration-ready
เมื่อคุณเพิ่มป้ายกำกับนี้ลงในปัญหา GitHub แล้ว ทีมจะดำเนินการต่อไปนี้
สร้างความคิดเห็นในปัญหา GitHub เพื่อติดตามรายการที่ดำเนินการไม่สำเร็จและโปรเจ็กต์ดาวน์สตรีมที่ต้องย้ายข้อมูล (ดูตัวอย่าง)
ไฟล์ปัญหา GitHub เพื่อแจ้งเจ้าของโครงการดาวน์สตรีมที่เสียหายจากการเปลี่ยนแปลงที่เข้ากันไม่ได้ (ดูตัวอย่าง)
ติดตามผลเพื่อให้แน่ใจว่าปัญหาทั้งหมดได้รับการแก้ไขก่อนวันที่กำหนดการเผยแพร่
การย้ายข้อมูลโปรเจ็กต์ในไปป์ไลน์ดาวน์สตรีมไม่ใช่ความรับผิดชอบของผู้เขียนการเปลี่ยนแปลงที่ใช้ร่วมกันไม่ได้ แต่คุณสามารถดำเนินการต่อไปนี้เพื่อเร่งการย้ายข้อมูลและทำให้ทั้งผู้ใช้ Bazel และทีม Bazel Green ทำงานได้ง่ายขึ้น
ส่ง PR เพื่อแก้ไขโปรเจ็กต์ดาวน์สตรีม
ติดต่อชุมชน 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 เป็น "เท็จ" ในไฟล์ blazerc
ภายในเพื่อเลิกบล็อกการพลิกธง วิธีนี้ทำให้เรามั่นใจได้ว่าผู้ใช้ 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 ปิดเมื่อผสานคอมมิต