ร่วมพัฒนา TESA Open Knowledge

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

English: CONTRIBUTING.en.md

ก่อนเริ่ม: ข้อตกลงเมื่อร่วมพัฒนา

เมื่อคุณส่งงานเข้าคลังนี้ คุณยืนยันว่า

1. คุณมีสิทธิ์ส่งงานนั้น และยอมให้เผยแพร่ภายใต้สัญญาอนุญาตของตำแหน่งที่งานนั้นอยู่ (ตารางในหัวข้อ “สัญญาอนุญาตแยกตามตำแหน่ง”)
2. งานของคุณจะเผยแพร่เป็นส่วนหนึ่งของ TESA Open Knowledge โดยมีเครดิตของสมาคมสมองกลฝังตัวไทย (Thai Embedded Systems Association: TESA) ตาม ATTRIBUTION.md ส่วนชื่อของคุณจะอยู่ในประวัติ git และในรายชื่อ authors ของ course.yaml สำหรับงานเขียนที่เป็นเนื้อหาสาระ
3. คุณปฏิบัติตาม จรรยาบรรณของชุมชน

DCO sign-off (ทุก commit)

เราใช้ Developer Certificate of Origin 1.1 แทนการเซ็น CLA การ sign-off คือการรับรองว่าคุณมีสิทธิ์ส่งงานนั้นภายใต้สัญญาอนุญาตของโครงการ ทำได้ด้วยการเติม -s ตอน commit

git commit -s -m "แก้คำอธิบาย PWM ในบทเรียน aiot-mpy.m02.l03"

git จะต่อท้ายข้อความ commit ด้วยบรรทัด

Signed-off-by: ชื่อจริงของคุณ <อีเมลของคุณ>

• ใช้ชื่อและอีเมลที่ติดต่อได้จริง (ตั้งด้วย git config user.name และ git config user.email)
• ถ้าลืม sign-off ใน commit ล่าสุด แก้ด้วย git commit --amend -s --no-edit ถ้าลืมหลาย commit ใช้ git rebase --signoff main
• ถ้าแก้ไฟล์ผ่านหน้าเว็บ GitHub ให้เขียนบรรทัด Signed-off-by: ในข้อความ commit เอง

PR ที่มี commit ไม่ได้ sign-off จะยังไม่ถูก merge

ผู้เขียนคือคน

ชื่อผู้เขียน ผู้ร่วมเขียน และผู้ sign-off ต้องเป็นคนจริงเท่านั้น ถ้าใช้ผู้ช่วย AI เขียนโค้ดหรือเนื้อหา ห้ามใส่บรรทัด Co-authored-by: หรือข้อความท้าย “Generated with …” ที่ให้เครดิตผู้ช่วย AI ทั้งใน commit และในไฟล์ คุณเป็นผู้รับผิดชอบงานที่ส่งตามที่รับรองไว้ใน DCO CI ตรวจทุก commit และทุกไฟล์ (tools/check_authorship.py และ tools/validate.py) และจะไม่ผ่านถ้าพบ

เลือกวิธีร่วมพัฒนา

อยากทำอะไร	เริ่มที่
แจ้งเนื้อหาผิด ลิงก์เสีย โค้ดรันไม่ผ่าน	แจ้ง erratum
เสนอบทเรียนหรือหลักสูตรใหม่	เสนอบทเรียน ก่อนเริ่มเขียน
แปลหรือตรวจคำแปล	งานแปล
เฟิร์มแวร์หรือ toolchain รุ่นใหม่ทำให้บทเรียนพัง	แจ้งปัญหา toolchain
พบช่องโหว่หรือข้อมูลลับหลุด	อย่าเปิด issue สาธารณะ ดู SECURITY.md

การแก้เล็ก ๆ เช่น คำผิด ส่ง pull request ได้เลยโดยไม่ต้องเปิด issue ก่อน

ขั้นตอนเขียนหรือแก้บทเรียน

1. เปิด issue เสนอบทเรียน สำหรับงานใหญ่ เพื่อตกลงเป้าหมาย ระดับ และ skill ID กับหัวหน้าหลักสูตรก่อนลงแรงเขียน

2. fork แล้วสร้าง branch เช่น lesson/aiot-mpy-m02-l04

