# 📦 NPM Release Workflow — Task-Based Development → Develop → Master

This guide describes the complete workflow for publishing **task-based development builds** and **stable releases** using GitHub Actions, Git tags, and npm versioning.

Incorrect versioning or incorrect tags will break the publish pipeline — follow the process exactly.

---

# 📘 Table of Contents
- Overview
- Branch Strategy
- Task Branch Workflow
- Versioning Rules
- Development Release Workflow (`develop`)
- Promotion Workflow (Dev → Master)
- Publishing via GitHub Release UI
- How GitHub Action Detects Release Type
- Summary Table
- Common Mistakes & Fixes

---

# 🧩 Overview

We maintain two release channels:

| Channel              | Branch   | Tag              | Purpose               |
|---------------------|----------|------------------|-----------------------|
| Stable (`latest`)   | master   | `vX.Y.Z`         | Production release    |
| Development (`dev`) | develop  | `vX.Y.Z-dev.N`   | QA/internal testing   |

Releases are triggered using Git tags:

```
npm version
```

---

# 🌿 Branch Strategy

## `master`
- Production-ready code  
- Publishes **stable** builds  
- Versions never include a `dev` suffix  

## `develop`
- Used for QA/internal testing  
- Publishes **development** builds  
- Versions always include `-dev.N`  

## Task Branches
- Create from `master`  
- Naming: `task/<JIRA-ID>-<description>`  
- After completing work, merge into `develop`  

---

# 🏗️ Task Branch Workflow

### 1. Create a task branch
```bash
git checkout master
git pull origin master
git checkout -b task/<JIRA-ID>-<description>
```

### 2. Work on the task
```bash
git add .
git commit -m "TASK-123: Implement XYZ"
```

### 3. Merge into develop
```bash
git checkout develop
git pull origin develop
git merge task/<JIRA-ID>-<description>
```

---

# 🔧 Versioning Rules

## Development Versions
```
X.Y.Z-dev.N
```
Example:
```
2.4.30-dev.0
```

## Stable Versions
```
X.Y.Z
```

## Rules
- Each version must be unique  
- Dev versions do **not** convert into stable versions  
- Git tag must exactly match `package.json` version  

---

# 🟦 Development Release Workflow (`develop`)

### 1. Switch to develop
```bash
git checkout develop
git pull origin develop
```

### 2. Create a new development version
```bash
npm version prerelease --preid=dev
```

### 3. Push commit + tag
```bash
git push --follow-tags
```

### 4. GitHub Action publishes dev build
```
npm publish --tag dev
```

### 5. Install the dev build
```bash
npm install soxo-bootstrap-core@dev
```

---

# 🟩 Promotion Workflow (Dev → Master)

### 1. Switch to master
```bash
git checkout master
git pull origin master
```

### 2. Merge develop into master
```bash
git merge develop
```

### 3. Bump the stable version
```bash
npm version patch
# or
npm version minor
# or
npm version major
```

### 4. Push with tags
```bash
git push --follow-tags
```

### 5. GitHub Action publishes stable build
```
npm publish
```

### 6. Install stable version
```bash
npm install soxo-bootstrap-core
# or
npm install soxo-bootstrap-core@<version>
```

---

# 🟧 Publishing via GitHub Release UI

### Important
**The tag must match the `package.json` version exactly**, including the `v` prefix.

Example:
```
package.json: "version": "2.4.31-dev.0"
GitHub Tag:  v2.4.31-dev.0
```

---

## Steps

### 1. Ensure `develop` branch is up to date  
Push your changes.

### 2. Ensure version contains a dev suffix  
If not:
```bash
npm version prerelease --preid=dev
git push --follow-tags
```

### 3. Open GitHub → Releases → Draft a new release

### 4. Create tag matching the version  
Example:
```
v2.4.31-dev.0
```

### 5. Select target branch = `develop`

### 6. Title = tag version  
Description is optional.

### 7. Publish the release  
Triggers:
```
npm publish --tag dev
```

---

# ⚙️ How GitHub Action Detects Release Type

If version contains `dev`:
```
npm publish --tag dev
```

Otherwise:
```
npm publish
```

---

# 📊 Summary Table

| Step                     | Branch   | Command                                 | Tag              | Publish Type |
|--------------------------|----------|------------------------------------------|------------------|--------------|
| Create task branch       | master   | `git checkout -b task/<ID>`              | —                | —            |
| Merge task → develop     | develop  | `git merge task/<ID>`                    | —                | —            |
| Dev version              | develop  | `npm version prerelease --preid=dev`     | `vX.Y.Z-dev.N`   | dev          |
| Publish dev build        | develop  | `git push --follow-tags`                 | —                | dev          |
| Merge develop → master   | master   | `git merge develop`                      | —                | —            |
| Stable version           | master   | `npm version patch/minor/major`          | `vX.Y.Z`         | latest       |
| Publish stable build     | master   | `git push --follow-tags`                 | —                | latest       |

---

# ⚠️ Common Mistakes & Fixes

| Mistake                        | Issue                | Fix                             |
|-------------------------------|----------------------|---------------------------------|
| Tag doesn't match version     | Publish fails        | Always use `npm version`         |
| Manual tag creation           | Version mismatch     | Avoid manual tagging             |
| Dev publish from master       | Wrong channel        | Verify branch before tagging     |
| Not pushing tags              | Workflow won’t run   | Use `git push --follow-tags`     |
| Merging incomplete tasks      | Breaks dev builds    | Test before merging              |