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

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

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

ภาพรวม

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

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

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

หลักเกณฑ์

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

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

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

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

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

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

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

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

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

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

กระบวนการ

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

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

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