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

เอกสารนี้จัดทําขึ้นที่ผู้ร่วมให้ข้อมูลใน Bazel

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

ภาพรวม

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

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

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

หลักเกณฑ์

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

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

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

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

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

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

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

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

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

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

กระบวนการ

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

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

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