วิธีการเขียนคำอธิบายเซ็ตการแก้ไขที่ดี
หลายๆเครื่องมือของ Mercurial ใช้บรรทัดแรกของคำอธิบายเซ็ตการแก้ไขเพื่อสรุปสั้นๆให้ผู้ใช้ได้อ่านว่าเป็นการแก้ไขเกี่ยวกับอะไร
เพราะฉะนั้นคุณควรจะมองบรรทัดแรกของคำอธิบายเหมือนกับหัวจดหมาย โดยบรรทัดแรกนี้ควรจะ:
- เป็นบรรทัดที่จบในตัวเอง
- ไม่ยาวมากนัก (ไม่เกิน 65 ตัวอักษรภาษาอังกฤษ)
- อธิบายคร่าวๆเกี่ยวกับเนื้อหาของเซ็ตการแก้ไข
ด้านล่างนี้เป็นตัวอย่างของคำอธิบายที่ดี:
เวอรชั่นแรกของระบบ veeblefrotzer ใช้เทคนิค McWhirly/O'Blivet เวอร์ชั่นแสดงผลถูกต้องสำหรับวันที่ 12 ของทุกๆเดือน แต่ยังใช้ไม่ได้กับวันอื่นๆ
คำอธิบายด้านบนเป็นตัวอย่างที่ดีเพราะว่า:
- บรรทัดแรกอธิบายเกี่ยวกับการแก้ไขอย่างกระชับ ได้ใจความ
- คำอธิบายสั้นและก็ให้ข้อมูลได้ดี
- มีการระบุข้อจำกัดของการแก้ไขด้วย
นี่คือตัวอย่างที่ไม่ค่อยดีนัก:
เขียนเวอร์ชั่นแรกของระบบ veeblefrotzer ซึ่งใช้วิธี McWhirly/O'Blivet เพื่อ envolvolution ของ subducted whingnangle ลองดู McWhirly, O'Blivet, "Acta Exsanguinata", vol. III, chap. 19 สำหรับคำอธิบายเกี่ยวกับเทคนิคนี้ แบบสั้นๆ ถ้าหาบทนี้ไม่เจอก็คงเพราะมีคนตัดมันออกมาแล้วเอาไปแปะอยู่ตามผนังของห้อง ทำงานที่ไหนซักที่ล่ะ
ทำไมมันถึงไม่ค่อยดีน่ะเหรอ?
- บรรทัดแรกไม่จบในบรรทัด (ต้องอ่านต่อไปยังบรรทัดที่สอง)
ไม่แบ่งย่อหน้า → ทำให้อ่านยาก
- มีรายละเอียดที่ไม่ค่อยเกี่ยวข้องกับการแก้ไขเยอะ