Release 0.7.4 (#597)

Author: tnaum-ms

.github/skills/review-external-pr/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: review-external-pr
+description: Prepare an external contributor's PR for maintainer review by redirecting it into a dedicated review branch, then merging and creating a new finalization PR targeting next. Use when triaging/reviewing contributor PRs, merging external PRs with maintainer changes, or setting up a review workflow for incoming community contributions.
+---
+
+# Review External PR Workflow
+
+Redirects an external contributor's PR into a `reviews/` staging branch so a maintainer can inspect, add changes, then merge everything into `next` cleanly.
+
+## When to Use
+
+- An external contributor opened a PR targeting `next` and you want to add changes before merging
+- You want to formally review and finalize a community contribution
+- You want the contributor to get proper merge credit while still controlling what lands in `next`
+
+## Workflow Steps
+
+### 1. Gather PR Info
+
+```bash
+gh pr view <PR_NUMBER> --json title,author,headRefName,baseRefName,body
+```
+
+Note the **PR number**, **title**, and **author login** — you'll need them for branch naming and PR descriptions.
+
+### 2. Create the Review Branch
+
+Branch naming format: `reviews/<helpful-name>-original-pr-<number>`
+
+```bash
+git fetch origin
+git checkout -b reviews/<helpful-name>-original-pr-<PR_NUMBER> origin/next
+git push origin reviews/<helpful-name>-original-pr-<PR_NUMBER>
+```
+
+Example: `reviews/copy-reference-original-pr-545`
+
+### 3. Retarget the Contributor's PR
+
+> ⚠️ **Known issue**: `gh pr edit --base` may emit a deprecation warning about Projects (classic). This is a cosmetic warning only — the base branch change succeeds regardless. Verify with `gh pr view <PR_NUMBER> --json baseRefName`.
+
+```bash
+gh pr edit <PR_NUMBER> --base reviews/<helpful-name>-original-pr-<PR_NUMBER>
+```
+
+Verify:
+
+```bash
+gh pr view <PR_NUMBER> --json baseRefName
+```
+
+### 4. Merge the Contributor's PR
+
+Once the base is updated and the PR is ready:
+
+```bash
+gh pr merge <PR_NUMBER> --squash
+```
+
+Or approve + merge via the GitHub UI to trigger any required status checks.
+
+### 5. Create the Finalization PR
+
+Pull the merged review branch, then open a new PR from it to `next`:
+
+```bash
+git checkout reviews/<helpful-name>-original-pr-<PR_NUMBER>
+git pull origin reviews/<helpful-name>-original-pr-<PR_NUMBER>
+```
+
+Create the PR:
+
+```bash
+gh pr create \
+  --base next \
+  --head reviews/<helpful-name>-original-pr-<PR_NUMBER> \
+  --title "<original title> [reviewed]" \
+  --body "This PR finalizes the review of the contribution originally submitted by @<author_login> in #<PR_NUMBER>.
+
+Original PR: <PR_URL>"
+```
+
+### 6. Comment on the Original PR
+
+Go back to the contributor's original (now merged) PR and leave a comment linking to the finalization PR:
+
+```bash
+gh pr comment <ORIGINAL_PR_NUMBER> \
+  --body "Thank you for the contribution! The review is continuing in #<NEW_PR_NUMBER> where maintainer changes will be finalized before merging to \`next\`."
+```
+
+## Summary
+
+| Step | Action                                     | Result                                    |
+| ---- | ------------------------------------------ | ----------------------------------------- |
+| 1    | Gather PR info                             | Know PR number, title, author             |
+| 2    | Create `reviews/...` branch off `next`     | Staging branch ready                      |
+| 3    | Retarget contributor's PR to review branch | Their diff is scoped to review branch     |
+| 4    | Merge contributor's PR                     | Contributor gets merge credit             |
+| 5    | Create finalization PR to `next`           | Maintainer controls what lands in `next`  |
+| 6    | Comment on original PR with link to new PR | Contributor is informed, thread is linked |

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change Log
 
+## 0.7.4
+
+### New Features & Improvements
+
+- **URL-Encoded Password Detection**: When a connection attempt fails and the password contains URL-encoded characters, the extension now offers a "Retry with Decoded Password" option. If the retry succeeds, the decoded password can be saved. [#444](https://github.com/microsoft/vscode-documentdb/issues/444), [#594](https://github.com/microsoft/vscode-documentdb/pull/594)
+- **Rich Markdown Tooltips**: Cluster, database, and collection tree items in the Connections view now show rich markdown tooltips on hover, displaying useful details (host, auth method, document count, storage size) without requiring expansion or connection. [#579](https://github.com/microsoft/vscode-documentdb/issues/579), [#588](https://github.com/microsoft/vscode-documentdb/pull/588)
+- **Copy Reference Context Menu**: Adds a "Copy Reference…" right-click option to database, collection, and index nodes with a QuickPick format picker. Databases offer name, shell command (`use dbName`), or qualified name; collections offer name, namespace, shell reference, or `db.getCollection()` form; indexes offer name, key definition, or shell command. Names with special characters automatically use safe escaping. [#545](https://github.com/microsoft/vscode-documentdb/pull/545), [#587](https://github.com/microsoft/vscode-documentdb/pull/587)
+
+### Documentation
+
+- **Improved CONTRIBUTING.md**: Adds a PR submission checklist, corrects Node/npm version requirements, and adds multi-platform setup stubs. [#565](https://github.com/microsoft/vscode-documentdb/pull/565)
+
+### Dependencies
+
+- **Dependency Updates**: Bumps `handlebars` (4.7.8 → 4.7.9), `lodash` (4.17.23 → 4.18.1), `lodash` and `@microsoft/api-extractor` in `/api`, and `follow-redirects` (1.15.11 → 1.16.0). [#552](https://github.com/microsoft/vscode-documentdb/pull/552), [#556](https://github.com/microsoft/vscode-documentdb/pull/556), [#558](https://github.com/microsoft/vscode-documentdb/pull/558), [#586](https://github.com/microsoft/vscode-documentdb/pull/586)
+
 ## 0.7.3
 
 ### New Features

CONTRIBUTING.md

@@ -2,11 +2,12 @@
 
 Thank you for your interest in contributing to the **DocumentDB for VS Code** extension. This guide helps you set up your development environment and configure Visual Studio Code to effectively contribute to the extension.
 
-The document consists of three sections:
+The document consists of four sections:
 
 1. [Branching Strategy](#1-branching-strategy)
 2. [Machine Setup](#2-machine-setup)
 3. [VS Code Configuration](#3-vs-code-configuration)
+4. [PR Submission Checklist](#4-pr-submission-checklist)
 
 ## 1. Branching Strategy
 
@@ -22,12 +23,10 @@ The repository follows a structured branching strategy to ensure smooth developm
 GitHub Actions are configured to perform automated checks on the repository. The intensity of these checks depends on the target branch:
 
 1. **Push to `next`, `dev/*`, or `feature/*` branches**:
-
    - Runs basic code quality checks and tests.
    - Skips resource-intensive jobs like integration tests and packaging to focus on code validation.
 
 2. **Pull Requests to `main` or `next`**:
-
    - Executes all jobs, including code checks, tests, and packaging.
    - Ensures complete validation before merging, including artifact generation.
 
@@ -38,18 +37,21 @@ This setup ensures that contributions are thoroughly validated while optimizing
 
 ## 2. Machine Setup
 
-Follow these instructions to configure your machine for JavaScript/TypeScript development using Windows Subsystem for Linux (WSL2) and Visual Studio Code.
+> **Platform coverage:** The detailed setup instructions below are written for **Windows + WSL2**. Stub sections for [macOS](#22-macos-pending), [Windows (native)](#23-windows-native-pending), and [plain Linux](#24-linux-pending) are included but not yet filled in; Contributors on those platforms are warmly invited to submit a PR expanding those sections!
 
-> This setup assumes you're using WSL2 on Windows. However, you can use a Linux or Windows setup exclusively if preferred.
+---
 
-### 2.1. Install Ubuntu 22.\* on Windows
+### 2.1. Windows + WSL2 _(documented)_
 
-- Install **Ubuntu 22.\*** from the Microsoft Store and launch it to configure your Linux user account.
+Follow these instructions to configure your machine for JavaScript/TypeScript development using Windows Subsystem for Linux (WSL2) and Visual Studio Code.
+
+#### 2.1.1. Install Ubuntu 22.\* on Windows
 
+- Install **Ubuntu 22.\*** from the Microsoft Store and launch it to configure your Linux user account.
   - Your development environment and tools will reside within `WSL2`.
   - VS Code integrates seamlessly with `WSL2` instances, enabling smooth development from your Windows machine.
 
-### 2.2. Update Ubuntu Packages
+#### 2.1.2. Update Ubuntu Packages
 
 Open your Ubuntu terminal and run:
 
@@ -58,29 +60,48 @@ sudo apt update
 sudo apt upgrade
 ```
 
-### 2.3. Install Node.js with FNM (Fast Node Manager)
+#### 2.1.3. Install Node.js with FNM (Fast Node Manager)
+
+`FNM` helps with installing and switching Node.js versions easily. This is useful for testing compatibility across different Node.js versions.
 
-- `FNM` helps with installing and switching Node.js versions easily. This is useful for testing compatibility across different Node.js versions.
+The minimum required versions are **Node.js 22.18.0** and **npm 10.0.0** (see `engines` in `package.json`).
 
 Run the following commands:
 
 ```bash
 curl -fsSL https://fnm.vercel.app/install | bash
 source ~/.bashrc
-fnm install 22
-fnm use 22
-fnm default 22
-node --version
+fnm install 22.18.0
+fnm use 22.18.0
+fnm default 22.18.0
+node --version   # should print v22.18.0 or later
+npm --version    # should print 10.x or later
 ```
 
-### 2.4. Install TypeScript Globally (optional)
-
-You can install TypeScript globally:
+#### 2.1.4. Install TypeScript Globally (optional)
 
 ```bash
 npm install -g typescript
 ```
 
+---
+
+### 2.2. macOS _(pending)_
+
+> **Help wanted!** If you develop on macOS, please consider contributing setup instructions for this section. The general flow (install Node.js via a version manager such as `nvm` or `fnm`, clone the repo, `npm install && npm run build`) should be very similar to the WSL2 path above.
+
+---
+
+### 2.3. Windows (native) _(pending)_
+
+> **Help wanted!** If you develop on Windows without WSL2, please consider contributing setup instructions for this section.
+
+---
+
+### 2.4. Linux _(pending)_
+
+> **Help wanted!** If you develop on Linux natively, please consider contributing setup instructions for this section. The WSL2 Ubuntu steps above should translate almost verbatim.
+
 ## 3. VS Code Configuration
 
 This section explains how to clone the **DocumentDB for VS Code** repository and set up Visual Studio Code for development and debugging.
@@ -90,7 +111,6 @@ This section explains how to clone the **DocumentDB for VS Code** repository and
 1. Ensure you have completed the [Machine Setup](#2-machine-setup) steps.
 
 2. Fork or directly clone the official repository:
-
    - [DocumentDB for VS Code (vscode-documentdb)](https://github.com/microsoft/vscode-documentdb)
 
    - Open your **WSL2** terminal and clone the repository:
@@ -124,6 +144,59 @@ code .
    - Select `Launch Extension (webpack)`.
    - Press `F5`.
 
+## 4. PR Submission Checklist
+
+Before opening or marking a pull request as ready for review, **all of the following steps must pass locally**. The same checks run in CI, so catching failures locally saves time.
+
+### 4.1. Localization
+
+If you added, changed, or removed any user-facing string (anything passed to `vscode.l10n.t()`), regenerate the localization bundle:
+
+```bash
+npm run l10n
+```
+
+Commit any changes to the `l10n/` folder together with your code changes.
+
+### 4.2. Formatting
+
+Run Prettier to ensure all files meet the project's formatting standards:
+
+```bash
+npm run prettier-fix
+```
+
+Commit any files that Prettier reformats.
+
+### 4.3. Linting
+
+Run ESLint and fix all reported issues before submitting:
+
+```bash
+npm run lint
+```
+
+### 4.4. Package Verification
+
+Verify the extension can be packaged successfully without errors:
+
+```bash
+npm run package
+```
+
+This step catches webpack bundling issues and missing assets that unit tests alone won't surface.
+
+---
+
+> **Summary — run these four commands before every PR:**
+>
+> ```bash
+> npm run l10n
+> npm run prettier-fix
+> npm run lint
+> npm run package
+> ```
+
 ## You're Ready to Contribute! 🎉
 
 You've now successfully set up your development environment and are ready to contribute to **DocumentDB for VS Code**. We appreciate your contributions!