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

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