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

รายงานปัญหา ดูแหล่งที่มา รุ่น 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 ดูตัวอย่าง

เราขอแนะนําให้ทําดังนี้

  • ชื่อจะขึ้นต้นด้วยชื่อแฟล็ก (ชื่อแฟล็กจะขึ้นต้นด้วย incompatible_)

  • คุณเพิ่มป้ายกำกับ incompatible-change

  • คำอธิบายจะมีคำอธิบายการเปลี่ยนแปลงและลิงก์ไปยังเอกสารการออกแบบที่เกี่ยวข้อง

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

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

สําหรับเครื่องมือย้ายข้อมูล ให้ลองมีส่วนร่วมใน Buildifier โดยสามารถแก้ไขไฟล์ BUILD, WORKSPACE และ .bzl ได้โดยอัตโนมัติ นอกจากนี้ยังอาจรายงานคำเตือนด้วย

การใช้งาน

สร้าง Flag ใหม่ใน Bazel ค่าเริ่มต้นต้องเป็น False ข้อความช่วยเหลือควรมี URL ของปัญหาใน GitHub เนื่องจากชื่อ Flag ขึ้นต้นด้วย 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)

การพลิกสถานะ

โปรดตรวจสอบสิ่งต่อไปนี้ก่อนเปลี่ยนค่าเริ่มต้นของ 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 เพื่อติดตามการนําการแจ้งว่าไม่เหมาะสมออก

การนำการแจ้งว่าไม่เหมาะสมออก

หลังจากพลิกธงที่ HEAD แล้ว ควรนำเครื่องหมายออกจาก Bazel ในที่สุด สิ่งที่จะเกิดขึ้นเมื่อคุณนำการแจ้งว่าไม่เหมาะสมออกคือ

  • พิจารณาให้เวลาผู้ใช้ในการย้ายข้อมูลนานขึ้นหากเป็นการเปลี่ยนแปลงที่สำคัญซึ่งเข้ากันไม่ได้ โดยหลักการแล้ว Flag ควรพร้อมใช้งานในเวอร์ชันหลักอย่างน้อย 1 รายการ
  • สำหรับคอมมิตที่นําการแจ้งว่าไม่สําคัญออก ให้ใช้ Fixes #abc ในคําอธิบายเพื่อให้ปัญหาใน GitHub ปิดเมื่อผสานคอมมิต