หลีกเลี่ยงไม่ได้ที่เราจะทําการเปลี่ยนแปลงที่ส่งผลกับ Bazel เราจะต้องเปลี่ยนการออกแบบและแก้ไขสิ่งที่ใช้การไม่ได้ อย่างไรก็ตาม เราต้องตรวจสอบว่าชุมชนและระบบนิเวศของ Bazel ปฏิบัติตามได้ เพื่อให้โปรเจ็กต์ Bazel ใช้นโยบายความเข้ากันได้แบบย้อนหลัง เอกสารนี้อธิบายกระบวนการของผู้ร่วมให้ข้อมูล Bazel ในการเปลี่ยนแปลงที่ส่งผลกับ Bazel เพื่อให้เป็นไปตามนโยบายนี้
ปฏิบัติตามนโยบายการออกแบบเอกสาร
ปัญหาเกี่ยวกับ GitHub
รายงานปัญหา GitHub ในที่เก็บ Bazel ดูตัวอย่าง
เราขอแนะนําให้คุณดําเนินการดังต่อไปนี้
ชื่อจะเริ่มด้วยชื่อของแฟล็ก (ชื่อแฟล็กจะขึ้นต้นด้วย
incompatible_
)คุณเพิ่มป้ายกํากับ
incompatible-change
คําอธิบายมีคําอธิบายของการเปลี่ยนแปลงและลิงก์ไปยังเอกสารการออกแบบที่เกี่ยวข้อง
คําอธิบายมีสูตรการย้ายข้อมูลที่จะอธิบายวิธีที่ผู้ใช้ควรอัปเดตโค้ด ตามหลักการแล้ว เมื่อการเปลี่ยนแปลงเป็นกลไก ให้ใส่ลิงก์ไปยังเครื่องมือย้ายข้อมูล
ตัวอย่างจะมีตัวอย่างข้อความแสดงข้อผิดพลาดที่ผู้ใช้จะได้รับหากไม่ได้ย้ายข้อมูล ซึ่งจะทําให้ GitHub ค้นพบปัญหาได้ง่ายขึ้นจากเครื่องมือค้นหา ตรวจสอบว่าข้อความแสดงข้อผิดพลาดมีประโยชน์และดําเนินการได้ หากเป็นไปได้ ข้อความแสดงข้อผิดพลาดควรมีชื่อของแฟล็กที่เข้ากันไม่ได้
สําหรับเครื่องมือย้ายข้อมูล ให้พิจารณามีส่วนร่วมใน Buildifier
และสามารถนําการแก้ไขอัตโนมัติไปใช้กับไฟล์ BUILD
, WORKSPACE
และ .bzl
ได้
ซึ่งอาจรายงานคําเตือนด้วย
การใช้งาน
สร้างแฟล็กใหม่ใน Bazel ค่าเริ่มต้นต้องเป็น "เท็จ" ข้อความช่วยเหลือควรมี 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 + ดาวน์สตรีม ทรัพยากรส่วนใหญ่มักจะพึ่งพาทรัพยากรของโปรเจ็กต์ Bazel อื่นๆ ดังนั้นการย้ายข้อมูลจึงควรเลิกบล็อกการย้ายข้อมูลสําหรับชุมชนที่กว้างขึ้น หากต้องการตรวจสอบสถานะการย้ายข้อมูลของโปรเจ็กต์เหล่านั้น ให้ใช้ไปป์ไลน์ bazelisk-plus-incompatible-flags
ดูวิธีการทํางานของไปป์ไลน์นี้ที่นี่
ทีมสนับสนุนนักพัฒนาซอฟต์แวร์จะตรวจสอบป้ายกํากับ migration-ready
เมื่อเพิ่มป้ายกํากับนี้ในปัญหา GitHub แล้ว ป้ายกํากับเหล่านี้จะจัดการสิ่งต่อไปนี้
สร้างความคิดเห็นในปัญหา GitHub เพื่อติดตามรายการความล้มเหลวและโปรเจ็กต์ดาวน์สตรีมที่ต้องย้ายข้อมูล (ดูตัวอย่าง)
รายงานปัญหาของ GitHub เพื่อแจ้งเจ้าของโปรเจ็กต์ในโปรเจ็กต์ดาวน์สตรีมทั้งหมดซึ่งได้รับผลกระทบจากการเปลี่ยนแปลงที่เข้ากันไม่ได้ (ดูตัวอย่าง)
ติดตามผลเพื่อให้แน่ใจว่าปัญหาทั้งหมดได้รับการแก้ไขก่อนวันเผยแพร่เป้าหมาย
การย้ายข้อมูลโปรเจ็กต์ในไปป์ไลน์ดาวน์สตรีมไม่ใช่ความรับผิดชอบของผู้เขียนการเปลี่ยนแปลงที่เข้ากันไม่ได้ทั้งหมด แต่คุณทําสิ่งต่อไปนี้เพื่อเร่งการย้ายข้อมูลและทําให้ทั้งผู้ใช้ Bazel และทีม Bazel เร็วขึ้นได้
ส่ง PR เพื่อแก้ไขโปรเจ็กต์ดาวน์สตรีม
ติดต่อชุมชน Bazel เพื่อรับความช่วยเหลือเกี่ยวกับการย้ายข้อมูล (เช่น Bazel Rules Authors SIG)
พลิกธง
ก่อนที่จะพลิกค่าเริ่มต้นของแฟล็กเป็น "จริง" โปรดตรวจสอบว่า
ระบบจะย้ายข้อมูลที่เก็บหลักในระบบนิเวศ
ในไปป์ไลน์
bazelisk-plus-incompatible-flags
แฟล็กควรอยู่ใต้The following flags didn't break any passing Bazel team owned/co-owned projects
ปัญหาทั้งหมดในรายการตรวจสอบจะมีการทําเครื่องหมายว่าแก้ไขแล้ว/ปิดแล้ว
ข้อกังวลและคําถามของผู้ใช้ได้รับการแก้ไขแล้ว
เมื่อแฟล็กพร้อมที่จะพลิกใน Bazel แต่ถูกบล็อกในการย้ายข้อมูลภายในที่ Google โปรดพิจารณาตั้งค่าแฟล็กเป็น false ในไฟล์ blazerc
ภายในเพื่อเลิกบล็อกการพลิกแฟล็ก การดําเนินการนี้จะทําให้ผู้ใช้มั่นใจได้ว่า 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 เมื่อมีการรวมสัญญาผูกมัด