วิธีสร้าง What is New Popup ใน Frappe App ด้วย Change Log

Frappe Framework มี Built-in Feature สำหรับแสดง "What's New" Popup Dialog ให้ User เมื่อพวกเขา Login หลังจาก App มีการ Update เวอร์ชัน Feature นี้ช่วยให้ User รู้ว่ามี Features ใหม่หรือ Bug Fixes อะไรบ้าง

วิธีการทำงาน

เมื่อ User Login หลังจาก App Update, Frappe จะ:

1. ตรวจจับ Version Changes - เปรียบเทียบ __version__ ของ App กับ Version ที่เก็บไว้
2. ค้นหา Change Log Files - หาไฟล์ที่ตรงกับ Version ใหม่
3. แสดง Modal Dialog - Title "Updated To A New Version 🎉"
4. แสดง Updates - จาก "Updates detailed" sections ใน Markdown Files

โครงสร้าง Directory

your_app/
├── your_app/
│   ├── __init__.py          # มี __version__ = "x.y.z"
│   └── change_log/
│       ├── current/
│       │   ├── readme.md    # Placeholder (จำเป็น)
│       │   └── changes.md   # Placeholder ว่าง
│       ├── v0/              # Major Version 0.x.x
│       │   └── v0_9_2.md
│       └── v1/              # Major Version 1.x.x
│           ├── v1_0_0.md
│           ├── v1_1_0.md
│           └── v1_5_0.md

การตั้งชื่อไฟล์

• Directory: v{major}/ - Group ตาม Major Version
• File: v{major}_{minor}_{patch}.md - Version ด้วย Underscores
• ตัวอย่าง: Version 1.5.0 → v1/v1_5_0.md

รูปแบบ Markdown File

แต่ละ Version File ใช้ Format นี้:

# Updates detailed

- Feature description พร้อมคำอธิบายสั้นๆ
- อีก Feature หรือ Improvement
- Extended settings:
  - Sub-feature 1
  - Sub-feature 2
  - Sub-feature 3

# Updates detailed

- Section ที่สองของ Updates (Optional)
- Features หรือ Fixes เพิ่มเติม

กฎ Format

1. Title: ต้องเป็น # Updates detailed (ตรงเป๊ะ)
2. Content: ใช้ Bullet Points ด้วย -
3. Nested Items: ใช้ Tab + - สำหรับ Sub-items
4. Multiple Sections: เพิ่ม # Updates detailed Heading ได้หลายอัน
5. Emojis: Optional, ใส่ได้เช่น 🎉 📸 🔍

Quick Setup Commands

# สร้าง Directory Structure
mkdir -p your_app/change_log/v1 your_app/change_log/current

# สร้าง Placeholder Files
cat > your_app/change_log/current/readme.md << 'EOF'
Leave change log files in this folder for user release notes.

(this file is just a placeholder, don't delete it)
EOF

touch your_app/change_log/current/changes.md

# สร้าง Version File (ตัวอย่าง 1.5.0)
cat > your_app/change_log/v1/v1_5_0.md << 'EOF'
# Updates detailed

- Your feature description here
- Another update or improvement
EOF

ตัวอย่าง Version File

# Updates detailed

## Document Scanner - OCR Integration 🔍

- **Google Vision OCR Integration**: ทดสอบ OCR บน Scanned Documents
  - Raw Text Extraction View
  - Parsed Data JSON View
  - Copy to Clipboard Button
- **Quick Scan Mode**: Pipeline แบบน้อยที่สุด
  - Detect → Crop → Sharpen เท่านั้น
  - ประมวลผลเร็วขึ้นสำหรับ Simple Documents

## Bug Fixes

- แก้ไข Deskew Threshold สำหรับ Document Straightening
- ปรับปรุง Luminance Merge ด้วย Conservative Clamping

Integration กับ Release Workflow

เมื่อใช้ Automated Release:

1. ก่อน Release: สร้างไฟล์ v{major}_{minor}_{patch}.md
2. Version Bump: รัน Release Script
3. Push: git push --follow-tags
4. Users See: Popup เมื่อ Login หลัง Update

ตัวอย่าง Workflow

# 1. สร้าง Changelog File
cat > your_app/change_log/v1/v1_6_0.md << 'EOF'
# Updates detailed

- เพิ่ม Dark Mode Toggle
- ปรับปรุง Performance การโหลดหน้า
- แก้ไข Bug การ Export PDF
EOF

# 2. Commit
git add .
git commit -m "feat: add dark mode and fix PDF export"

# 3. Bump Version
yarn release:minor  # หรือ npm version minor

# 4. Push
git push --follow-tags

ตรวจสอบ version ใน init.py

# your_app/__init__.py
__version__ = "1.6.0"

สำคัญ: Version ใน __init__.py ต้องตรงกับชื่อไฟล์ Changelog

Troubleshooting

Popup ไม่แสดง

1. ตรวจสอบ File Naming: v1_5_0.md ไม่ใช่ v1.5.0.md
2. ตรวจสอบ __version__: ใน __init__.py ต้องตรงกับ Version File
3. Clear Browser Cache: และ Re-login
4. ตรวจสอบ Directory Structure: ต้องอยู่ใน v{major}/ Folder

Content ไม่ Render

1. Heading ต้องถูก: ใช้ # Updates detailed เป๊ะ
2. Markdown Syntax: ใช้ Bullet Points - ถูกต้อง
3. File Location: อยู่ใน v{major}/ Folder ที่ถูก

ตรวจสอบ Version ปัจจุบัน

# ใน bench console
bench --site your-site.local console

import your_app
print(your_app.__version__)

Multiple Apps

แต่ละ App ใน Bench สามารถมี Change Log ของตัวเองได้:

frappe-bench/
├── apps/
│   ├── frappe/
│   │   └── frappe/change_log/
│   ├── erpnext/
│   │   └── erpnext/change_log/
│   └── your_app/
│       └── your_app/change_log/

เมื่อ User Login หลัง Update, Frappe จะรวม Changelogs จากทุก Apps ที่มี Version Change

Best Practices

1. เขียน Changelog ก่อน Release - เพื่อให้ Users รู้ว่ามีอะไรใหม่
2. ใช้ Format ที่อ่านง่าย - Bullet Points สั้นๆ กระชับ
3. แยก Features และ Bug Fixes - ใช้ Headings แยก Sections
4. ใส่ Emojis - ช่วยให้ Changelog น่าอ่านขึ้น
5. Semantic Versioning - Major.Minor.Patch

สรุป

Frappe's Built-in Change Log Feature ช่วยให้:

• แจ้ง Users เกี่ยวกับ Updates อัตโนมัติ
• ไม่ต้องส่ง Email หรือ Announcement แยก
• UX ดีขึ้น Users รู้ว่า App มีอะไรใหม่

สิ่งที่ต้องทำ:

1. สร้าง change_log/ Directory Structure
2. สร้าง Markdown File ตาม Version
3. ใช้ # Updates detailed Heading
4. Match Version กับ __init__.py

เอกสารอ้างอิง

• Frappe Versioning
• Semantic Versioning