@momo-kits/native-kits 0.156.2 → 0.156.3-beta.1-debug

package/PUBLISH_GUIDE.md

@@ -8,13 +8,13 @@ Tài liệu này hướng dẫn cách sử dụng script publish cho `@momo-kits
 
 Dự án sử dụng **`publish.sh`** - một script thống nhất hỗ trợ 2 modes:
 
-- **`beta`**: Publish phiên bản beta cho testing
+- **`beta`**: Publish phiên bản beta/alpha cho testing
 - **`release`**: Publish phiên bản release chính thức
 
 Script có 3 phases riêng biệt:
 1. **Check Version**: Kiểm tra và chuẩn bị version
-2. **Publish NPM**: Publish lên NPM registry
-3. **Publish Maven**: Publish lên GitLab Maven repository
+2. **Publish Maven**: Publish lên GitLab Maven repository
+3. **Publish NPM**: Publish lên NPM registry
 
 ---
 
@@ -46,11 +46,11 @@ sh publish.sh beta
 # Phase 1: Check version
 sh publish.sh beta check
 
-# Phase 2: Publish NPM
-sh publish.sh beta npm
-
-# Phase 3: Publish Maven
+# Phase 2: Publish Maven
 sh publish.sh beta maven
+
+# Phase 3: Publish NPM
+sh publish.sh beta npm
 ```
 
 #### **Quy Trình Beta Publishing**
@@ -72,92 +72,210 @@ sh publish.sh beta maven
    sh publish.sh beta
    ```
 
-#### **Ví Dụ Beta Publishing**
+---
+
+## 📦 Version Types (Beta Mode)
+
+Beta mode hỗ trợ 2 loại version:
+
+### **1. Specific Version (Tag: alpha)**
+
+**Định nghĩa:** Version có suffix KHÔNG phải "beta"
+
+**Ví dụ:**
+- `0.156.2-test.1`
+- `0.156.2-alpha.1`
+- `0.156.2-rc.1`
+
+**Behavior:**
+- NPM tag: `alpha`
+- Check existence: ❌ **FAIL** nếu version đã tồn tại
+- Không auto-increment
+- Developer phải tự quản lý version
+
+**Use case:** Testing specific features, hotfix testing
+
+### **2. Normal Version (Tag: beta)**
+
+**Định nghĩa:** Version có suffix "beta" HOẶC không có suffix
+
+**Ví dụ:**
+- `0.156.2` (no suffix)
+- `0.156.2-beta.1`
+- `0.156.2-beta.5`
+
+**Behavior:**
+- NPM tag: `beta`
+- Auto-format: `0.156.2` → `0.156.2-beta.1`
+- Auto-increment nếu tồn tại: `.beta.1` → `.beta.2` → `.beta.3`...
+
+**Use case:** Regular beta testing, continuous development
+
+---
+
+## 🔍 Version Detection Examples
+
+### **Example 1: Specific Version**
 
 ```bash
-# 1. Kiểm tra version
-$ cat package.json | grep version
-  "version": "0.156.2"
+# package.json
+{
+  "version": "0.156.2-test.1"
+}
 
-# 2. Test check version
+# Run
 $ sh publish.sh beta check
-📦 Version from package.json: 0.156.2
-🔎 Checking if version 0.156.2 already exists on npm...
-✅ Version 0.156.2 does not exist on npm. Safe to publish.
-✅ PHASE 1 COMPLETED
-
-# 3. Publish
-$ sh publish.sh beta
-🚀 PUBLISH SCRIPT - MODE: BETA
-Running ALL PHASES
-[... Phase 1: Check version ...]
-[... Phase 2: Publish NPM ...]
-   🐛 Debug version: 0.156.2-debug (with compose) - Published first
-   📦 Normal version: 0.156.2 (without compose) - Published second
-   🏷️  NPM Tag: beta
-[... Phase 3: Publish Maven ...]
-🎉 ALL PHASES COMPLETED SUCCESSFULLY!
+
+# Output
+🏷️  Detected: SPECIFIC version (tag: alpha)
+🔎 Checking if specific version 0.156.2-test.1 exists on npm...
+✅ Specific version 0.156.2-test.1 does not exist on npm. Safe to publish.
+✅ NPM tag: alpha
 ```
 
-#### **⚠️ Nếu Version Đã Tồn Tại**
+**Kết quả trên NPM:**
+- `@momo-kits/native-kits@0.156.2-test.1` (tag: **alpha**)
+- `@momo-kits/native-kits@0.156.2-test.1-debug` (tag: **alpha**)
+
+### **Example 2: Normal Version (No Suffix)**
 
 ```bash
