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

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

  2. แจ้งปัญหาใน GitHub

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

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

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

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

ปัญหาเกี่ยวกับ 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 แล้ว ทีมจะดำเนินการต่อไปนี้

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

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

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

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

  1. ส่ง PR เพื่อแก้ไขโปรเจ็กต์ดาวน์สตรีม

  2. ติดต่อชุมชน 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 ปิดเมื่อผสานคอมมิต