# Publishing Guide

This document explains how to publish new versions of `@7365admin1/layer-common` to npm using changesets and GitHub Actions.

## Overview

The package uses an automated publishing workflow powered by [Changesets](https://github.com/changesets/changesets) and GitHub Actions. When you make changes and create a changeset, the workflow automatically:

1. Creates a "Version Packages" PR with version bumps
2. Publishes to npm when you merge that PR

## Quick Start

### 1. Make Your Changes

Make your code changes in a new branch as usual.

### 2. Create a Changeset

Before committing, create a changeset to document your changes:

```bash
npx changeset
```

You'll be prompted to:
- Select the type of change: `patch`, `minor`, or `major`
- Write a summary of your changes

This creates a `.changeset/[random-name].md` file.

### 3. Commit and Push

```bash
git add .
git commit -m "feat: your feature description"
git push
```

### 4. Create a Pull Request

Create a PR to merge your branch into `main`.

### 5. Merge Your PR

Once approved, merge your PR to `main`.

### 6. Bot Creates Version PR (Automatic)

After merging, the GitHub Actions bot will automatically:
- Detect your changeset
- Create a new PR titled "Version Packages"
- Update `package.json` with the new version
- Update `CHANGELOG.md`
- Remove the changeset file

### 7. Merge the Version PR

Review and merge the "Version Packages" PR. This will:
- Bump the version in `package.json`
- Automatically publish to npm 🚀

## Workflow Diagram

```
You: Make changes + create changeset
         ↓
You: Push and create PR
         ↓
You: Merge PR to main
         ↓
Bot: Creates "Version Packages" PR (automatic)
         ↓
You: Merge "Version Packages" PR
         ↓
Bot: Publishes to npm (automatic)
```

## Version Types

When creating a changeset, you'll choose a version bump type:

- **patch** (1.8.0 → 1.8.1): Bug fixes, minor changes
- **minor** (1.8.0 → 1.9.0): New features, backward compatible
- **major** (1.8.0 → 2.0.0): Breaking changes

## Common Commands

### Create a Changeset
```bash
npx changeset
```

### Create an Empty Changeset
```bash
npx changeset add --empty
```

### Check Which Packages Would Be Published
```bash
npx changeset status
```

### Manually Version (Local Testing Only)
```bash
npx changeset version
```

### Manually Publish (Not Recommended)
```bash
yarn run release
```
> ⚠️ **Note**: Manual publishing requires 2FA or an automation token. Use GitHub Actions instead.

## GitHub Setup

### Required Secrets

The repository needs the following GitHub secret:

**`NPM_TOKEN`**
- Location: Settings → Secrets and variables → Actions
- Type: Granular Access Token (Automation)
- Value: Your npm automation token
- Permissions: Read and Write for packages, with 2FA bypass enabled

### Workflow Files

- `.github/workflows/main.yml` - CI workflow (builds and tests)
- `.github/workflows/publish.yml` - Publish workflow (creates PRs and publishes)

## Configuration Files

### `.changeset/config.json`

```json
{
  "$schema": "https://unpkg.com/@changesets/config@3.0.5/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "access": "public",
  "baseBranch": "main"
}
```

Key settings:
- `"access": "public"` - Package is published as public (free)
- `"baseBranch": "main"` - PRs are created against main

### `package.json`

```json
{
  "name": "@7365admin1/layer-common",
  "version": "1.8.1",
  "author": "7365admin1",
  "publishConfig": {
    "access": "public"
  }
}
```

Key settings:
- `"publishConfig.access": "public"` - Ensures scoped package is public

## Troubleshooting

### "Version didn't update on npm"

**Solution**: Make sure you merged the bot's "Version Packages" PR. The version only publishes after merging that PR, not your original PR.

### "No Version Packages PR was created"

**Possible causes**:
1. No changeset file was committed
2. CI workflow failed
3. Check GitHub Actions logs for errors

**Solution**: Run `npx changeset status` locally to verify changesets exist.

### "402 Payment Required" Error

**Cause**: Scoped packages (`@username/package`) are private by default and require payment.

**Solution**: Ensure `publishConfig.access` is set to `"public"` in `package.json`.

### "403 Forbidden" or "401 Unauthorized"

**Cause**: Invalid or expired npm token.

**Solution**: 
1. Generate a new Granular Access Token (Automation type) on npmjs.com
2. Update the `NPM_TOKEN` secret in GitHub
3. Ensure token has "Bypass 2FA" enabled

### "Changeset not found" Error

**Cause**: Changeset file wasn't committed or was deleted.

**Solution**: Run `npx changeset` again and commit the generated `.changeset/*.md` file.

## Best Practices

### 1. Always Create Changesets

Never merge code changes without a changeset. It ensures:
- Version tracking
- Changelog updates
- Proper npm publishing

### 2. Write Clear Changeset Summaries

Your changeset summary becomes the changelog entry. Make it:
- Clear and concise
- User-focused (what changed, not how)
- Action-oriented (e.g., "Added X feature" not "Adding X feature")

### 3. Don't Skip the Version PR

Always review and merge the "Version Packages" PR. It shows exactly what will be published.

### 4. Use Yarn for Local Development

The project uses Yarn for dependency management:

```bash
yarn install
yarn dev
yarn build
```

### 5. Keep `.npmrc` Private

The `.npmrc` file contains your authentication token. It's in `.gitignore` - **never commit it!**

## Security

### npm Authentication

- **GitHub Actions**: Uses `NPM_TOKEN` secret (automation token)
- **Local Publishing**: Uses `.npmrc` file (not committed to git)

### Token Types

- **Automation tokens**: Bypass 2FA, designed for CI/CD
- **Publish tokens**: Require 2FA, for manual publishing

Always use automation tokens for GitHub Actions.

## Package Information

- **Name**: `@7365admin1/layer-common`
- **Registry**: https://registry.npmjs.org/
- **Package Page**: https://www.npmjs.com/package/@7365admin1/layer-common
- **Author**: 7365admin1
- **License**: MIT

## Need Help?

If you encounter issues:

1. Check the [Changesets documentation](https://github.com/changesets/changesets)
2. Review GitHub Actions workflow logs
3. Verify npm token is valid and has correct permissions
4. Ensure `.changeset/config.json` has `"access": "public"`

---

**Last Updated**: January 2026