+# package.json
+{
+  "version": "0.156.2"
+}
+
+# Run
 $ sh publish.sh beta check
-❌ ERROR: Version 0.156.1 already exists on npm!
 
-Please update the version in package.json before publishing.
+# Output
+🏷️  Detected: NORMAL version (tag: beta)
+🔄 Adding beta suffix: 0.156.2 → 0.156.2-beta.1
+🔎 Checking version 0.156.2-beta.1 on npm...
+✅ Version 0.156.2-beta.1 does not exist on npm. Using this version.
+✅ NPM tag: beta
 ```
 
-**Giải pháp:** Tăng version trong `package.json`:
+**Kết quả trên NPM:**
+- `@momo-kits/native-kits@0.156.2-beta.1` (tag: **beta**)
+- `@momo-kits/native-kits@0.156.2-beta.1-debug` (tag: **beta**)
+
+### **Example 3: Normal Version (With Beta Suffix)**
+
 ```bash
-# Mở và edit file
-vim package.json
-# hoặc
-code package.json
+# package.json
+{
+  "version": "0.156.2-beta.1"
+}
+
+# Giả sử npm đã có: beta.1, beta.2
 
-# Thay đổi: "version": "0.156.1" → "0.156.2"
+# Run
+$ sh publish.sh beta check
+
+# Output
+🏷️  Detected: NORMAL version (tag: beta)
+🔎 Checking version 0.156.2-beta.1 on npm...
+⚠️  Version 0.156.2-beta.1 already exists on npm. Auto-incrementing...
+   Version incremented: 0.156.2-beta.1 → 0.156.2-beta.2
+⚠️  Version 0.156.2-beta.2 already exists on npm. Auto-incrementing...
+   Version incremented: 0.156.2-beta.2 → 0.156.2-beta.3
+✅ Version 0.156.2-beta.3 does not exist on npm. Using this version.
+✅ NPM tag: beta
 ```
 
-### 🟢 Publish Release Từ Local
+**Kết quả trên NPM:**
+- `@momo-kits/native-kits@0.156.2-beta.3` (tag: **beta**)
+- `@momo-kits/native-kits@0.156.2-beta.3-debug` (tag: **beta**)
 
-#### **Cách 1: Publish tất cả phases (Khuyến nghị)**
+### **Example 4: Specific Version Already Exists (FAIL)**
 
 ```bash
-sh publish.sh release
+# package.json
+{
+  "version": "0.156.2-test.1"
+}
+
+# Version đã tồn tại trên npm
+
+# Run
+$ sh publish.sh beta check
+
+# Output
+🏷️  Detected: SPECIFIC version (tag: alpha)
+🔎 Checking if specific version 0.156.2-test.1 exists on npm...
+
+❌ ERROR: Specific version 0.156.2-test.1 already exists on npm!
+
+Please update the version in package.json before publishing.
+# Exit code: 1
 ```
 
-#### **Cách 2: Chạy từng phase riêng**
+---
 
-```bash
-# Phase 1: Check version
-sh publish.sh release check
+## 🟢 Publish Release Từ Local
 
-# Phase 2: Publish NPM
-sh publish.sh release npm
+### **Đặc Điểm Quan Trọng**
 
-# Phase 3: Publish Maven
+⚠️ **Release mode KHÔNG đọc version từ `package.json`**
+
+✅ **Release mode đọc version từ `npm@latest`**
+
+### **Cách Publish**
+
+```bash
+# Publish tất cả phases
+sh publish.sh release
+
+# Hoặc từng phase
+sh publish.sh release check
 sh publish.sh release maven
+sh publish.sh release npm
 ```
 
-#### **Quy Trình Release Publishing**
+### **Quy Trình Release Publishing**
 
-1. **Version trong `package.json` có thể là bất kỳ format nào:**
-   ```json
-   {
-     "version": "0.156.1-test.5"
-   }
+1. **Script đọc version từ npm@latest:**
+   ```bash
+   npm view @momo-kits/native-kits@latest version
+   # Output: 0.156.2
    ```
 
-2. **Chạy publish:**
-   ```bash
-   sh publish.sh release
+2. **Auto-increment patch version:**
+   ```
+   0.156.2 → 0.156.3
    ```
 
