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

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

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

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

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

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

  5. เปลี่ยนสถานะเป็นเข้ากันได้

ปัญหาใน GitHub

แจ้งปัญหาใน GitHub ในที่เก็บ Bazel ดูตัวอย่าง

เราขอแนะนำให้คุณดำเนินการดังนี้

  • ชื่อจะขึ้นต้นด้วยชื่อของฟีเจอร์ (ชื่อฟีเจอร์จะขึ้นต้นด้วย incompatible_)

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

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

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

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

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

การใช้งาน

สร้างแฟล็กใหม่ใน Bazel ค่าเริ่มต้นต้องเป็นเท็จ ข้อความช่วยเหลือ ควรมี URL ของปัญหาใน GitHub เนื่องจากชื่อฟีเจอร์เริ่มต้นด้วย incompatible_ จึงต้องมีแท็กข้อมูลเมตา ดังนี้

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

ในคำอธิบายการคอมมิต ให้เพิ่มสรุปสั้นๆ ของฟีเจอร์ นอกจากนี้ ให้เพิ่ม RELNOTES: ในรูปแบบต่อไปนี้ RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

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

ป้ายกำกับ

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

หากพบปัญหาเกี่ยวกับการแจ้งเตือนและยังไม่คาดหวังให้ผู้ใช้ย้ายข้อมูล ให้ทำดังนี้ นำการแจ้งเตือนออก migration-ready

หากคุณวางแผนที่จะเปลี่ยนสถานะของฟีเจอร์ในรุ่นหลักถัดไป ให้เพิ่มป้ายกำกับ "breaking-change-X.0" ลงในปัญหา

การอัปเดตที่เก็บ

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

หากต้องการตรวจสอบสถานะการย้ายข้อมูลของโปรเจ็กต์เหล่านั้น คุณสามารถใช้bazelisk-plus-incompatible-flagsไปป์ไลน์ และดูวิธีการทำงานของไปป์ไลน์นี้ได้ที่นี่

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

  1. ยื่นปัญหาใน Github เพื่อแจ้งให้เจ้าของโปรเจ็กต์ดาวน์สตรีมที่การเปลี่ยนแปลงที่ไม่เข้ากันของคุณทำให้เกิดปัญหาทราบ
  2. ส่งคำขอให้รวมการเปลี่ยนแปลงเพื่อแก้ไขโปรเจ็กต์ที่ขึ้นอยู่กับโปรเจ็กต์นี้
  3. ติดต่อชุมชน Bazel เพื่อขอความช่วยเหลือเกี่ยวกับการย้ายข้อมูล (เช่น SIG ผู้เขียนกฎของ Bazel)

การพลิกธง

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

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

    ในไปป์ไลน์ bazelisk-plus-incompatible-flags ธงควรปรากฏในส่วน The following flags didn't break any passing Bazel team owned/co-owned projects

  • ข้อกังวลและคำถามของผู้ใช้ได้รับการแก้ไขแล้ว

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

เมื่อเปลี่ยนค่าเริ่มต้นของฟีเจอร์เป็น "จริง" โปรดทำดังนี้

  • ใช้ RELNOTES[INC] ในคำอธิบายการคอมมิตโดยมีรูปแบบดังนี้ RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details คุณสามารถใส่ข้อมูลเพิ่มเติมในส่วนที่เหลือของคำอธิบายการคอมมิตได้
  • ใช้ Fixes #xyz ในคำอธิบายเพื่อให้ระบบปิดปัญหาใน GitHub เมื่อผสานรวมการเปลี่ยนแปลง
  • ตรวจสอบและอัปเดตเอกสารประกอบหากจำเป็น
  • ยื่นปัญหาใหม่ #abc เพื่อติดตามการนำการแจ้งว่าไม่เหมาะสมออก

การนำธงออก

หลังจากเปลี่ยนสถานะฟีเจอร์ที่ HEAD แล้ว ควรนำออกจาก Bazel ในที่สุด เมื่อวางแผนที่จะนำฟีเจอร์ที่ไม่รองรับออก ให้ทำดังนี้

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