npm package: @squiz/dxp-ai-semantic-release-config
Description: Shared semantic-release configuration for DXP AI Tools
Latest version: 0.0.29

# @squiz/dxp-ai-semantic-release-config

Shared semantic-release configuration for DXP AI Tools repository.

## Features

- **Multi-environment support**: Feature, Development, Staging, and Production releases
- **Git tag namespacing**: Prevents conflicts between different environments using tag prefixes
- **Conventional commits**: Automatic version bumping based on commit messages
- **NPM dist-tag support**: Publish to different dist-tags (alpha, dev, stg, latest)

## Installation

```bash
npm install --save-dev @squiz/dxp-ai-semantic-release-config
```

## Usage

In your tool's `package.json`:

```json
{
  "release": {
    "extends": "@squiz/dxp-ai-semantic-release-config"
  }
}
```

Or create a `.releaserc.js`:

```javascript
module.exports = require('@squiz/dxp-ai-semantic-release-config');
```

## Environment Variables

### `RELEASE_STAGE`

Controls which release stage to execute and determines git tag prefix:

- **`feature`**: Creates alpha prerelease versions with `feature-v` tag prefix
- **`development`**: Creates dev prerelease versions with `dev-v` tag prefix
- **`staging`**: Creates beta prerelease versions with `stg-v` tag prefix
- **`production`** (or unset): Creates stable versions with `v` tag prefix

### `NPM_CONFIG_TAG`

Controls the npm dist-tag for publishing:

- **`alpha`**: Feature/alpha dist-tag
- **`dev`**: Development dist-tag
- **`stg`**: Staging dist-tag
- **`latest`**: Production dist-tag (default)

## Environment Configuration

| Environment | Branch | RELEASE_STAGE | NPM_CONFIG_TAG | Git Tag Format | Version Example | Use Case |
|-------------|--------|---------------|----------------|----------------|-----------------|----------|
| **Feature** | `feature/*` | `feature` | `alpha` | `feature-v${version}` | `feature-v1.0.0-alpha.1` | Feature branch testing |
| **Development** | `develop` | `development` | `dev` | `dev-v${version}` | `dev-v1.0.0-dev.5` | Development environment |
| **Staging** | `main` | `staging` | `stg` | `stg-v${version}` | `stg-v1.0.0-beta.1` | Pre-production testing |
| **Production** | `main` | `production` | `latest` | `v${version}` | `v1.0.0` | Production releases |

## Git Tag Prefixes

Different tag prefixes prevent conflicts between environments:

- **Feature**: `feature-v1.0.0-alpha.1`
- **Development**: `dev-v1.0.0-dev.5`
- **Staging**: `stg-v1.0.0-beta.1`
- **Production**: `v1.0.0`

This allows semantic-release to track releases independently across all environments.

## CI/CD Examples

### Staging Pipeline (Tools Repo)

```yaml
staging:publish-tools:
  stage: staging-deploy
  variables:
    RELEASE_STAGE: staging
    NPM_CONFIG_TAG: stg
  script:
    - npm run publish-tools
```

### Production Pipeline (Tools Repo)

```yaml
production:publish-tools:
  stage: production-deploy
  variables:
    RELEASE_STAGE: production
    NPM_CONFIG_TAG: latest
  script:
    - npm run publish-tools
```

## Commit Message Format

This config uses conventional commits for version bumping:

| Commit Type | Release Type | Example |
|-------------|--------------|---------|
| `feat:` | minor | `feat: add new validation rule` |
| `fix:` | patch | `fix: correct schema validation` |
| `docs:` (with README scope) | patch | `docs(README): update examples` |
| `refactor:` | patch | `refactor: simplify error handling` |
| `style:` | patch | `style: format code` |
| `test:` | patch | `test: add unit tests` |
| `BREAKING CHANGE:` | major | Any commit with `BREAKING CHANGE:` in body |

## Publishing Flow

### Same Branch, Different Stages

Both staging and production can run on `main` branch without conflicts:

```
1. Push to main → Both pipelines trigger

2. Staging runs first:
   ├─ RELEASE_STAGE=staging
   ├─ Creates version: 1.0.0-beta.1
   ├─ Creates tag: stg-v1.0.0-beta.1
   ├─ Publishes: npm publish --tag stg
   └─ Success ✅

3. Production runs later:
   ├─ RELEASE_STAGE=production
   ├─ Ignores stg-v* tags
   ├─ Creates version: 1.0.0
   ├─ Creates tag: v1.0.0
   ├─ Publishes: npm publish --tag latest
   └─ Success ✅

No conflict! Different tag prefixes keep them separate.
```

## Registry Configuration

This config works with any npm-compatible registry. Registry configuration should be set in `.npmrc`:

```ini
# GitLab Package Registry
@squiz-ai-tool:registry=https://gitlab.squiz.net/api/v4/projects/17893/packages/npm/
//gitlab.squiz.net/api/v4/projects/17893/packages/npm/:_authToken=${CI_JOB_TOKEN}
```

## License

ISC