Merge branch 'main' into feature/http-client-js-playground

Author: timotheeguerin

.github/copilot-instructions.md

@@ -125,9 +125,33 @@ TypeSpec is a language for defining cloud service APIs and shapes. This monorepo
 
 ## Pull Request instructions
 
-- When the work is done, run `pnpm chronus add` to add a changelog entry. Select the correct type of change (fix, feat, docs, etc.) and provide a clear description based on the initial issue description. Only add an area tag when the package has multiple areas and the change targets a secondary area; use bracket format like `[converter]` or `[formatter]` (for example, a secondary openapi3 converter change should start with `[converter]`). Avoid generic area prefixes like `core -` and do not add any area tag for single-area packages. For new features, include a short code block in the changelog entry that showcases the new functionality; skip code blocks for simple bug fixes.
+### Changelog entries
+
+When the work is done, run `pnpm chronus add` to add a changelog entry. The valid change kinds are defined in [`.chronus/config.yaml`](../.chronus/config.yaml). Do **NOT** use `feat`, `docs`, `patch`, `minor`, or `major` — these are not valid change kinds.
+
+**If a PR affects multiple packages with different types of changes, create a separate changelog entry for each.** For example, if the PR adds a feature to `@typespec/http` and fixes a bug in `@typespec/openapi3`, run `pnpm chronus add` twice to create two separate changelog entries — one with `feature` for `@typespec/http` and one with `fix` for `@typespec/openapi3`. Do NOT bundle different change types into a single entry.
+
+### Changelog message guidelines
+
+- Provide a clear description based on the initial issue description.
+- Only add an area tag when the package has multiple areas and the change targets a secondary area; use bracket format like `[converter]` or `[formatter]` (for example, a secondary openapi3 converter change should start with `[converter]`). Avoid generic area prefixes like `core -` and do not add any area tag for single-area packages.
+- For new features, include a short code block in the changelog entry that showcases the new functionality; skip code blocks for simple bug fixes.
+
+### TDD approach
+
 - Always start by defining additional unit tests/updating existing unit tests to fulfill the requirements first. Then make changes to the code accordingly. If you are following the TDD (Test Driven Development) approach, make sure to run the tests and see them fail before implementing the code changes.
 
+## Branch Naming Conventions
+
+### Out-of-sync / hotfix releases
+
+Out-of-sync releases and hotfix releases follow the same flow using a `publish/` branch:
+
+- **Pattern:** `publish/<package>-release-<MM-DD>` (e.g., `publish/python-release-03-26`)
+- These branches skip certain CI checks (consistency, external-integration) and auto-publish on merge
+- For **out-of-sync releases**, the PR targets `main`
+- For **hotfix releases**, the PR targets the corresponding `release/*` branch (e.g., `release/v0.60`) instead of `main`
+
 ## Available Task Instructions
 
 - [Testserver Generation](./prompts/testserver-generation.md): Instructions for generating TypeSpec HTTP spec test servers

.github/dependabot.yml

@@ -25,6 +25,7 @@ updates:
       - "packages/http-client-csharp"
       - "packages/http-client-java"
       - "packages/http-client-python"
+    labels: [] # conflict with our labels in labels.ts
     groups:
       alloy:
         patterns:
@@ -126,6 +127,7 @@ updates:
       interval: "weekly"
     exclude-paths:
       - ".github/workflows/*.lock.{yaml,yml}"
+    labels: [] # conflict with our labels in labels.ts
     groups:
       actions:
         patterns:

.github/skills/emitter-prep-for-pr/SKILL.md

@@ -264,14 +264,30 @@ Write changeset messages that are:
 
 ### Multiple packages
 
-If changes affect multiple packages, list all of them:
+If changes affect multiple packages **with the same change kind**, list all of them in a single changeset:
 
 ```yaml
 packages:
   - "@typespec/http-client-python"
   - "@typespec/http-client-csharp"
 ```
 
+**If packages have different change kinds, create separate changeset files for each.** For example, if the PR adds a feature to `@typespec/http-client-python` and fixes a bug in `@typespec/http-client-csharp`, create two files:
+
+```yaml
+# File 1: feature for python
+changeKind: feature
+packages:
+  - "@typespec/http-client-python"
+```
+
+```yaml
+# File 2: fix for csharp
+changeKind: fix
+packages:
+  - "@typespec/http-client-csharp"
+```
+
 ### Skipping changeset
 
 Some changes don't need a changeset:

.github/workflows/core-ci.yml

