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