วิธีร่วมพัฒนา

TomeCMS มีผู้ดูแลอยู่คนเดียว งานที่รับเข้าได้ง่ายที่สุดจึงเป็นการแก้เล็ก ๆ ที่ตรงจุดและมีเทสต์มาด้วย หน้านี้เขียนตาม CONTRIBUTING.md ใน repository

รับทั้งการแก้ไขข้อบกพร่องและฟีเจอร์ใหม่ ฟีเจอร์ใหม่จะเข้าไปใน minor release ถัดไป และต้องไม่ทำให้สิ่งที่ใช้ได้อยู่แล้วเสีย รวมถึงcontent API ภายใต้ /api/v1

ทุกคนที่มีส่วนร่วม ทั้งใน issue, pull request และ discussion ต้องทำตามหลักปฏิบัติของชุมชน (Code of Conduct)

ก่อนเริ่ม

ถ้าจะแก้อะไรที่ใหญ่กว่าการแก้เล็ก ๆ ให้เปิด issue ก่อน แล้วบอกว่าอยากเปลี่ยนอะไรและเพราะอะไร จะได้ไม่ต้องเขียนโค้ดที่ไปคนละทางกับแผน แบบฟอร์ม issue มีสองแบบ คือ “Bug report” กับ “Feature idea”

ถ้าเจอช่องโหว่ อย่าเปิด issue ให้แจ้งแบบส่วนตัวตามที่นโยบายความปลอดภัยบอกไว้

เอกสารออกแบบและแผนการลงมือทำอยู่ใน docs/specs และ docs/plans เอกสารเหล่านี้อธิบายว่าทำไมสิ่งต่าง ๆ จึงเป็นอย่างที่เป็นอยู่

เตรียมเครื่อง

หน้าเตรียมเครื่องสำหรับพัฒนา อธิบายทั้งบน macOS และ Windows หน้าโครงสร้างโปรเจกต์ บอกว่าอะไรอยู่ตรงไหน ส่วนหน้าเขียนธีม กับเขียนปลั๊กอิน อธิบายสองทางที่ต่อยอด TomeCMS ได้

หลักที่โค้ดยึดไว้

สองภาษา

ข้อความของแอดมินอยู่ใน src/lib/admin-i18n.ts และข้อความของหน้าเว็บสาธารณะอยู่ใน src/lib/i18n.ts ทุกข้อความเขียนไว้ทั้งภาษาอังกฤษและภาษาไทย ในไฟล์ของแอดมิน ชุดข้อความภาษาไทยประกาศ type ให้ตรงกับชุดภาษาอังกฤษ ถ้าขาดข้อความไหนไป การตรวจ type จะไม่ผ่าน

ใช้ design token ชุดเดียว

สี ระยะห่าง ความโค้งมุม และตัวอักษร มาจาก src/styles/installer-tokens.css เท่านั้น DESIGN.md อธิบาย token เหล่านี้ และ npm run check จะไม่ผ่านถ้าสองไฟล์นี้ไม่ตรงกัน

ปลั๊กอินบอก แกนระบบวาด

ปลั๊กอินส่งข้อมูลกลับมาเท่านั้น และไม่มีอะไรที่ปลั๊กอินส่งกลับมาถูกเขียนลงในหน้าเว็บเป็น markup หน้าเขียนปลั๊กอิน อธิบายข้อตกลงนี้

ไฟล์ migration มีแต่เพิ่ม ไม่มีแก้

การเปลี่ยนโครงสร้างฐานข้อมูลแต่ละครั้งคือไฟล์ใหม่ที่มีหมายเลขกำกับใน src/server/db/migrations/ และลงทะเบียนไว้ใน src/server/db/migrator.ts ถ้าเพิ่มตารางใหม่ ต้องใส่ตารางนั้นใน src/server/db/reset-tables.ts ด้วย ไฟล์นี้กำหนดว่าตอนรีเซ็ตการติดตั้งจะล้างตารางไหนบ้าง และการตรวจ type จะไม่ผ่านจนกว่าจะใส่ตารางนั้นไว้ migration ที่ออกไปแล้วจะไม่ถูกแก้อีกเลย

ทำตามแบบที่มีอยู่

ตั้งชื่อ เขียนคอมเมนต์ และจัดโครงสร้างให้เข้ากับโค้ดรอบ ๆ ส่วนที่คุณแก้ และอย่าจัดรูปแบบโค้ดส่วนที่คุณไม่ได้แก้

เทสต์

เขียนเทสต์ก่อน ดูให้เห็นว่าเทสต์ไม่ผ่าน แล้วจึงแก้โค้ดให้ผ่าน การแก้ข้อบกพร่องต้องมาพร้อมเทสต์ที่จะจับข้อบกพร่องนั้นได้

npm run check
npm run test:unit
node scripts/test-foundation.mjs tests/integration/<file>.test.ts
npm run test:e2e -- tests/e2e/<file>.spec.ts

npm run check รัน astro check การตรวจ design token และการทดสอบตัวเองของสคริปต์ต่าง ๆ เทสต์ integration กับเทสต์ในเบราว์เซอร์เปิด PostgreSQL กับ SeaweedFS แบบใช้แล้วทิ้งของตัวเองผ่าน Docker Compose และลบทิ้งเมื่อจบ เทสต์ในเบราว์เซอร์รันบน Playwright ทั้งสอง project คือเดสก์ท็อปกับโทรศัพท์ หน้าการทดสอบ บอกว่าแต่ละคำสั่งต้องมีอะไร

การ commit และ pull request

• ข้อความ commit ใช้รูปแบบ Conventional Commits คือ type(scope): what changed โดย type เป็นหนึ่งใน feat, fix, refactor, docs, test, chore, perf หรือ ci ส่วนเนื้อความบอกว่าแก้เพราะอะไร
• เปิด pull request ไปที่ branch develop ซึ่งเป็นที่ทำงานหลัก ส่วน main จะเปลี่ยนก็ต่อเมื่อออกเวอร์ชันใหม่เท่านั้น
• pull request หนึ่งอันแก้เรื่องเดียว และกรอกแบบฟอร์มให้ครบ แบบฟอร์มถามว่าคุณเปลี่ยนอะไร เพราะอะไร และรันอะไรไปแล้วบ้าง
• ถ้าการแก้นั้นมองเห็นได้ ให้แนบภาพหน้าจอทั้งธีมสว่างและธีมมืด และที่ความกว้างของโทรศัพท์
• อย่า commit ข้อมูลลับสำหรับเข้าระบบ ไฟล์ .env ไฟล์ dump ของฐานข้อมูล หรือไฟล์สำรองข้อมูล

สัญญาอนุญาต

TomeCMS เผยแพร่ภายใต้ MIT License การร่วมพัฒนาถือว่าคุณยอมรับให้งานที่คุณส่งมาเผยแพร่ภายใต้สัญญาอนุญาตเดียวกัน