การเขียนบันทึกประจํารุ่น

เอกสารนี้มีไว้สำหรับผู้ร่วมให้ข้อมูลของ Bazel

คำอธิบายการคอมมิตใน Bazel มีแท็ก RELNOTES: ตามด้วยหมายเหตุประจำรุ่น ทีม Bazel ใช้แท็กนี้เพื่อติดตามการเปลี่ยนแปลงในแต่ละรุ่นและเขียนประกาศประจำรุ่น

ภาพรวม

• การเปลี่ยนแปลงของคุณเป็นการแก้ไขข้อบกพร่องใช่ไหม ในกรณีนี้ คุณไม่จำเป็นต้องมีหมายเหตุประจำรุ่น โปรดใส่ข้อมูลอ้างอิงถึงปัญหาใน GitHub

• หากการเปลี่ยนแปลงเป็นการเพิ่ม / นำออก / เปลี่ยนแปลง Bazel ในลักษณะที่ผู้ใช้มองเห็นได้ การกล่าวถึงการเปลี่ยนแปลงดังกล่าวอาจเป็นประโยชน์

หากการเปลี่ยนแปลงมีความสำคัญ ให้ปฏิบัติตามนโยบาย เอกสารการออกแบบก่อน

หลักเกณฑ์

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

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

• ใช้เครื่องหมายแบ็กควอต (`) ครอบโค้ด สัญลักษณ์ แฟล็ก หรือคำที่มีขีดล่าง

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

• ใช้กาลปัจจุบันและรูปแบบ "ตอนนี้ Bazel รองรับ Y แล้ว" หรือ "ตอนนี้ X ทำ Z ได้แล้ว" เสมอ เราไม่ต้องการให้หมายเหตุประจำรุ่นมีลักษณะเหมือนรายการข้อบกพร่อง รายการหมายเหตุประจำรุ่นทั้งหมดควรให้ข้อมูลและใช้รูปแบบและภาษาที่สอดคล้องกัน

• หากมีการเลิกใช้งานหรือนำออก ให้ใช้ "เลิกใช้งาน X แล้ว" หรือ "นำ X ออกแล้ว" ไม่ใช่ "นำออกแล้ว" หรือ "ถูกนำออกแล้ว"

• หากตอนนี้ Bazel ทำงานแตกต่างออกไป ให้ใช้ "ตอนนี้ X ทำ $newBehavior แทน $oldBehavior แล้ว" ในกาลปัจจุบัน วิธีนี้จะช่วยให้ผู้ใช้ทราบรายละเอียดสิ่งที่คาดหวังได้เมื่อใช้รุ่นใหม่

• หากตอนนี้ Bazel รองรับหรือเลิกรับรองรายการใดรายการหนึ่ง ให้ใช้ "ตอนนี้ Bazel รองรับ/เลิกรับรอง X แล้ว"

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

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

กระบวนการ

เราจะรวบรวมแท็ก RELNOTES ของการคอมมิตทุกรายการ ซึ่งเป็นส่วนหนึ่งของกระบวนการออกรุ่น จากนั้นคัดลอกทุกอย่างลงใน Google เอกสาร เพื่อตรวจสอบ แก้ไข และจัดระเบียบหมายเหตุ

ผู้จัดการการออกรุ่นจะส่งอีเมลไปยัง bazel-dev รายชื่ออีเมล เราขอเชิญผู้ร่วมให้ข้อมูลของ Bazel มาร่วมให้ข้อมูลในเอกสารและตรวจสอบว่าการเปลี่ยนแปลงของตนเองแสดงอย่างถูกต้องในประกาศ

จากนั้นจะส่งประกาศไปยังบล็อกของ Bazel โดยใช้ที่เก็บ bazel-blog