-3. **Script sẽ tự động:**
-   - Convert sang format beta: `0.156.1-test.5` → `0.156.1-beta.1`
-   - Check version trên npm
-   - Auto-increment nếu đã tồn tại: `0.156.1-beta.1` → `0.156.1-beta.2`
-   - Publish với tag `latest`
+3. **Check existence và tiếp tục increment nếu cần:**
+   ```
+   0.156.3 exists? → 0.156.4
+   0.156.4 exists? → 0.156.5
+   ...
+   ```
+
+4. **Update `package.json` với version mới**
+
+5. **Publish với tag `latest`**
+
+### **Example: Release Publishing**
+
+```bash
+$ sh publish.sh release check
+
+# Output
+🔍 Reading latest version from npm@latest (NOT from package.json)...
+📦 Current @latest version on npm: 0.156.2
+🔼 Auto-incremented version: 0.156.2 → 0.156.3
+🔎 Checking if version 0.156.3 exists on npm...
+✅ Version 0.156.3 does not exist on npm. Using this version.
+📝 Updated package.json: 0.156.2-beta.5 → 0.156.3
+✅ Using version: 0.156.3
+✅ NPM tag: latest
+```
+
+**Kết quả trên NPM:**
+- `@momo-kits/native-kits@0.156.3` (tag: **latest**)
+- `@momo-kits/native-kits@0.156.3-debug` (tag: **latest**)
 
 ---
 
@@ -165,18 +283,19 @@ sh publish.sh release maven
 
 ### 🔵 Beta Publishing (GitLab CI)
 
-**Trigger:** Commit message chứa `[ci build]`
+**Trigger:** Commit message chứa `[ci build]` (KHÔNG trên nhánh `main`)
 
 ```bash
+git checkout develop
 git add .
 git commit -m "feat: add new feature [ci build]"
 git push
 ```
 
 **Pipeline sẽ chạy 3 stages:**
-1. `beta_check_version`
-2. `beta_publish_npm`
-3. `beta_publish_maven`
+1. `beta_check_version` (Phase 1)
+2. `beta_publish_maven` (Phase 2)
+3. `beta_publish_npm` (Phase 3)
 
 ### 🟢 Release Publishing (GitLab CI)
 
@@ -189,9 +308,9 @@ git push origin main
 ```
 
 **Pipeline sẽ chạy 3 stages:**
-1. `release_check_version`
-2. `release_publish_npm`
-3. `release_publish_maven`
+1. `release_check_version` (Phase 1)
+2. `release_publish_maven` (Phase 2)
+3. `release_publish_npm` (Phase 3)
 
 ---
 
@@ -200,123 +319,100 @@ git push origin main
 | Tiêu chí | Beta Mode | Release Mode |
 |----------|-----------|--------------|
 | **Script** | `sh publish.sh beta` | `sh publish.sh release` |
-| **Trigger CI** | Commit có `[ci build]` | Push vào `main` |
-| **Version Check** | **Fail** nếu tồn tại | **Auto-increment** |
-| **Format Version** | Giữ nguyên | Convert → `-beta.*` |
-| **NPM Tag** | `beta` | `latest` |
-| **Publish Order** | Debug first → Normal | Debug first → Normal |
+| **Trigger CI** | Commit có `[ci build]` (không trên main) | Push vào `main` |
+| **Read Version** | Từ `package.json` | Từ `npm@latest` |
+| **Version Types** | Specific (alpha) / Normal (beta) | N/A |
+| **NPM Tag** | `alpha` hoặc `beta` | `latest` |
+| **If Exists** | Specific: FAIL / Normal: Auto-increment | Auto-increment |
+| **Phase Order** | Check → Maven → NPM | Check → Maven → NPM |
 
 ---
 
-## 🔍 Chi Tiết Các Phases
-
-### **Phase 1: Check Version**
+## 🔧 NPM Tags Explained
 
-**Beta Mode:**
-- Đọc version từ `package.json`
-- Check version trên npm
-- ❌ **FAIL** nếu version đã tồn tại
-- Update `gradle.properties`
+### **Tag: alpha**
 
-**Release Mode:**
-- Đọc version từ `package.json`
-- Convert sang format `-beta.*` nếu cần
-- Check version trên npm
-- ✅ **Auto-increment** nếu đã tồn tại
-- Update `gradle.properties`
+**Khi nào:** Beta mode + Specific version
 
-### **Phase 2: Publish NPM**
-
-**Thứ tự publish (cả Beta và Release):**
+**Cài đặt:**
+```bash
+npm install @momo-kits/native-kits@alpha
+npm install @momo-kits/native-kits@0.156.2-test.1
+```
 
-1. **Debug version** (với compose) - Published FIRST
-   - Version: `X.Y.Z-debug`
-   - Bao gồm thư mục `compose/`
-   - Dành cho development/testing
+**Use case:** Testing specific features, experimental builds
 
-2. **Normal version** (không compose) - Published SECOND
-   - Version: `X.Y.Z`
-   - Không bao gồm `compose/`
-   - Dành cho React Native apps
+### **Tag: beta**
 
-### **Phase 3: Publish Maven**
+**Khi nào:** Beta mode + Normal version
 
-- Publish Kotlin Multiplatform artifacts
-- Lên GitLab Packages Repository
-- Dành cho `compose` module
+**Cài đặt:**
+```bash
+npm install @momo-kits/native-kits@beta
+npm install @momo-kits/native-kits@0.156.2-beta.1
+```
 
----
+**Use case:** Regular beta testing, pre-release versions
 
-## 📝 Ví Dụ Chi Tiết
+### **Tag: latest**
 
-### **Ví dụ 1: Beta - Version chưa tồn tại**
+**Khi nào:** Release mode
 
+**Cài đặt:**
 ```bash
