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

เราจำเป็นต้องทำการเปลี่ยนแปลงที่ส่งผลกับส่วนอื่นในระบบกับ 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)

การพลิกธง

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

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

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