Skip to content

RELEASING.md

Latest commit

 

History

History
81 lines (53 loc) · 4.92 KB

RELEASING.md

File metadata and controls

81 lines (53 loc) · 4.92 KB

🚀 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.

📚 Table of Contents

  1. Versioning Convention
  2. Pre-Release Flow (Automated)
  3. Stable Release Flow (Manual)
  4. Marketplace README Limitation
  5. Marking Pre-Release-Only Features in the README

🔢 Versioning Convention

We follow VS Code's recommended odd/even pre-release scheme:

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.

  • 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. 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).

  2. Update the changelog + readme.

    • Rename [Unreleased] in the root 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).

  3. Bump the version. Set version in 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.

  4. 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 packages lana-<package.json version>.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.

  5. 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.

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:

> 🧪 **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).