-$ sh publish.sh beta
+npm install @momo-kits/native-kits@latest
+npm install @momo-kits/native-kits
+npm install @momo-kits/native-kits@0.156.3
+```
 
-📦 Version from package.json: 0.156.2
-🔎 Checking if version 0.156.2 already exists on npm...
-✅ Version 0.156.2 does not exist on npm. Safe to publish.
+**Use case:** Production releases, stable versions
 
-# Phase 2
-🐛 Debug version: 0.156.2-debug (with compose) - Published first
-📦 Normal version: 0.156.2 (without compose) - Published second
-🏷️  NPM Tag: beta
-```
+---
 
-**Kết quả trên NPM:**
-- `@momo-kits/native-kits@0.156.2-debug` (tag: beta)
-- `@momo-kits/native-kits@0.156.2` (tag: beta)
+## 🔍 Chi Tiết Các Phases
 
-### **Ví dụ 2: Beta - Version đã tồn tại (FAIL)**
+### **Phase 1: Check Version**
 
-```bash
-$ sh publish.sh beta check
+**Beta Mode:**
+1. Đọc version từ `package.json`
+2. Phát hiện version type (specific vs normal)
+3. Set NPM tag (alpha vs beta)
+4. Format version:
+   - Specific: Check existence, fail if exists
+   - Normal: Add beta suffix, auto-increment if exists
+5. Update `gradle.properties`
 
-📦 Version from package.json: 0.156.1
-🔎 Checking if version 0.156.1 already exists on npm...
+**Release Mode:**
+1. Đọc version từ `npm@latest` (KHÔNG từ package.json)
+2. Increment patch version
+3. Check existence, auto-increment if exists
+4. Update `package.json` và `gradle.properties`
+5. Set NPM tag = `latest`
 
-❌ ERROR: Version 0.156.1 already exists on npm!
+### **Phase 2: Publish Maven**
 
-Please update the version in package.json before publishing.
-# Exit code: 1
-```
+**Thứ tự:** Chạy SAU phase 1, TRƯỚC phase 3
 
-### **Ví dụ 3: Release - Auto-convert và increment**
+**Hành động:**
+- Publish Kotlin Multiplatform artifacts
+- Lên GitLab Packages Repository
+- Dành cho `compose` module
 
-```bash
-$ sh publish.sh release
-
-📦 Version from package.json: 0.156.1-test.5
-🔄 Converting to beta format: 0.156.1-test.5 → 0.156.1-beta.1
-✅ Version updated to beta format: 0.156.1-beta.1
-🔎 Checking if version 0.156.1-beta.1 already exists on npm...
-⚠️  Version 0.156.1-beta.1 already exists on npm. Auto-incrementing...
-   Version incremented: 0.156.1-beta.1 → 0.156.1-beta.2
-🔄 Checking version 0.156.1-beta.2 on npm...
-✅ Version 0.156.1-beta.2 does not exist on npm. Using this version.
-```
+### **Phase 3: Publish NPM**
 
