docs: expand versioning and release guide in AGENTS.md

Author: sserrata

AGENTS.md

@@ -47,21 +47,115 @@ yarn test
 - `yarn` – install dependencies
 - `yarn build-packages` – compile all packages
 
-## Publish a New Release
-
-1. **Bump the version** (use semantic versioning):
-   ```bash
-   yarn release:version <patch|minor|major>
-   ```
-2. **Update `CHANGELOG.md`** by running:
-   ```bash
-   yarn release:changelog
-   ```
-   Copy the output to the top of `CHANGELOG.md` with the current date. Update the "High level enhancements" section (high-level summary of new features or bug fixes) and clean up the history for public release.
-3. **Cleanup documentation** in `README.md`, `packages/docusaurus-plugin-openapi-docs/README.md` and `demo/docs/intro.mdx`.
-4. **Commit** all changes with the message `Prepare release vX.Y.Z`.
-
-Once merged, the `release.yaml` workflow will publish the release automatically.
+## Versioning and Releases
+
+This project uses [semantic versioning](https://semver.org/) and Lerna for package management. Releases are triggered automatically when version changes are merged to `main`.
+
+### Version Types
+
+| Bump Type    | Example                         | When to Use                             |
+| ------------ | ------------------------------- | --------------------------------------- |
+| `patch`      | `4.5.0` → `4.5.1`               | Bug fixes, minor documentation updates  |
+| `minor`      | `4.5.1` → `4.6.0`               | New features, non-breaking enhancements |
+| `major`      | `4.6.0` → `5.0.0`               | Breaking changes                        |
+| `preminor`   | `4.5.1` → `4.6.0-rc.0`          | Pre-release for upcoming minor version  |
+| `prerelease` | `4.6.0-rc.0` → `4.6.0-rc.1`     | Iterate on existing pre-release         |
+| `graduate`   | `4.6.0-rc.5` → `4.6.0`          | Promote pre-release to stable           |
+| `betamajor`  | `4.5.1` → `5.0.0-beta.0`        | Start a new beta major version          |
+| `betapatch`  | `5.0.0-beta.0` → `5.0.0-beta.1` | Iterate on beta version                 |
+
+### Preparing a Release
+
+#### Step 1: Bump the Version
+
+Run the version command with the appropriate bump type:
+
+```bash
+yarn release:version <bump>
+```
+
+This updates `lerna.json` and all package versions. The version is stored in `lerna.json` and propagated to all packages.
+
+#### Step 2: Generate the Changelog
+
+```bash
+yarn release:changelog
+```
+
+This outputs a changelog template comparing commits between the latest tag and `main`. Copy the output and prepend it to `CHANGELOG.md`.
+
+**Changelog format:**
+
+```markdown
+## X.Y.Z (Mon DD, YYYY)
+
+High level enhancements
+
+- Brief summary of major features or fixes
+
+Other enhancements and bug fixes
+
+- Commit message ([#123](https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/123))
+```
+
+**Guidelines for changelog entries:**
+
+- Replace `TODO HIGHLIGHTS` with a concise summary of user-facing changes
+- Remove internal commits (CI changes, minor refactors) that don't affect users
+- Group related changes together when appropriate
+- Use past tense for descriptions
+
+#### Step 3: Update Documentation (if needed)
+
+Review and update version references in:
+
+- `README.md`
+- `packages/docusaurus-plugin-openapi-docs/README.md`
+- `demo/docs/intro.mdx`
+
+#### Step 4: Commit and Open a PR
+
+```bash
+git add .
+git commit -m "Prepare release vX.Y.Z"
+```
+
+Open a pull request targeting `main`. The PR title should follow the format: `(release) vX.Y.Z`.
+
+### Automatic Publishing
+
+Once the release PR is merged to `main`, the `release.yaml` GitHub Action:
+
+1. Checks if the version tag already exists (skips if it does)
+2. Installs dependencies and builds packages
+3. Publishes packages to npm
+4. Creates and pushes a git tag (`vX.Y.Z`)
+
+**Important:** Do not manually publish or create tags. The workflow handles this automatically.
+
+### Beta Releases
+
+Beta releases follow a separate workflow on the `v3.0.0` branch (or other designated beta branches):
+
+1. Use `betamajor` or `betapatch` to bump versions
+2. Generate changelog with `yarn release:changelog`
+3. Merge to the beta branch
+4. The `release-beta.yaml` workflow publishes with the `beta` npm tag
+
+Users install beta versions with:
+
+```bash
+npm install docusaurus-plugin-openapi-docs@beta
+```
+
+### Troubleshooting Releases
+
+| Issue              | Solution                                                            |
+| ------------------ | ------------------------------------------------------------------- |
+| Release skipped    | Version tag already exists; bump to a new version                   |
+| Changelog empty    | No commits between latest tag and main; verify remote is configured |
+| Publish failed     | Check npm token in GitHub secrets (`NPM_AUTH_TOKEN`)                |
+| Tag already exists | A previous release used this version; bump again                    |
 
 ## Handling Issues and Pull Requests