3. คัดลอกแม่แบบ จาก templates/

   • บทเรียน: templates/lesson/ ไปไว้ที่ courses/<course-id>/mNN-<slug>/lNN-<slug>/
   • โมดูล: templates/module/README.md
   • หลักสูตรใหม่: templates/course/

4. เขียนตามคู่มือผู้เขียน templates/AUTHORING.md ซึ่งอธิบาย front matter, ลำดับหัวข้อ, quiz, สไลด์ และกติกาการสอน

5. ตรวจด้วย validator ก่อนส่ง

   python3 tools/validate.py

   validator ตรวจโครงสร้างเนื้อหา เช่น schema ของ YAML และ front matter, skill ID และไฟล์ที่ถูกอ้างถึง ต้องผ่านทั้งหมด เมื่อเปิด pull request แล้ว CI จะตรวจเพิ่มเรื่องคำต้องห้าม เครดิตภาพ ลิงก์ และสัญญาอนุญาตของแต่ละไฟล์

6. รันโค้ดจริง บนบอร์ดหรือ BENTO Emulator แล้วจดชื่อบอร์ด เวอร์ชันเฟิร์มแวร์ และเวอร์ชัน toolchain หรือ emulator ไว้ใน PR

7. เปิด pull request แล้วกรอก checklist ในแม่แบบ PR ให้ครบ

กติกาเรื่องคำ

หน่วยการเรียนรู้ในคลังนี้คือ เส้นทาง (pathway) → หลักสูตร (course) → โมดูล (module) → บทเรียน (lesson)

• ในข้อความที่ผู้เรียนอ่าน ห้ามใช้คำว่า คาบ หรือ คาบเรียน ในความหมายของช่วงเวลาเรียน และห้ามใช้ session N หรือ Session N เรียกหน่วยการเรียนรู้ ให้ใช้ บทเรียน, โมดูล, หลักสูตร แทน ในหลักสูตร AIoT in Action ใช้คำว่า “ตอน” แทนโมดูลได้ถ้าจำเป็น
• ข้อยกเว้น: คาบ ในความหมายของคาบของสัญญาณถูกต้องและใช้ได้ เช่น คาบของ PWM ให้เขียนว่า คาบเวลา (period)
• เรียกผู้อ่านว่า “ผู้เรียน” ไม่ใช้กรอบของชั้นเรียนมหาวิทยาลัย เช่น การระบุคณะหรือมหาวิทยาลัยของผู้เรียน สัดส่วนคะแนน คำเรียกแบบรุ่นพี่รุ่นน้อง หรือการบังคับจำนวนคนต่อกลุ่ม
• เขียนภาษาไทยเป็นหลัก ใช้ศัพท์เทคนิคภาษาอังกฤษได้ ศัพท์ที่ใช้บ่อยอยู่ใน glossary/terms.yaml
• ชื่อตัวแปร ฟังก์ชัน และไฟล์เป็นภาษาอังกฤษ

CI ตรวจคำต้องห้ามในบทเรียนให้อัตโนมัติ แต่อ่านบริบทไม่ได้ ถ้าคุณใช้ “คาบเวลา” ถูกความหมายแล้วยังถูกเตือน ให้บอกใน PR

สัญญาอนุญาตแยกตามตำแหน่ง

ตำแหน่ง	สัญญาอนุญาต
เนื้อหา Markdown, สไลด์, ภาพที่คุณทำเอง ใน courses/	CC BY-NC 4.0 (พร้อมคำอนุญาตเพิ่มใน ATTRIBUTION.md)
แม่แบบในโฟลเดอร์ resources/ ของบทเรียน	CC BY 4.0
โค้ดใหม่ (ตัวอย่าง แบบฝึก เฉลย เครื่องมือ เว็บไซต์)	Apache-2.0
โค้ดที่นำเข้าจากหลักสูตร AIoT in Action ของ AIC	MIT (คงบรรทัดลิขสิทธิ์เดิม)
skills/	CC BY-SA 4.0
ภาพหรือไฟล์จากบุคคลที่สาม	ตามต้นทาง และต้องลงทะเบียนใน credits.yaml

ไฟล์โค้ดใหม่ให้ขึ้นต้นด้วย SPDX header

