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