-**Kết quả trên NPM:**
-- `@momo-kits/native-kits@0.156.1-beta.2-debug` (tag: latest)
-- `@momo-kits/native-kits@0.156.1-beta.2` (tag: latest)
+**Thứ tự:** Chạy SAU phase 2 (Maven)
 
-### **Ví dụ 4: Release - Multiple increments**
+**Publish 2 versions theo thứ tự:**
 
-```bash
-$ sh publish.sh release
-
-📦 Version from package.json: 0.156.1-beta.5
-
-# Giả sử NPM đã có: beta.5, beta.6, beta.7
-⚠️  Version 0.156.1-beta.5 already exists on npm...
-   Version incremented: 0.156.1-beta.5 → 0.156.1-beta.6
-⚠️  Version 0.156.1-beta.6 already exists on npm...
-   Version incremented: 0.156.1-beta.6 → 0.156.1-beta.7
-⚠️  Version 0.156.1-beta.7 already exists on npm...
-   Version incremented: 0.156.1-beta.7 → 0.156.1-beta.8
-✅ Version 0.156.1-beta.8 does not exist on npm. Using this version.
-```
+1. **Debug version** (với compose) - FIRST
+   - Version: `X.Y.Z-debug`
+   - Bao gồm thư mục `compose/`
+   - Tag: `alpha` / `beta` / `latest`
+
+2. **Normal version** (không compose) - SECOND
+   - Version: `X.Y.Z`
+   - Không bao gồm `compose/`
+   - Tag: `alpha` / `beta` / `latest`
 
 ---
 
@@ -328,20 +424,22 @@ $ sh publish.sh release
 ┌──────────────────────────────────────────────────┐
 │ 1. Develop Feature                               │
 │    - Code changes                                │
-│    - Update version in package.json              │
+│    - Update version in package.json (beta only)  │
 └─────────────────┬────────────────────────────────┘
                   ↓
 ┌──────────────────────────────────────────────────┐
 │ 2. Beta Testing                                  │
 │    Local: sh publish.sh beta                     │
 │    CI: git commit -m "feat: xxx [ci build]"      │
+│    Tag: alpha (specific) or beta (normal)        │
 └─────────────────┬────────────────────────────────┘
                   ↓
 ┌──────────────────────────────────────────────────┐
 │ 3. Team Testing                                  │
 │    npm install @momo-kits/native-kits@beta       │
+│    npm install @momo-kits/native-kits@alpha      │
 └─────────────────┬────────────────────────────────┘
-                  ↓
+                  │
            ┌──────┴──────┐
            │  Approved?   │
            └──────┬───────┘
@@ -351,6 +449,7 @@ $ sh publish.sh release
 │ 4. Release Production                            │
 │    Local: sh publish.sh release                  │
 │    CI: merge to main                             │
+│    Reads from npm@latest, auto-increment         │
 └─────────────────┬────────────────────────────────┘
                   ↓
 ┌──────────────────────────────────────────────────┐
@@ -363,31 +462,38 @@ $ sh publish.sh release
 
 ## ⚠️ Lưu Ý Quan Trọng
 
-### 1. Publishing Order
+### 1. Version Management
+
+**Beta Mode:**
+- Specific version: Phải unique, fail nếu tồn tại
+- Normal version: Auto-increment, không cần lo
+- Version trong `package.json` được sử dụng
 
-**NPM publish theo thứ tự:**
-1. ✅ Debug version (`X.Y.Z-debug`) - FIRST
-2. ✅ Normal version (`X.Y.Z`) - SECOND
+**Release Mode:**
+- ⚠️ **KHÔNG đọc từ `package.json`**
+- ✅ **Đọc từ `npm@latest`**
+- Auto-increment patch version
+- `package.json` được UPDATE với version mới
 
-**Lý do:** Đảm bảo debug version luôn available trước
+### 2. NPM Tags
 
-### 2. Version Format
+**Cài đặt theo tag:**
+```bash
+npm install @momo-kits/native-kits@alpha    # Specific versions
+npm install @momo-kits/native-kits@beta     # Normal beta versions
+npm install @momo-kits/native-kits@latest   # Release versions
+```
 
-**Beta Mode:**
-- Giữ nguyên format trong `package.json`
-- Fail nếu đã tồn tại trên npm
-- ⚠️ Developer phải tự quản lý version
+### 3. Phase Execution Order
 
