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

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

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

ภาพรวม

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

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

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

หลักเกณฑ์

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

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

• ใช้เครื่องหมายคำพูดย้อนกลับรอบโค้ด สัญลักษณ์ แฟลก หรือคำใดๆ ที่มีขีดล่าง

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

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

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

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

• หาก Bazel รองรับหรือไม่รองรับบางสิ่งในตอนนี้ ให้ใช้ "ตอนนี้ Bazel รองรับ/ไม่รองรับ X แล้ว"

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

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

กระบวนการ

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

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

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