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

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

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

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

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

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

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

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

ปัญหาใน 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 ดูวิธีการทำงานของไปป์ไลน์นี้ได้ที่นี่

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

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

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

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

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

1. ส่งคำขอให้ผสานรวมเพื่อแก้ไขโปรเจ็กต์ที่ขึ้นอยู่กับโปรเจ็กต์นี้

2. ติดต่อชุมชน Bazel เพื่อขอความช่วยเหลือเกี่ยวกับการย้ายข้อมูล (เช่น SIG ผู้เขียนกฎของ Bazel)

การพลิกธง

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

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

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