-**Release Mode:**
-- Auto-convert sang `-beta.*` format:
-  - `0.156.1-test.5` → `0.156.1-beta.1`
-  - `0.156.1-alpha.2` → `0.156.1-beta.1`
-  - `0.156.1-rc.3` → `0.156.1-beta.1`
-- Auto-increment nếu tồn tại:
-  - Beta: `-beta.5` → `-beta.6`
-  - Regular: `1.0.0` → `1.0.1`
+**Cả Beta và Release:**
+1. Check Version
+2. ✅ **Publish Maven** (FIRST)
+3. ✅ **Publish NPM** (SECOND)
 
-### 3. File Modifications
+**Lý do:** Maven artifacts cần được publish trước để NPM debug version có thể reference
+
+### 4. File Modifications
 
 Script tạm thời modify các file (restore sau publish):
 - `package.json` (version)
@@ -395,93 +501,74 @@ Script tạm thời modify các file (restore sau publish):
 - `.npmignore` (cho debug version)
 - `compose/build.gradle.kts` (cho debug version)
 
-### 4. NPM Permissions
-
-```bash
-# Check account hiện tại
-npm whoami
-
-# Login nếu cần
-npm login
-
-# Verify permissions
-npm access ls-packages @momo-kits
-```
-
 ---
 
 ## 🐛 Troubleshooting
 
-### Lỗi: "Could not read version from package.json"
-
-**Nguyên nhân:** File `package.json` không hợp lệ
-
-**Giải pháp:**
-```bash
-# Kiểm tra syntax
-cat package.json | jq .
-
-# Kiểm tra version field
-cat package.json | grep version
-```
+### Lỗi: "Specific version already exists on npm"
 
-### Lỗi: "Version already exists on npm" (Beta)
-
-**Nguyên nhân:** Version đã được publish
+**Nguyên nhân:** Specific version đã được publish
 
 **Giải pháp:**
 ```bash
 # Option 1: Tăng version thủ công
 vim package.json
-# "version": "0.156.1" → "0.156.2"
+# "version": "0.156.2-test.1" → "0.156.2-test.2"
 
-# Option 2: Sử dụng release mode (auto-increment)
-sh publish.sh release
+# Option 2: Chuyển sang normal version
+vim package.json
+# "version": "0.156.2-test.1" → "0.156.2"
+# Script sẽ auto-format thành 0.156.2-beta.1
 ```
 
-### Lỗi: "Permission denied"
+### Lỗi: "Could not read version from npm@latest"
 
-**Nguyên nhân:** Không có quyền publish package
+**Nguyên nhân:** Package chưa tồn tại trên npm hoặc chưa có version @latest
 
 **Giải pháp:**
 ```bash
-# 1. Kiểm tra account
-npm whoami
-
-# 2. Login với account có quyền
-npm login
+# Kiểm tra package trên npm
+npm view @momo-kits/native-kits
 
-# 3. Liên hệ admin để cấp quyền
+# Nếu chưa có, publish beta trước
+sh publish.sh beta
 ```
 
-### Script không chạy trên GitLab CI
+### Beta không trigger trên GitLab CI
 
-**Beta không trigger:**
-- ✅ Check commit message có `[ci build]`
-- ✅ Check branch không match `engine/w*`
+**Kiểm tra:**
+- ✅ Commit message có `[ci build]`
+- ✅ Branch KHÔNG phải `main`
+- ✅ Branch KHÔNG match `engine/w*`
 
-**Release không trigger:**
-- ✅ Check đang push vào `main` branch
-- ✅ Check GitLab CI settings
+### Release không trigger trên GitLab CI
+
+**Kiểm tra:**
+- ✅ Đang push vào `main` branch
+- ✅ GitLab CI settings enabled
 
 ---
 
 ## 📦 Sử Dụng Packages
 
-### Cài Đặt Beta Version
+### Cài Đặt Beta/Alpha Versions
 
 ```bash
-# Latest beta
+# Latest alpha (specific versions)
+npm install @momo-kits/native-kits@alpha
+
+# Latest beta (normal versions)
 npm install @momo-kits/native-kits@beta
 
-# Specific beta version
-npm install @momo-kits/native-kits@0.156.2
+# Specific version
+npm install @momo-kits/native-kits@0.156.2-beta.1
+npm install @momo-kits/native-kits@0.156.2-test.1
 
 # Debug version (with compose)
-npm install @momo-kits/native-kits@0.156.2-debug
+npm install @momo-kits/native-kits@0.156.2-beta.1-debug
 ```
 
