From 0fd95cdcc312fe50a20df9fb2a95c0919a7a789a Mon Sep 17 00:00:00 2001 From: Luke Cotter <4013877+lukecotter@users.noreply.github.com> Date: Fri, 29 May 2026 15:43:57 +0100 Subject: [PATCH] docs(release): add maintainer release guide and link it from docs - add RELEASING.md with concise stable/pre-release process and versioning rules - document when to use main vs a release branch for older-line patch releases - cross-link CONTRIBUTING.md and DEVELOPING.md to the release guide for maintainers --- CONTRIBUTING.md | 2 ++ DEVELOPING.md | 2 +- RELEASING.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 RELEASING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0603467..0b202555 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,6 +17,8 @@ Before you dive in, please make sure to review our [code of conduct](https://git For detailed instructions on setting up your development environment, refer to the [Development Guide](https://github.com/certinia/debug-log-analyzer/blob/main/DEVELOPING.md). +> πŸ”– Maintainers: see the [Release Guide](https://github.com/certinia/debug-log-analyzer/blob/main/RELEASING.md) for the versioning convention and how stable/pre-release publishing works. + ## πŸš€ Ready to Contribute? We can't wait to see your contributions! Whether it’s fixing a bug, adding a new feature, or improving the docs, we truly appreciate your time and effort. diff --git a/DEVELOPING.md b/DEVELOPING.md index 4652d5a0..cdba1057 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -111,7 +111,7 @@ Ensure all tests pass before submitting your pull request. ## πŸ“¦ Packaging the Extension -This is for information only packaging and releasing is handled in Github. +This is for information only - packaging and releasing are handled in GitHub (see [RELEASING.md](./RELEASING.md) for the maintainer guide). Once you're ready to package the extension for distribution: 1. Ensure that you’ve installed the dependencies: diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 00000000..849f10c3 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,81 @@ +# πŸš€ Releasing the Apex Log Analyzer Extension + +This guide explains how maintainers release stable and pre-release versions. + +> ℹ️ Contributors don't need this β€” packaging and publishing are handled in GitHub by maintainers. +> For local dev and packaging, see [DEVELOPING.md](./DEVELOPING.md). + +## πŸ“š Table of Contents + +1. [Versioning Convention](#-versioning-convention) +2. [Pre-Release Flow (Automated)](#-pre-release-flow-automated) +3. [Stable Release Flow (Manual)](#-stable-release-flow-manual) +4. [Marketplace README Limitation](#-marketplace-readme-limitation) +5. [Marking Pre-Release-Only Features in the README](#-marking-pre-release-only-features-in-the-readme) + +## πŸ”’ Versioning Convention + +We follow VS Code's recommended [odd/even pre-release scheme](https://code.visualstudio.com/api/working-with-extensions/publishing-extension#prerelease-extensions): + +> Why this convention: Marketplace publishing supports `major.minor.patch` only (no SemVer pre-release identifiers), so pre-release and stable builds must use different numeric versions. We use odd/even minors for that split. See [microsoft/vsmarketplace#50](https://github.com/microsoft/vsmarketplace/issues/50). + +- **Stable** β€” `major.EVEN.patch` (e.g. `1.18.1`). The **minor is always even**. +- **Pre-release** β€” `major.ODD.yyyymmdd` (e.g. `1.19.20260529`). The **minor is the next odd + number** and the patch is the build date. + +Keep the committed `lana/package.json` version on the current stable (even minor). + +## πŸ€– Pre-Release Flow (Automated) + +Pre-releases are fully automated by [`.github/workflows/cd-prerelease.yml`](./.github/workflows/cd-prerelease.yml). No manual action is required. + +- **Trigger** β€” weekly cron (Tuesdays 04:15 UTC) plus manual `workflow_dispatch`. +- **`check` job** β€” compares `HEAD` against the floating `pre` tag and the latest stable tag. If `HEAD` already matches either (no new commits since the last pre-release or stable), it exits early and nothing is published. +- **`publish` job** β€” when there are new commits it bumps a CI-only pre-release version, packages and publishes with `--pre-release`, then moves the floating `pre` tag to `HEAD`. + +## πŸ“¦ Stable Release Flow (Manual) + +A stable release is cut by hand. Do these steps in order: + +1. **Choose the release branch.** + - Use `main` for the current stable line. + - Create/use a release branch only when shipping a patch for an older version line (for example, `main` already contains work for the next major/minor). + +1. **Update the changelog + readme.** + - Rename `[Unreleased]` in the root [`CHANGELOG.md`](./CHANGELOG.md) to `## [X.Y.Z] YYYY-MM-DD` . + - Only edit the **root** `CHANGELOG.md` + - Remove any `πŸ§ͺ Pre-Release` markers in the root `README.md` for features that ship in this + release (see [Marking Pre-Release-Only Features](#-marking-pre-release-only-features-in-the-readme)). + +1. **Bump the version.** Set `version` in [`lana/package.json`](./lana/package.json) to the new stable version. Use the **next even minor** (`1.18.x` β†’ `1.20.0`) for a feature release, or a patch bump (`1.18.1` β†’ `1.18.2`) for a fix-only release. Commit these changes to the selected release branch. +1. **Create a GitHub Release.** Tag the release with a name that **exactly equals** the + `lana/package.json` version (e.g. `1.20.0`). + + > ⚠️ **Gotcha:** [`.github/workflows/publish.yml`](./.github/workflows/publish.yml) packages + > `lana-.vsix` but publishes `lana-${tag_name}.vsix`. If the tag name and + > the `package.json` version don't match, the publish step fails because the `.vsix` filename + > won't exist. **No `v` prefix** β€” use `1.20.0`, not `v1.20.0`. + +1. **Publish runs automatically.** `publish.yml` fires on the release `published` event, packages the + extension, and publishes the stable build to the VS Code Marketplace and Open VSX. + +## 🌐 Marketplace README Limitation + +VS Code Marketplace always shows the README and `CHANGELOG` from the highest published version. There is no separate stable/pre-release README. Because pre-releases usually have a higher odd minor, the public Marketplace page may show pre-release docs. See [microsoft/vscode#163477](https://github.com/microsoft/vscode/issues/163477). + +Practical consequences: + +- Keep the README channel-neutral. +- Treat root `README.md`, `CHANGELOG.md`, and `LICENSE.txt` as the source of truth. Do not hand-edit the generated `lana/` copies. + +## πŸ§ͺ Marking Pre-Release-Only Features in the README + +Because the public README can show pre-release content to stable users (see above), make pre-release-only features clearly marked so stable users aren't misled about what they can use today. + +Add a blockquote callout directly under the relevant feature in the root `README.md`: + +```md +> πŸ§ͺ **Pre-Release** β€” available in the Pre-Release Version; not yet in the stable release. +``` + +When a feature graduates to stable, **removing its `πŸ§ͺ Pre-Release` marker is part of the stable release checklist** (step 1 above).