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

วันที่ รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 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 ได้ง่ายขึ้นจาก เครื่องมือค้นหา ตรวจสอบว่าข้อความแสดงข้อผิดพลาดนั้นมีประโยชน์และดำเนินการได้ หากเป็นไปได้ ข้อความแสดงข้อผิดพลาดควรมีชื่อของรายการที่ใช้ร่วมกันไม่ได้ แจ้ง

สำหรับเครื่องมือย้ายข้อมูล ให้พิจารณาการมีส่วนร่วม 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 ส่วนใหญ่มัก ทรัพยากร 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)

พลิกธง

ก่อนเปลี่ยนค่าเริ่มต้นของธงเป็น "จริง" โปรดตรวจสอบว่า

  • มีการย้ายข้อมูลที่เก็บหลักในระบบนิเวศ

    ในไปป์ไลน์ 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 เมื่อผสานคอมมิตเข้าด้วยกัน