-### Cài Đặt Release Version
+### Cài Đặt Release Versions
 
 ```bash
 # Latest release
@@ -490,28 +577,41 @@ npm install @momo-kits/native-kits@latest
 npm install @momo-kits/native-kits
 
 # Specific release version
-npm install @momo-kits/native-kits@0.156.1-beta.2
+npm install @momo-kits/native-kits@0.156.3
 ```
 
 ---
 
 ## 🎓 Best Practices
 
-1. **Development:**
-   - Luôn test với beta trước khi release
-   - Dùng version có ý nghĩa (semantic versioning)
+### 1. Beta Testing
+
+**Specific versions (alpha tag):**
+- Dùng cho testing features cụ thể
+- Phải unique, không duplicate
+- Ví dụ: `0.156.2-hotfix.1`, `0.156.2-experiment.1`
 
-2. **Beta Testing:**
-   - Update version mỗi lần publish beta
-   - Kiểm tra version trước khi commit
+**Normal versions (beta tag):**
+- Dùng cho continuous development
+- Auto-increment, dễ quản lý
+- Ví dụ: `0.156.2`, `0.156.2-beta.1`
 
-3. **Release:**
-   - Chỉ release từ nhánh `main`
-   - Đảm bảo tất cả tests pass
+### 2. Release
 
-4. **Version Management:**
-   - Beta: Tự quản lý version, tăng thủ công
-   - Release: Để script auto-increment
+- Luôn merge vào `main` để trigger release
+- Không cần lo version trong `package.json`
+- Script tự động đọc từ npm@latest và increment
+
+### 3. Version Naming
+
+**Good:**
+- `0.156.2-test.1` (specific, clear purpose)
+- `0.156.2-beta.1` (normal, standard format)
+- `0.156.2` (normal, will auto-format)
+
+**Avoid:**
+- `0.156.2-beta-test.1` (confusing)
+- `0.156.2-v1` (unclear)
 
 ---
 
@@ -524,21 +624,52 @@ Nếu có vấn đề, liên hệ team hoặc tạo issue trên GitLab.
 ## 🔗 Quick Reference
 
 ```bash
-# Beta - Local
-sh publish.sh beta                    # All phases
-sh publish.sh beta check              # Check only
-sh publish.sh beta npm                # NPM only
-sh publish.sh beta maven              # Maven only
-
-# Release - Local
-sh publish.sh release                 # All phases
-sh publish.sh release check           # Check only
-sh publish.sh release npm             # NPM only
-sh publish.sh release maven           # Maven only
+# Beta - Local (Specific version → alpha tag)
+# package.json: "version": "0.156.2-test.1"
+sh publish.sh beta
+
+# Beta - Local (Normal version → beta tag)
+# package.json: "version": "0.156.2"
+sh publish.sh beta
+
+# Release - Local (reads from npm@latest)
+sh publish.sh release
+
+# Individual phases
+sh publish.sh beta check              # Phase 1
+sh publish.sh beta maven              # Phase 2
+sh publish.sh beta npm                # Phase 3
 
 # Beta - CI
-git commit -m "feat: xxx [ci build]"  # Trigger beta
+git commit -m "feat: xxx [ci build]"  # Trigger beta (not on main)
 
 # Release - CI
 git push origin main                  # Trigger release
 ```
+
+---
+
+## 📋 Version Type Decision Tree
+
+```
+Start: Publish Beta
+    ↓
+Check version in package.json
+    ↓
+Has suffix? (contains "-")
+    ├─ No → Normal Version
+    │         ├─ Auto-add: 0.156.2 → 0.156.2-beta.1
+    │         ├─ Tag: beta
+    │         └─ Auto-increment if exists
+    │
+    └─ Yes → Check suffix type
+              ├─ Contains "beta" → Normal Version
+              │                     ├─ Keep format: 0.156.2-beta.1
+              │                     ├─ Tag: beta
+              │                     └─ Auto-increment if exists
+              │
+              └─ Other suffix → Specific Version
+                                ├─ Keep format: 0.156.2-test.1
+                                ├─ Tag: alpha
+                                └─ FAIL if exists
+```