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

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 (ชื่อ 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 แล้ว ป้ายกำกับดังกล่าวจะจัดการสิ่งต่อไปนี้

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