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

รายงานปัญหา ดูแหล่งที่มา

หลีกเลี่ยงไม่ได้ที่เราจะทําการเปลี่ยนแปลงที่ส่งผลกับ 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" ลงในปัญหา

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

Bazel CI ทดสอบรายการโปรเจ็กต์สําคัญที่ Bazel@HEAD + ดาวน์สตรีม ทรัพยากรส่วนใหญ่มักจะพึ่งพาทรัพยากรของโปรเจ็กต์ Bazel อื่นๆ ดังนั้นการย้ายข้อมูลจึงควรเลิกบล็อกการย้ายข้อมูลสําหรับชุมชนที่กว้างขึ้น หากต้องการตรวจสอบสถานะการย้ายข้อมูลของโปรเจ็กต์เหล่านั้น ให้ใช้ไปป์ไลน์ bazelisk-plus-incompatible-flags ดูวิธีการทํางานของไปป์ไลน์นี้ที่นี่

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

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

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

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

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

  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

  • ปัญหาทั้งหมดในรายการตรวจสอบจะมีการทําเครื่องหมายว่าแก้ไขแล้ว/ปิดแล้ว

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

เมื่อแฟล็กพร้อมที่จะพลิกใน 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 รุ่น
  • สําหรับสัญญาผูกมัดที่นําแฟล็กออก ให้ใช้ Fixes #abc ในคําอธิบายเพื่อปิดใช้ปัญหา GitHub เมื่อมีการรวมสัญญาผูกมัด