Generate published API entry point from src/api.ts

.github/workflows/pr-file-check.yml

@@ -41,3 +41,36 @@ jobs:
             src/**/*.unit.test.ts
           skip-label: 'skip tests'
           failure-message: 'TypeScript code was edited without also editing a test file (the ${skip-label} label can be used to pass this check)'
+
+      - name: 'Public API changes require a version bump'
+        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1
+        with:
+          prereq-pattern: 'src/api.ts'
+          file-pattern: 'api/package.json'
+          skip-label: 'skip api version'
+          failure-message: 'The public API (${prereq-pattern}) was changed without bumping the package version in ${file-pattern} (the ${skip-label} label can be used to pass this check)'
+
+      - name: 'Public API changes require a changelog entry'
+        uses: brettcannon/check-for-changed-files@871d7b8b5917a4f6f06662e2262e8ffc51dff6d1 # v1.2.1
+        with:
+          prereq-pattern: 'src/api.ts'
+          file-pattern: 'api/CHANGELOG.md'
+          skip-label: 'skip api changelog'
+          failure-message: 'The public API (${prereq-pattern}) was changed without a changelog entry in ${file-pattern} (the ${skip-label} label can be used to pass this check)'
+
+  version-match:
+    name: 'Extension and API package versions match'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: 'Compare package.json versions'
+        run: python scripts/compare_package_versions.py

CONTRIBUTING.md

@@ -89,6 +89,15 @@ This project requires contributors to sign a Contributor License Agreement (CLA)
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with questions.
 
+## Public API package (`@vscode/python-environments`)
+
+The npm package under [`api/`](./api) is the public API facade other extensions consume. Its entry point, `api/src/main.ts`, is a **copy** of [`src/api.ts`](./src/api.ts) — the single source of truth — and is **not committed** (see [`api/.gitignore`](./api/.gitignore)).
+
+- Edit the API only in `src/api.ts`. This file contains the full public surface, including the runtime `PythonEnvironments.api()` helper and `EXTENSION_ID`. `api/src/main.ts` is a build artifact — never edit or commit it.
+- `api/src/main.ts` is produced by the publish pipeline ([`build/azure-pipeline.npm.yml`](./build/azure-pipeline.npm.yml)), which copies `src/api.ts` to `api/src/main.ts` before compiling. The api package is therefore built in CI only; to build it locally, copy the file first (e.g. `cp src/api.ts api/src/main.ts`).
+- `src/api.ts` itself is validated on every PR by the extension's own lint and TypeScript compile.
+- **Versioning:** the published package version in [`api/package.json`](./api/package.json) must always match the extension version in [`package.json`](./package.json). CI enforces this via [`scripts/compare_package_versions.py`](./scripts/compare_package_versions.py). Additionally, any PR that edits `src/api.ts` must bump `api/package.json` (use the `skip api version` label to bypass) and add an entry to [`api/CHANGELOG.md`](./api/CHANGELOG.md) (use the `skip api changelog` label to bypass). When bumping, update both `package.json` files so they stay in sync.
+
 ## Questions or Issues?
 
 - **Questions**: Start a [discussion](https://github.com/microsoft/vscode-python/discussions/categories/q-a)

api/.gitignore

@@ -0,0 +1,4 @@
+# Copied from ../src/api.ts by the publish pipeline (build/azure-pipeline.npm.yml).
+# This is the published package entry point; it is produced at publish time and
+# intentionally NOT committed. src/api.ts is the single source of truth.
+src/main.ts

api/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to the `@vscode/python-environments` API package are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.37.0]
+
+- Aligned the API package version with the Python Environments extension version.

api/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@vscode/python-environments",
     "description": "An API facade for the Python Environments extension in VS Code",
-    "version": "1.0.0",
+    "version": "1.37.0",
     "author": {
         "name": "Microsoft Corporation"
     },