Apache-2.0

# SPDX-FileCopyrightText: 2026 Thai Embedded Systems Association (TESA)

ตัวอย่างโค้ดของ Infineon ให้ลิงก์ไปยัง repository และ tag เป็นค่าเริ่มต้น ถ้าจำเป็นต้องคัดลอก ต้องคง header และไฟล์สัญญาอนุญาตเดิม และอ้างอิงแหล่งให้ครบ ดู NOTICE.md

ภาพและเครดิต

• ทุกภาพที่ไม่ได้ทำเองต้องมีรายการใน courses/<course-id>/credits.yaml ได้แก่ path, title, author, source, license (SPDX ID หรือ own สำหรับภาพที่ทำเอง) และ modified (true ถ้าแก้ภาพ เช่น ใส่คำไทย)
• ภาพ CC BY-SA ที่ถูกแก้จะกลายเป็น CC BY-SA ด้วย ระบุให้ถูก
• ภาพไม่มีสัญญาอนุญาตที่ชัดเจน ห้ามใช้
• ทุกภาพต้องมีข้อความ alt ที่บอกว่าภาพแสดงอะไร
• CREDITS.md สร้างอัตโนมัติจาก credits.yaml ไม่ต้องแก้เอง
• ไฟล์หนึ่งไฟล์ต้องไม่เกิน 5 MB และไม่เพิ่มไฟล์วิดีโอ

ฉบับแปล

• ภาษาไทยเป็นต้นฉบับ (README.md) ภาษาอังกฤษอยู่ข้างกันในโฟลเดอร์เดียว (README.en.md)
• ฟิลด์ translation ใน front matter ของฉบับไทยบอกสถานะ: done เมื่อ README.en.md ตรงกับฉบับไทยล่าสุด หรือ pending เมื่อยังไม่มีหรือยังไม่ได้ปรับตาม
• ถ้าแก้ฉบับไทยจนสาระเปลี่ยน ให้แก้ฉบับอังกฤษด้วย หรือเปลี่ยนสถานะเป็น pending
• ร่างจากเครื่องแปลใช้ได้ แต่ต้องมีคนตรวจทานก่อน merge และบอกใน PR ว่าใช้เครื่องแปลช่วย
• โค้ดใช้ร่วมกันทั้งสองภาษา ไม่ต้องแยกไฟล์ตามภาษา

ห้ามส่งข้อมูลลับและข้อมูลภายใน

• ห้ามมีรหัส Wi-Fi, token, รหัสผ่าน broker หรือกุญแจจริงในโค้ดหรือภาพหน้าจอ ใช้ค่าตัวแทน เช่น "<your-password>"
• ก่อนส่ง PR ให้ค้นไฟล์ของคุณด้วยคำว่า PASSWORD, SECRET, TOKEN, API_KEY แล้วดูว่าทุกค่าเป็นค่าตัวแทน
• ห้ามใส่ path ภายในเครื่องหรือเซิร์ฟเวอร์ และห้ามลิงก์ไปเอกสารภายใน
• ใช้โดเมน tesaiot.dev เท่านั้น เช่น BENTO IDE ที่ https://ide.tesaiot.dev/ และ Developer Hub ที่ https://dev.tesaiot.dev/

การตรวจและการ merge

• ทุก PR ต้องผ่าน validator, งาน CI และ DCO
• บทเรียนใหม่หรือการแก้ที่เปลี่ยนสาระ ต้องผ่าน การตรวจสองชั้น: ผู้ตรวจทางเทคนิครันโค้ดบนบอร์ดจริงหรือ emulator และผู้ตรวจด้านการสอนตรวจเป้าหมาย เวลา prerequisite และ skill ID
• erratum ที่ไม่เปลี่ยนสาระ ใช้การอนุมัติหนึ่งคน
• หัวหน้าหลักสูตรที่ระบุใน .github/CODEOWNERS เป็นผู้ merge
• สถานะของบทเรียน (pre-alpha → alpha → beta → stable) และเกณฑ์เลื่อนสถานะอยู่ใน GOVERNANCE.md

ถ้าติดตรงไหน ถามใน issue ได้เลย เราช่วยกันแกะได้