คำแนะนำในการเปิดตัวการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบ

รายงานปัญหา ดูแหล่งที่มา /3} /4} {3/4} {3/4} {3/4} {3/4} /4.

เป็นเรื่องหลีกเลี่ยงไม่ได้ที่เราจะทำการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบของ Bazel เราจะต้องเปลี่ยนดีไซน์และแก้ไขสิ่งที่ไม่ค่อยได้ผล อย่างไรก็ตาม เราต้องแน่ใจว่าชุมชนและระบบนิเวศของ Bazel จะก้าวไปพร้อมกันได้ ด้วยเหตุนี้ โปรเจ็กต์ Bazel จึงได้นำนโยบายความเข้ากันได้แบบย้อนหลังมาใช้ เอกสารนี้อธิบายกระบวนการที่ผู้ให้ข้อมูลร่วมกันของ Bazel ทำการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นใน Bazel เพื่อปฏิบัติตามนโยบายนี้

1. ปฏิบัติตามนโยบายเอกสารการออกแบบ

2. แจ้งปัญหาเกี่ยวกับ GitHub

3. ใช้การเปลี่ยนแปลง

4. อัปเดตป้ายกำกับ

5. อัปเดตที่เก็บ

6. พลิกแฟล็กที่ใช้ร่วมกันไม่ได้

ปัญหาเกี่ยวกับ 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 ตรวจสอบวิธีการทำงานของไปป์ไลน์นี้ที่นี่

ทีมสนับสนุนนักพัฒนาซอฟต์แวร์ของเราจะตรวจสอบป้ายกำกับ migration-ready เมื่อเพิ่มป้ายกำกับนี้ไปยังปัญหาใน GitHub แล้ว ป้ายกำกับดังกล่าวจะจัดการสิ่งต่อไปนี้

1. สร้างความคิดเห็นในปัญหา GitHub เพื่อติดตามรายการความล้มเหลวและโปรเจ็กต์ดาวน์สตรีมที่จำเป็นต้องย้ายข้อมูล (ดูตัวอย่าง)

2. ไฟล์ปัญหา GitHub เพื่อแจ้งเจ้าของโครงการดาวน์สตรีมทั้งหมดที่เสียหายจากการเปลี่ยนแปลงที่เข้ากันไม่ได้ (ดูตัวอย่าง)

3. ติดตามผลเพื่อให้แน่ใจว่าปัญหาทั้งหมดได้รับการแก้ไขก่อนวันที่กำหนดการเผยแพร่

การย้ายข้อมูลโปรเจ็กต์ในไปป์ไลน์ดาวน์สตรีมไม่ใช่ความรับผิดชอบของผู้เขียนการเปลี่ยนแปลงที่ใช้ร่วมกันไม่ได้ แต่คุณสามารถดำเนินการต่อไปนี้เพื่อเร่งการย้ายข้อมูลและทำให้ทั้งผู้ใช้ Bazel และทีม Bazel Green ทำงานได้ง่ายขึ้น

1. ส่ง PR เพื่อแก้ไขโปรเจ็กต์ปลายทาง

2. ติดต่อชุมชน 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 เมื่อรวมคอมมิตแล้ว