ui-soxo-bootstrap-core 2.6.40-dev.1 → 2.6.40-dev.12

package/DEVELOPER_GUIDE.md

@@ -1,323 +1,323 @@
-# 📦 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
-- CI/CD Authentication (Trusted Publishing)
-- 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 ui-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 ui-soxo-bootstrap-core
-# or
-npm install ui-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
-
-The workflow reads the `version` field from `package.json` at publish time:
-
-| Condition                    | Command                                                 | Result                             |
-| ---------------------------- | ------------------------------------------------------- | ---------------------------------- |
-| Version contains `-dev`      | `npm publish --provenance --access public --tag dev`    | Publishes to the `dev` dist-tag    |
-| Version has no `-dev` suffix | `npm publish --provenance --access public --tag latest` | Publishes to the `latest` dist-tag |
-
-The workflow also enforces that the GitHub release tag matches `v<version>` from `package.json` and fails the run immediately if they diverge — this prevents the most common publish failure described below.
-
----
-
-# 📊 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       |
-
----
-
-# 🔐 CI/CD Authentication (Trusted Publishing)
-
-As of npm's 2025 policy changes, classic automation tokens (`NPM_TOKEN`) are deprecated. This repo now authenticates to npm via **OIDC Trusted Publishing** — GitHub Actions exchanges a short-lived OIDC token for a publish token at run time, so **no secret is stored in the repository**.
-
-## What this means for developers
-
-Nothing. You still follow the same flow: `npm version` → push tag → create GitHub Release. The auth happens transparently in CI.
-
-## What this means for maintainers
-
-The first-time setup on npmjs.com must be done once per package:
-
-1. Log in to [npmjs.com](https://www.npmjs.com) → open the package (`ui-soxo-bootstrap-core`) → **Settings**.
-2. Under **Trusted Publisher**, click **Add trusted publisher** and fill in:
-   - Publisher: **GitHub Actions**
-   - Organization or user: `soxo-tech`
-   - Repository: `bootstrap-core`
-   - Workflow filename: `npm-publish.yml`
-   - Environment name: *(leave blank)*
-3. Save. Any old `NPM_TOKEN` repository secret can be removed.
-
-## Runtime requirements
-
-The workflow runs on Node 20 and upgrades npm to the latest CLI (`npm install -g npm@latest`) because OIDC trusted publishing requires **npm ≥ 11.5.1**. The `--provenance` flag attaches a verifiable build attestation to every published version, visible on the npmjs.com package page.
-
-## If publish fails with `403 Forbidden` or `ENEEDAUTH`
-
-The trusted publisher config on npmjs.com no longer matches the workflow. Check that org, repo, and workflow filename match exactly — including case.
-
----
-
-# ⚠️ 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          |
+# 📦 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
+- CI/CD Authentication (Trusted Publishing)
+- 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 ui-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 ui-soxo-bootstrap-core
+# or
+npm install ui-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
+
+The workflow reads the `version` field from `package.json` at publish time:
+
+| Condition                    | Command                                                 | Result                             |
+| ---------------------------- | ------------------------------------------------------- | ---------------------------------- |
+| Version contains `-dev`      | `npm publish --provenance --access public --tag dev`    | Publishes to the `dev` dist-tag    |
+| Version has no `-dev` suffix | `npm publish --provenance --access public --tag latest` | Publishes to the `latest` dist-tag |
+
+The workflow also enforces that the GitHub release tag matches `v<version>` from `package.json` and fails the run immediately if they diverge — this prevents the most common publish failure described below.
+
+---
+
+# 📊 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       |
+
+---
+
+# 🔐 CI/CD Authentication (Trusted Publishing)
+
+As of npm's 2025 policy changes, classic automation tokens (`NPM_TOKEN`) are deprecated. This repo now authenticates to npm via **OIDC Trusted Publishing** — GitHub Actions exchanges a short-lived OIDC token for a publish token at run time, so **no secret is stored in the repository**.
+
+## What this means for developers
+
+Nothing. You still follow the same flow: `npm version` → push tag → create GitHub Release. The auth happens transparently in CI.
+
+## What this means for maintainers
+
+The first-time setup on npmjs.com must be done once per package:
+
+1. Log in to [npmjs.com](https://www.npmjs.com) → open the package (`ui-soxo-bootstrap-core`) → **Settings**.
+2. Under **Trusted Publisher**, click **Add trusted publisher** and fill in:
+   - Publisher: **GitHub Actions**
+   - Organization or user: `soxo-tech`
+   - Repository: `bootstrap-core`
+   - Workflow filename: `npm-publish.yml`
+   - Environment name: *(leave blank)*
+3. Save. Any old `NPM_TOKEN` repository secret can be removed.
+
+## Runtime requirements
+
+The workflow runs on Node 20 and upgrades npm to the latest CLI (`npm install -g npm@latest`) because OIDC trusted publishing requires **npm ≥ 11.5.1**. The `--provenance` flag attaches a verifiable build attestation to every published version, visible on the npmjs.com package page.
+
+## If publish fails with `403 Forbidden` or `ENEEDAUTH`
+
+The trusted publisher config on npmjs.com no longer matches the workflow. Check that org, repo, and workflow filename match exactly — including case.
+
+---
+
+# ⚠️ 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          |