รุ่นและการเปลี่ยนแปลง

การเปลี่ยนแปลงของทุกเวอร์ชันจดไว้สองที่ใน repository คือรายการสั้น ๆ ใน changelog และไฟล์บันทึกประจำรุ่นที่ละเอียดกว่า

Changelog

CHANGELOG.md รวมทุกรุ่นของ TomeCMS ไว้ เรียงจากใหม่ไปเก่า พร้อมวันที่ของแต่ละรุ่น รูปแบบของไฟล์ทำตาม Keep a Changelog และการนับเวอร์ชันทำตาม Semantic Versioning สิ่งที่เปลี่ยนไปหลังรุ่นล่าสุดจะรออยู่ใต้หัวข้อ “Unreleased”

ตั้งแต่ 0.8.0 เป็นต้นมา แต่ละรายการแบ่งเป็นสิ่งที่เพิ่ม สิ่งที่เปลี่ยน สิ่งที่แก้ วิธีอัปเกรด และสิ่งที่เปลี่ยนไปสำหรับคนเขียนธีม ปลั๊กอิน และเว็บแบบ headless ส่วนรายการก่อนหน้านั้นเป็นรายการสั้น ๆ ทุกรายการจบด้วยลิงก์ไปยังบันทึกฉบับเต็มของรุ่นนั้น

บันทึกประจำรุ่น

docs/releases/ เก็บไฟล์ไว้รุ่นละหนึ่งไฟล์ เริ่มจาก 0.2.0.md แต่ละไฟล์เปิดด้วยวันที่และสถานะของรุ่น ตั้งแต่ 0.3.0 เป็นต้นมา จะมีหัวข้อ “Upgrading” บอกว่าการอัปเกรดต้องทำอะไร เช่น migration ที่ต้องรัน และการตั้งค่าหรือ dependency ใหม่ ไฟล์รุ่นหลัง ๆ ยังบอกด้วยว่าอะไรเปลี่ยนไปสำหรับคนเขียนธีม ปลั๊กอิน และเว็บแบบ headless ไฟล์เหล่านี้ทุกไฟล์จบด้วยหัวข้อ “Validation boundary” ซึ่งบอกว่ารุ่นนั้นผ่านการทดสอบอะไรมาแล้ว และยังต้องผ่านอะไรอีกก่อนจะติด tag สำหรับใช้งานจริง

ก่อนอัปเกรดเว็บที่ติดตั้งไว้ ให้อ่านบันทึกของทุกรุ่นที่ใหม่กว่ารุ่นของคุณ หน้าการอัปเดต อธิบายขั้นตอนการอัปเกรด

docs/releases/1.0.0.md ยังอธิบายเส้นทางการอัปเดตที่ 1.0.0 รองรับ และบันทึกผลการทดสอบรับการติดตั้งแบบ managed บนเซิร์ฟเวอร์จริงไว้ด้วย

ออกเวอร์ชันใหม่อย่างไร

งานทั้งหมดทำบน branch develop ส่วน main เก็บโค้ดที่ออกเป็นเวอร์ชันแล้ว และจะเปลี่ยนก็ต่อเมื่อ merge develop เข้าไปเท่านั้น

จะออกเวอร์ชันใหม่ ให้เปลี่ยนเวอร์ชันใน package.json บน develop เปลี่ยนหัวข้อ “Unreleased” ใน changelog เป็นเวอร์ชันนั้น เขียนบันทึกประจำรุ่นไว้ที่ docs/releases/<version>.md และตั้งค่า TOMECMS_VERSION ใน deploy/cloud-init.yaml ให้เป็น tag ใหม่ CI จะไม่ผ่านจนกว่าจะตั้งค่านั้น แล้ว merge เข้า main CI รันบน develop และ pull request แต่ไม่รันบน main เพราะการ merge เป็นแบบ fast-forward commit บน main จึงเป็น commit ที่ CI รันไปแล้ว workflow จะรอจน CI ของ commit นั้นผ่าน แล้วติด tag vX.Y.Z ให้ แล้ว build ตัว release จาก tag ได้แก่ image, attestation, update manifest และ GitHub release ซึ่งใช้ไฟล์บันทึกของเวอร์ชันนั้นเป็นคำอธิบาย ถ้า merge โดยไม่ได้เปลี่ยนเวอร์ชันจะไม่มีอะไรออก ถ้าเวอร์ชันใหม่ยังไม่มีไฟล์บันทึก workflow จะหยุดก่อนติด tag และ commit ที่ CI ไม่เคยรัน เช่น merge commit หรือการแก้ที่ push ตรงเข้า main จะไม่ถูกออกเป็น release

เวอร์ชัน 1.x หมายความว่าอะไร

ตั้งแต่ 1.0.0 เป็นต้นไป การนับเวอร์ชันทำตาม Semantic Versioning patch release เช่น 1.0.1 มีแต่การแก้ไขข้อบกพร่อง minor release เช่น 1.1.0 เพิ่มฟีเจอร์และไม่ทำให้สิ่งที่เคยใช้ได้เสีย รวมถึงcontent API ภายใต้ /api/v1 ส่วนการเปลี่ยนที่ทำให้ของเดิมใช้ไม่ได้จะรอไปถึง 2.0.0 การติดตั้งแบบ managed ติดตั้งทุกรุ่นเหล่านี้ได้จากหน้าแอดมิน ตามที่หน้าการอัปเดต อธิบายไว้

เวอร์ชัน 0.x เคยหมายความว่าอะไร

ส่วนหัวของ changelog บอกว่าเวอร์ชัน 0.x ทุกเวอร์ชันเป็นรุ่นทดลองก่อน 1.0 และไม่มีรุ่นไหนมีไว้ใช้งานจริง บันทึกประจำรุ่นจนถึง 0.12.0 เขียนสถานะว่า “Release candidate; not tagged for production” ตั้งแต่ 0.12.1 เป็นต้นไป แต่ละเวอร์ชันจะติด tag และออกเป็น GitHub release ด้วย หน้า “ระบบ” ของเว็บที่ติดตั้งไว้จึงตรวจหาเวอร์ชันใหม่ได้ และบันทึกประจำรุ่นจะเขียนสถานะว่า “Release candidate; tagged and published as a GitHub release, not for production”

เว็บที่ติดตั้งด้วย 0.x อัปเกรดได้ในที่เดิม โดยดึงโค้ดรุ่นใหม่แล้วรันสคริปต์ deploy อีกครั้ง ตามที่หน้าการอัปเดต อธิบายไว้

สายนี้ไม่ต่อเนื่องไปถึง 1.0.0 เว็บที่ติดตั้งด้วย 0.x จะกลายเป็นการติดตั้งแบบ managed ของ 1.0.0 ในที่เดิมไม่ได้ การย้ายไป 1.0.0 ต้องใช้เซิร์ฟเวอร์ใหม่ ตามที่หน้าติดตั้งบน VPS อธิบายไว้

ตั้งแต่ 0.11.0 จนถึง 1.0.0 TomeCMS งดเพิ่มฟีเจอร์ใหม่ และรับเฉพาะการแก้ไขข้อบกพร่อง ตั้งแต่ 1.0.0 เป็นต้นไป กลับมารับฟีเจอร์ใหม่อีกครั้ง หน้าวิธีร่วมพัฒนา บอกว่า pull request ต้องมีอะไรบ้าง