เอกสารฉบับนี้มุ่งเป้าไปที่ผู้ร่วมให้ข้อมูลของ Bazel
คำอธิบายสัญญาผูกมัดใน Bazel จะมีแท็ก RELNOTES: ตามด้วยบันทึกประจำรุ่น ซึ่งทีม Bazel จะใช้ข้อมูลนี้เพื่อติดตามการเปลี่ยนแปลงในแต่ละรุ่นและเขียนประกาศการเผยแพร่
ภาพรวม
การเปลี่ยนแปลงของคุณเป็นการแก้ไขบั๊กหรือไม่ ในกรณีนี้ คุณไม่จำเป็นต้องมีบันทึกประจำรุ่น โปรดระบุข้อมูลอ้างอิงเกี่ยวกับปัญหา GitHub
หากการเปลี่ยนแปลงเพิ่ม / นำออก / เปลี่ยนแปลง Bazel ในแบบที่ผู้ใช้มองเห็นได้ การพูดถึงสิ่งนี้อาจมีประโยชน์
หากการเปลี่ยนแปลงมีนัยสำคัญ ให้ทำตามนโยบายเอกสารการออกแบบก่อน
หลักเกณฑ์
ผู้ใช้จะอ่านบันทึกประจำรุ่น ดังนั้นควรเป็นประโยคสั้นๆ (ควรจะเป็น 1 ประโยค) หลีกเลี่ยงการใช้ศัพท์เฉพาะ (คำศัพท์ที่ใช้ภายในบาเซล) และควรเน้นประเด็นที่การเปลี่ยนแปลงนี้เกี่ยวกับ
ระบุลิงก์ไปยังเอกสารที่เกี่ยวข้อง บันทึกประจำรุ่นเกือบทั้งหมด ควรมีลิงก์อยู่ด้วย หากคำอธิบายกล่าวถึง Flag, ฟีเจอร์ และชื่อคำสั่ง ผู้ใช้น่าจะอยากทราบข้อมูลเพิ่มเติมเกี่ยวกับสิ่งนี้
ใช้เครื่องหมายอัญประกาศเดี่ยวรอบโค้ด สัญลักษณ์ ธง หรือคำใดๆ ที่มีขีดล่าง
อย่าคัดลอกและวางรายละเอียดข้อบกพร่อง เกมเหล่านี้มักไม่ค่อยมีเหตุผลและฟังดูสมเหตุสมผล สำหรับเราและทำให้ผู้ใช้เกาหัวได้ บันทึกประจำรุ่นมีไว้เพื่ออธิบายสิ่งที่เปลี่ยนแปลงและเหตุผลในภาษาที่ผู้ใช้เข้าใจได้
ใช้รูปแบบปัจจุบันเสมอ และรูปแบบ "ตอนนี้ Bazel รองรับ Y แล้ว" หรือ "X Now รองรับ Z" เราไม่ต้องการให้บันทึกประจำรุ่นของเราฟังดูเหมือนรายการข้อบกพร่อง ข้อความเผยแพร่ทั้งหมด ควรให้ข้อมูลและใช้รูปแบบและภาษาที่สอดคล้องกัน
หากมีสิ่งใดที่เลิกใช้งานแล้วหรือถูกนำออก ให้ใช้ "X เลิกใช้งานแล้ว" หรือ "X ถูกนำออก" ไม่ใช่ "ถูกนำออก" หรือ "ถูกนำออกแล้ว"
หากตอนนี้ Bazel ทำสิ่งที่ต่างออกไป ให้ใช้ "X ตอนนี้ $newBehavior แทน $oldBehavior" ในสถานการณ์ปัจจุบัน ช่วยให้ผู้ใช้ทราบรายละเอียดเกี่ยวกับสิ่งที่จะเกิดขึ้นเมื่อใช้เวอร์ชันใหม่
หากปัจจุบัน Bazel รองรับหรือไม่รองรับบางอย่างอีกต่อไป ให้ใช้ "ตอนนี้ Bazel รองรับ/ไม่รองรับ X แล้ว"
อธิบายว่าทำไมบางสิ่งจึงถูกนำออก / เลิกใช้งาน / มีการเปลี่ยนแปลง แค่ประโยคเดียวก็เพียงพอแล้ว แต่เราอยากให้ผู้ใช้ประเมินผลกระทบต่อบิลด์ได้
อย่าให้คำมั่นสัญญาเกี่ยวกับฟังก์ชันการทำงานในอนาคต หลีกเลี่ยง "เราจะนำธงนี้ออก" หรือ "จะมีการเปลี่ยนแปลง" ทำให้เกิดความไม่แน่นอน สิ่งแรกที่ผู้ใช้จะสงสัยคือ "เมื่อใด" และเราไม่ต้องการให้พวกเขาเริ่มกังวลว่าสิ่งที่บิลด์ปัจจุบันจะพังในเวลาที่ไม่รู้จัก
ขั้นตอน
ในกระบวนการเผยแพร่ เราได้รวบรวมแท็ก RELNOTES ของคอมมิตทุกรายการ เราคัดลอกทุกอย่างลงใน Google เอกสาร
ซึ่งเราจะตรวจสอบ แก้ไข และจัดระเบียบโน้ต
ผู้จัดการรุ่นจะส่งอีเมลไปยังรายชื่ออีเมลของ bazel-dev ผู้ให้ข้อมูลร่วมกันของ Bazel จะได้รับเชิญให้มีส่วนร่วมในเอกสาร และตรวจสอบว่าการเปลี่ยนแปลงแสดงอย่างถูกต้องในประกาศ
หลังจากนั้น ระบบจะส่งประกาศไปยังบล็อก Bazel โดยใช้ที่เก็บ Bazel-blog