@@ -0,0 +1,183 @@
+name: Core CI
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+    # Exclude isolated emitter packages and files already checked by dedicated CI workflows
+    paths-ignore:
+      - ".prettierignore"
+      - ".prettierrc.json"
+      - "cspell.yaml"
+      - "eslint.config.json"
+      - ".chronus/**"
+      - "eng/emitters/**"
+      - "packages/http-client-csharp/**"
+      - "packages/http-client-java/**"
+      - "packages/http-client-python/**"
+  pull_request:
+    branches:
+      - main
+      - "release/*"
+    paths-ignore:
+      - ".prettierignore"
+      - ".prettierrc.json"
+      - "cspell.yaml"
+      - "eslint.config.json"
+      - ".chronus/**"
+      - "eng/emitters/**"
+      - "packages/http-client-csharp/**"
+      - "packages/http-client-java/**"
+      - "packages/http-client-python/**"
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build (${{ matrix.os }}, Node ${{ matrix.node-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node-version: ["20.x", "22.x", "24.x"]
+
+    env:
+      TYPESPEC_VS_CI_BUILD: true
+      TYPESPEC_SKIP_WEBSITE_BUILD: true
+
+    steps:
+      - name: Enable git long paths (Windows)
+        if: runner.os == 'Windows'
+        run: git config --global core.longpaths true
+
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Restore .NET dependencies
+        run: dotnet restore
+        working-directory: packages/typespec-vs
+
+      - name: Build
+        run: pnpm run build
+
+      - name: Test
+        run: pnpm vitest run --coverage --reporter=default --reporter=github-actions
+
+      - name: Upload coverage artifacts
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-${{ matrix.os }}-node${{ matrix.node-version }}
+          path: packages/*/coverage/
+          retention-days: 5
+
+      - name: Check for changed files
+        run: node eng/common/scripts/check-for-changed-files.js
+
+  website:
+    name: Website
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Build website
+        run: pnpm --filter "@typespec/website..." run build
+
+      - name: Check for changed files
+        run: node eng/common/scripts/check-for-changed-files.js
+
+  e2e:
+    name: E2E Tests
+    runs-on: ubuntu-latest
+
+    env:
+      TYPESPEC_VS_CI_BUILD: false
+      TYPESPEC_SKIP_WEBSITE_BUILD: true
+      DISPLAY: ":99"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/setup
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Install Playwright browsers
+        run: |
+          sudo dpkg --configure -a
+          npx playwright install --with-deps
+
+      - name: Start Xvfb
+        run: |
+          /usr/bin/Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+          echo "Started xvfb"
+
+      - name: Build
+        run: pnpm run build
+
+      - name: E2E Tests
+        run: pnpm run test:e2e
+
+      - name: Upload UI test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: uitestresults-e2e
+          path: packages/playground-website/test-results/
+          retention-days: 5
+
+      - name: Upload screenshots
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: screenshots
+          path: packages/typespec-vscode/temp/images-linux/
+          retention-days: 5
+
+      - name: Upload trace results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: trace-results
+          path: packages/typespec-vscode/test-results/
+          retention-days: 5
+
+      - name: Check for changed files
+        run: node eng/common/scripts/check-for-changed-files.js
+
+  docker:
+    name: Docker Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build -f ./docker/Dockerfile .

.github/workflows/merge-release-in-main.yml

@@ -25,13 +25,16 @@ jobs:
 
       - name: Generate branch name
         id: branchname
+        env:
+          REF_NAME: ${{ github.ref_name }}
         run: |
-          echo "branchname=backmerge/${{ github.ref_name }}-$(date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
+          echo "branchname=backmerge/${REF_NAME}-$(date +'%Y-%m-%d')" >> "$GITHUB_OUTPUT"
       - name: Create branch
+        env:
+          BRANCH: ${{ steps.branchname.outputs.branchname }}
         run: |
-          branch="${{ steps.branchname.outputs.branchname }}"
-          git checkout -b $branch
-          git push --set-upstream origin $branch
+          git checkout -b "$BRANCH"
+          git push --set-upstream origin "$BRANCH"
 
       - name: create pull request
         id: open-pr

CONTRIBUTING.md

@@ -51,7 +51,7 @@ Those commands can be run on the workspace or in a specific package(`cd ./packag
 | `pnpm format`               | Format                                                                                                                                                    |
 | `pnpm format:check`         | Validate files are formatted                                                                                                                              |
 | `pnpm gen-extern-signature` | Regenerate TypeScript signature for decorators(except compiler)                                                                                           |
-| `pnpm change add`           | Add a change description                                                                                                                                  |
+| `pnpm change add`           | Add a change description (see valid kinds in [`.chronus/config.yaml`](.chronus/config.yaml))                                                              |
 | `pnpm lint`                 | Run linters                                                                                                                                               |
 | `pnpm lint:fix`             | Fix autofixable issues                                                                                                                                    |
 | `pnpm regen-samples`        | Regen the samples(when the samples test fail)                                                                                                             |
@@ -66,6 +66,15 @@ TYPESPEC_VERBOSE_TEST_OUTPUT=true.
 
 **For the compiler you will need to run it manually or run the whole workspace build. This is because for the tool to run it needs the compiler to build first.**
 
+### Writing tests
+
+Tests use [vitest](https://vitest.dev/) with the `createTester` API from `@typespec/compiler/testing`. **Do not** use the legacy `createTestHost`/`createTestRunner` APIs — they are deprecated. See the [testing documentation](https://typespec.io/docs/extending-typespec/testing) for the full guide and migration instructions.
+
+**Test structure rules:**
+
+- Do **not** wrap tests in a top-level `describe`. The test file name already provides context. Use `it()` directly at the top level. Only use `describe()` for sub-groups within a file.
+- Use `it` (not `test`) for test functions, as enforced by ESLint (`vitest/consistent-test-it`).
+
 ## Using VS Code
 
 ### Recommended extensions

packages/compiler/test/e2e/cli/cli.e2e.ts

@@ -16,7 +16,10 @@ interface ExecCliOptions {
 
 async function execCli(args: string[], { cwd }: ExecCliOptions) {
   const node = process.platform === "win32" ? "node.exe" : "node";
-  return execAsync(node, [resolvePath(pkgRoot, "entrypoints/cli.js"), ...args], { cwd });
+  return execAsync(node, [resolvePath(pkgRoot, "entrypoints/cli.js"), ...args], {
+    cwd,
+    env: { ...process.env, NO_COLOR: "1" },
+  });
 }
 async function execCliSuccess(args: string[], { cwd }: ExecCliOptions) {
   const result = await execCli(args, { cwd });