เอกสารนี้มีไว้สำหรับผู้มีส่วนร่วมใน 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