@momo-kits/native-kits 0.155.2-test.1 → 0.156.1-beta.12-debug

package/PUBLISH_GUIDE.md

@@ -0,0 +1,544 @@
+# Hướng Dẫn Publish NPM Package
+
+Tài liệu này hướng dẫn cách sử dụng script publish cho `@momo-kits/native-kits`.
+
+---
+
+## 📋 Tổng Quan
+
+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
+- **`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
+
+---
+
+## 🚀 Publish Từ Local
+
+### Yêu Cầu Trước Khi Publish
+
+1. **Login NPM:**
+   ```bash
+   npm login
+   ```
+
+2. **Kiểm tra version hiện tại:**
+   ```bash
+   cat package.json | grep version
+   ```
+
+### 🔵 Publish Beta Từ Local
+
+#### **Cách 1: Publish tất cả phases (Khuyến nghị)**
+
+```bash
+sh publish.sh beta
+```
+
+#### **Cách 2: Chạy từng phase riêng**
+
+```bash
+# Phase 1: Check version
+sh publish.sh beta check
+
+# Phase 2: Publish NPM
+sh publish.sh beta npm
+
+# Phase 3: Publish Maven
+sh publish.sh beta maven
+```
+
+#### **Quy Trình Beta Publishing**
+
+1. **Update version trong `package.json`:**
+   ```json
+   {
+     "version": "0.156.2"
+   }
+   ```
+
+2. **Chạy check version trước (optional nhưng khuyến nghị):**
+   ```bash
+   sh publish.sh beta check
+   ```
+
+3. **Nếu check thành công, publish:**
+   ```bash
+   sh publish.sh beta
+   ```
+
+#### **Ví Dụ Beta Publishing**
+
+```bash
+# 1. Kiểm tra version
+$ cat package.json | grep version
+  "version": "0.156.2"
+
+# 2. Test check version
+$ 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!
+```
+
+#### **⚠️ Nếu Version Đã Tồn Tại**
+
+```bash
+$ sh publish.sh beta check
+❌ ERROR: Version 0.156.1 already exists on npm!
+
+Please update the version in package.json before publishing.
+```
+
+**Giải pháp:** Tăng version trong `package.json`:
+```bash
+# Mở và edit file
+vim package.json
+# hoặc
+code package.json
+
+# Thay đổi: "version": "0.156.1" → "0.156.2"
+```
+
+### 🟢 Publish Release Từ Local
+
+#### **Cách 1: Publish tất cả phases (Khuyến nghị)**
+
+```bash
+sh publish.sh release
+```
+
+#### **Cách 2: Chạy từng phase riêng**
+
+```bash
+# Phase 1: Check version
+sh publish.sh release check
+
+# Phase 2: Publish NPM
+sh publish.sh release npm
+
+# Phase 3: Publish Maven
+sh publish.sh release maven
+```
+
+#### **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"
+   }
+   ```
+
+2. **Chạy publish:**
+   ```bash
+   sh publish.sh release
+   ```
+
+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`
+
+---
+
+## 🤖 Publish Tự Động Trên GitLab CI
+
+### 🔵 Beta Publishing (GitLab CI)
+
+**Trigger:** Commit message chứa `[ci build]`
+
+```bash
+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`
+
+### 🟢 Release Publishing (GitLab CI)
+
+**Trigger:** Push vào nhánh `main`
+
+```bash
+git checkout main
+git merge develop
+git push origin main
+```
+
+**Pipeline sẽ chạy 3 stages:**
+1. `release_check_version`
+2. `release_publish_npm`
+3. `release_publish_maven`
+
+---
+
+## 📊 So Sánh Beta vs Release
+
+| 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 |
+
+---
+
+## 🔍 Chi Tiết Các Phases
+
+### **Phase 1: Check Version**
+
+**Beta Mode:**
+- Đọc version từ `package.json`
+- Check version trên npm
+- ❌ **FAIL** nếu version đã tồn tại
+- Update `gradle.properties`
+
+**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`
+
+### **Phase 2: Publish NPM**
+
+**Thứ tự publish (cả Beta và Release):**
+
+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
+
+2. **Normal version** (không compose) - Published SECOND
+   - Version: `X.Y.Z`
+   - Không bao gồm `compose/`
+   - Dành cho React Native apps
+
+### **Phase 3: Publish Maven**
+
+- Publish Kotlin Multiplatform artifacts
+- Lên GitLab Packages Repository
+- Dành cho `compose` module
+
+---
+
+## 📝 Ví Dụ Chi Tiết
+
+### **Ví dụ 1: Beta - Version chưa tồn tại**
+
+```bash
+$ sh publish.sh beta
+
+📦 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 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)
+
+### **Ví dụ 2: Beta - Version đã tồn tại (FAIL)**
+
+```bash
+$ sh publish.sh beta check
+
+📦 Version from package.json: 0.156.1
+🔎 Checking if version 0.156.1 already exists on npm...
+
+❌ ERROR: Version 0.156.1 already exists on npm!
+
+Please update the version in package.json before publishing.
+# Exit code: 1
+```
+
+### **Ví dụ 3: Release - Auto-convert và increment**
+
+```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.
+```
+
+**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)
+
+### **Ví dụ 4: Release - Multiple increments**
+
+```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.
+```
+
+---
+
+## 🎯 Workflow Khuyến Nghị
+
+### Development Flow
+
+```
+┌──────────────────────────────────────────────────┐
+│ 1. Develop Feature                               │
+│    - Code changes                                │
+│    - Update version in package.json              │
+└─────────────────┬────────────────────────────────┘
+                  ↓
+┌──────────────────────────────────────────────────┐
+│ 2. Beta Testing                                  │
+│    Local: sh publish.sh beta                     │
+│    CI: git commit -m "feat: xxx [ci build]"      │
+└─────────────────┬────────────────────────────────┘
+                  ↓
+┌──────────────────────────────────────────────────┐
+│ 3. Team Testing                                  │
+│    npm install @momo-kits/native-kits@beta       │
+└─────────────────┬────────────────────────────────┘
+                  ↓
+           ┌──────┴──────┐
+           │  Approved?   │
+           └──────┬───────┘
+                  │ Yes
+                  ↓
+┌──────────────────────────────────────────────────┐
+│ 4. Release Production                            │
+│    Local: sh publish.sh release                  │
+│    CI: merge to main                             │
+└─────────────────┬────────────────────────────────┘
+                  ↓
+┌──────────────────────────────────────────────────┐
+│ 5. Production                                    │
+│    npm install @momo-kits/native-kits@latest     │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## ⚠️ Lưu Ý Quan Trọng
+
+### 1. Publishing Order
+
+**NPM publish theo thứ tự:**
+1. ✅ Debug version (`X.Y.Z-debug`) - FIRST
+2. ✅ Normal version (`X.Y.Z`) - SECOND
+
+**Lý do:** Đảm bảo debug version luôn available trước
+
+### 2. Version Format
+
+**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
+
+**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`
+
+### 3. File Modifications
+
+Script tạm thời modify các file (restore sau publish):
+- `package.json` (version)
+- `gradle.properties` (version)
+- `.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: "Version already exists on npm" (Beta)
+
+**Nguyên nhân:** 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"
+
+# Option 2: Sử dụng release mode (auto-increment)
+sh publish.sh release
+```
+
+### Lỗi: "Permission denied"
+
+**Nguyên nhân:** Không có quyền publish package
+
+**Giải pháp:**
+```bash
+# 1. Kiểm tra account
+npm whoami
+
+# 2. Login với account có quyền
+npm login
+
+# 3. Liên hệ admin để cấp quyền
+```
+
+### Script không chạy trên GitLab CI
+
+**Beta không trigger:**
+- ✅ Check commit message có `[ci build]`
+- ✅ Check branch không match `engine/w*`
+
+**Release không trigger:**
+- ✅ Check đang push vào `main` branch
+- ✅ Check GitLab CI settings
+
+---
+
+## 📦 Sử Dụng Packages
+
+### Cài Đặt Beta Version
+
+```bash
+# Latest beta
+npm install @momo-kits/native-kits@beta
+
+# Specific beta version
+npm install @momo-kits/native-kits@0.156.2
+
+# Debug version (with compose)
+npm install @momo-kits/native-kits@0.156.2-debug
+```
+
+### Cài Đặt Release Version
+
+```bash
+# Latest release
+npm install @momo-kits/native-kits@latest
+# hoặc
+npm install @momo-kits/native-kits
+
+# Specific release version
+npm install @momo-kits/native-kits@0.156.1-beta.2
+```
+
+---
+
+## 🎓 Best Practices
+
+1. **Development:**
+   - Luôn test với beta trước khi release
+   - Dùng version có ý nghĩa (semantic versioning)
+
+2. **Beta Testing:**
+   - Update version mỗi lần publish beta
+   - Kiểm tra version trước khi commit
+
+3. **Release:**
+   - Chỉ release từ nhánh `main`
+   - Đảm bảo tất cả tests pass
+
+4. **Version Management:**
+   - Beta: Tự quản lý version, tăng thủ công
+   - Release: Để script auto-increment
+
+---
+
+## 📞 Support
+
+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 - CI
+git commit -m "feat: xxx [ci build]"  # Trigger beta
+
+# Release - CI
+git push origin main                  # Trigger release
+```

package/build.gradle.kts

@@ -0,0 +1,11 @@
+plugins {
+    // this is necessary to avoid the plugins to be loaded multiple times
+    // in each subproject's classloader
+    alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.android.library) apply false
+    alias(libs.plugins.compose) apply false
+    alias(libs.plugins.kotlin.compose.compiler) apply false
+    alias(libs.plugins.jetbrains.kotlin.multiplatform) apply false
+    alias(libs.plugins.jetbrains.kotlin.serialization) apply false
+    alias(libs.plugins.vanniktech.mavenPublish) apply false
+}