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

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