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

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