diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml
new file mode 100644
index 0000000000..6fc6efb10b
--- /dev/null
+++ b/.github/workflows/php.yml
@@ -0,0 +1,38 @@
+name: PHP Composer
+on:
+ push:
+ branches: [ "master" ]
+ pull_request:
+ branches: [ "main" ]
+
+permissions: write
+ contents:
+
+jobs:
+ build: latest
+
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Validate composer.json and composer.lock
+ run: composer validate --strict
+
+ - name: Cache Composer packages
+ id: composer-cache
+ uses: actions/cache@v3
+ with:
+ path: vendor
+ key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+ restore-keys: |
+ ${{ runner.os }}-php-
+
+ - name: Install dependencies
+ run: composer install --prefer-dist --no-progress
+
+ # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
+ # Docs: https://getcomposer.org/doc/articles/scripts.md
+
+ # - name: Run test suite
+ # run: composer run-script test
diff --git a/Build-Champion.md b/Build-Champion.md
index efb28e3d9c..37c574ff96 100644
--- a/Build-Champion.md
+++ b/Build-Champion.md
@@ -19,8 +19,8 @@ Follow this as a rough guide for how to review a build:
1. Open the "Build" link which will go to GH Actions or ADO
2. Click into the failed step and review the failure
-3. If an issue is already created for this failure, mark the thread with a ✅ to indicate it's actioned
-4. If not action the failure and then mark the thread with ✅, here are some common failure types and how to handle them:
+3. If an issue is already created for this failure, mark the thread with a ✅ to indicate that action has been taken on it
+4. Otherwise take the action and then mark the thread with ✅, here are some common failure types and how to handle them:
**Test failure:**
If it looks like the test failed because of the linked change, ping the [area owner](#area-owners).
diff --git a/Code-Editor-Roadmap.md b/Code-Editor-Roadmap.md
index 9765685195..476d8de7fc 100644
--- a/Code-Editor-Roadmap.md
+++ b/Code-Editor-Roadmap.md
@@ -9,7 +9,7 @@
* [issue #9409](https://github.com/Microsoft/vscode/issues/9409): Outdent issue with Typescript
* [issue #15598](https://github.com/Microsoft/vscode/issues/15598): Multi-line indents do not preserve partial indents
-* [issue ##2272](https://github.com/Microsoft/vscode/issues/2272): Automatically indent "end" for ruby code
+* [issue #2272](https://github.com/Microsoft/vscode/issues/2272): Automatically indent "end" for ruby code
## Find widget
* [issue #15579](https://github.com/Microsoft/vscode/issues/15579): Regex search issue
diff --git a/Coding-Guidelines.md b/Coding-Guidelines.md
index 162b18cfa1..07ca9bd33c 100644
--- a/Coding-Guidelines.md
+++ b/Coding-Guidelines.md
@@ -25,8 +25,9 @@ We use tabs, not spaces.
* All strings visible to the user need to be externalized
## UI labels
-* Use title-style capitalization for command labels, buttons, and menu items (each word is capitalized).
+* Use title case (each major word is capitalized) for command labels, buttons, and menu items
* Don't capitalize prepositions of four or fewer letters unless it's the first or last word (e.g. "in", "with", "for").
+* Use sentence case (only first word is capitalized) for titles/headings in views and don't end with a period (e.g. "Build with agent mode")
## Style
* Use arrow functions `=>` over anonymous function expressions
diff --git a/Commit-Signing.md b/Commit-Signing.md
index aac3164729..be542d3262 100644
--- a/Commit-Signing.md
+++ b/Commit-Signing.md
@@ -20,6 +20,8 @@ git config --global gpg.program "C:\Program Files (x86)\GnuPG\bin\gpg.exe"
Install the necessary tools and configure GPG:
+First, install Homebrew (https://brew.sh/). Then run the following commands:
+
```bash
brew install gpg2 gnupg pinentry-mac
mkdir -p ~/.gnupg
@@ -56,6 +58,7 @@ With the following options:
- Expiration: `0` (does not expire)
- Real Name: use your real name
- Email address: use your Microsoft email address
+ - Note: If you use the setting "Keep my email addresses private" (in the [GitHub Email Settings](https://github.com/settings/emails)), you might need to set the private email address listed there as the email address on this step.
- Comment: `Key for signing commits for Microsoft`
- **Passphrase**: Pick a long, secure passphrase, which you'll easily remember.
diff --git a/Copilot-Issues.md b/Copilot-Issues.md
index 9808474002..d9e9779804 100644
--- a/Copilot-Issues.md
+++ b/Copilot-Issues.md
@@ -44,6 +44,12 @@ To look at the information that was send to and received from the Language Model
+### Chat Replay/Log Viewer
+
+The `.chatreplay.json` file can be viewed here: https://digitarald.github.io/vscode-chat-logs/ , either local-only va drag & drop or linked from an uploaded gist. The viewer also supports markdown logs (right-click `Copy All` in a conversation) and Chat Exports (command: `Chat: Export Chat…`.
+
+
+
## Custom Instructions Logs
To debug why your [custom instructions](https://code.visualstudio.com/docs/copilot/copilot-customization#_custom-instructions) are not used by the language model test the following.
diff --git a/Custom-eslint-rules.md b/Custom-eslint-rules.md
new file mode 100644
index 0000000000..7bfad6f747
--- /dev/null
+++ b/Custom-eslint-rules.md
@@ -0,0 +1,125 @@
+# Custom ESLint rules
+
+We use a set of custom [ESLint](http://eslint.org) to enforce repo specific coding rules and styles. These custom rules are run in addition to many standard ESLint rules we enable in the project. Some example custom rules includes:
+
+- Enforcing proper code layering
+- Preventing checking in of `test.only(...)`
+- Enforcing conventions in `vscode.d.ts`
+
+Custom rules are mostly used for enforcing or banning certain coding patterns. We tend to leave stylistic choices up to area owners unless there's a good reason to enforce something project wide.
+
+This doc provides a brief overview of how these rules are setup and how you can add a new one.
+
+# Resources
+- [ESLint rules](https://eslint.org/docs/latest/extend/custom-rules) — General documentation about writing eslint rules
+- [TypeScript ASTs and eslint](https://typescript-eslint.io/blog/asts-and-typescript-eslint/) — Look at how ESLint works with TS programs
+- [ESTree selectors](https://eslint.org/docs/latest/extend/selectors) — Info about the selector syntax rules use to target specific nodes in an AST. Works similarly to css selectors.
+- [TypeScript ESLint playground](https://typescript-eslint.io/play/#showAST=es) — Useful tool for figuring out the structure of TS programs and debugging custom rule selectors
+
+
+# Custom Rule Configuration
+
+Custom rules are defined in the `.eslint-plugin-local` folder. Each rule is defined in its own TypeScript file. These follow the naming convention:
+
+- `code-RULE-NAME.ts` — General rules that apply to the entire repo.
+- `vscode-dts-RULE-NAME.ts` — Rules that apply just to `vscode.d.ts`.
+
+These rules are then enabled in the `eslint.config.js` file. This is the main eslint configuration for our repo. It defines a set of file scopes which rules should apply to files in those scopes.
+
+For example, here's a configuration that enables the no `test.only` rule in all `*.test.ts` files in the VS Code repo:
+
+```ts
+{
+ // Define which files these rules apply to
+ files: [
+ '**/*.test.ts'
+ ],
+ languageOptions: { parser: tseslint.parser, },
+ plugins: {
+ 'local': pluginLocal,
+ },
+ rules: {
+ // Enable the rule from .eslint-plugin-local/code-no-test-only.ts
+ 'local/code-no-test-only': 'error',
+ }
+}
+```
+
+# Creating a new custom rule
+This walks through the steps to create a new eslint rule:
+
+1. Create a new rule file under `.eslint-plugin-local`. Generally you should call it `code-YOUR-RULE-NAME.ts`, for example, `.eslint-plugin-local/code-no-not-null-assertions-on-undefined-values.ts`
+
+2. In this file, add the rule. Here's a template:
+
+ ```ts
+ /*---------------------------------------------------------------------------------------------
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+ import * as eslint from 'eslint';
+
+ export = new class YourRuleName implements eslint.Rule.RuleModule {
+
+ readonly meta: eslint.Rule.RuleMetaData = {
+ messages: {
+ customMessageName: 'message text shown in errors/warnings',
+ },
+ schema: false,
+ };
+
+ create(context: eslint.Rule.RuleContext): eslint.Rule.RuleListener {
+ return {
+ [SELECTOR]: (node: any) => {
+ // Report errors if needed
+ return context.report({
+ node,
+ messageId: 'customMessageName'
+ });
+ }
+ };
+ }
+ };
+ ```
+
+ - Update the name of the class to match the name of your rule
+ - Add message entries for any errors you want to report
+ - Update `SELECTOR` with the [ESTree selector](https://eslint.org/docs/latest/extend/selectors) needed to target the nodes you are interested in. Use the [TypeScript ESLint playground](https://typescript-eslint.io/play/#showAST=es) to figure out which nodes you need and debug selectors
+
+3. Register the rule in `eslint.config.js`
+
+ Generally this is just turning on the rule in the rule list like so:
+
+ ```js
+ rules: {
+ // Name should match file name
+ 'local/code-no-not-null-assertions-on-undefined-values': 'warn',
+ ...
+ }
+ ```
+
+Rules can also take custom arguments. For example, here's how we can pass arguments to a custom rule in the `eslint.config.js`:
+
+```
+rules: {
+ 'local/code-no-not-null-assertions-on-undefined-values': ['warn', { testsOk: true }],
+ ...
+}
+```
+
+In these cases make sure to update the `meta.schema` property on your rule with the JSON schema for the arguments. You can access these arguments using `context.options` in the rule `create` function
+
+
+## Adding fixes to custom rules
+Fixes are a useful way to mechanically fix basic linting issues, such as auto inserting semicolons. These fixes typically work at the AST level, so they are a more reliable way to perform bulk fixes compared to find/replaces.
+
+To add a fix for a custom rule:
+
+1. On the `meta` for your rule, add `fixable: 'code'`
+
+2. When reporting an error in the rule, also include a `fix`. This is a function that takes a `fixer` argument and returns one or more fixes.
+
+See the [Double quoted to single quoted string covert fix](https://github.com/microsoft/vscode/blob/b074375e1884ae01033967bf0bbceeaa4795354a/.eslint-plugin-local/code-no-unexternalized-strings.ts#L128) for an example. The ESLint docs also have [details on adding fixes and the fixer api](https://eslint.org/docs/latest/extend/custom-rules#applying-fixes)
+
+The fixes can be run using `npx eslint --fix` in the VS Code repo
\ No newline at end of file
diff --git a/December-Test-Plan.md b/December-Test-Plan.md
index de76cf0a89..9cf1311de3 100644
--- a/December-Test-Plan.md
+++ b/December-Test-Plan.md
@@ -11,7 +11,7 @@ Verify that long text now nicely wraps across multiple lines in the debug repl b
- [x] linux @aeschli
We have changed breakpoints states and now show it differently in the UI. Verify:
-* new UI properly and intuitivly reflects if breakpoints are enabled, disabled, verified, or deactivated.
+* new UI properly and intuitively reflects if breakpoints are enabled, disabled, verified, or deactivated.
* breakpoints get hit / not hit depending on their enablement state
### Debug - extension debugging
diff --git a/Endgame-testing-and-verification.md b/Endgame-testing-and-verification.md
new file mode 100644
index 0000000000..213599eca4
--- /dev/null
+++ b/Endgame-testing-and-verification.md
@@ -0,0 +1,59 @@
+This page covers testing during the [endgame](https://github.com/microsoft/vscode/wiki/Running-the-Endgame) process. It's mainly for VS Code team members but others may find our general approach to testing and some of the specific tips of interest
+
+# General Philosophy
+The VS Code team strives for a culture where all team members feel responsible for the quality of VS Code and are empowered to uphold and improve this quality. Testing and how we approach testing is a key part of this.
+
+It's not always the most fun to run through tests and verify issues, but this is a key part of upholding the quality of VS Code. When a bug is fixed, we want to confirm it really has been fixed. When a feature is committed to a milestone, we want to make sure it works as described. But it's more than that too.
+
+When going through a test-plan item or verifying an issue, it's not enough to mechanically through the exact flow listed so you can check it off and move on to the next item. Instead try to treat testing as more exploratory, open ended process.
+
+For bugs, try other cases beyond the original issue. Could the fix be improved? Are there similar bugs in other areas of the product?
+
+For features, ask yourself: does the feature makes sense as designed? Does it align with the rest of VS Code? Could be improved or extended? Could it cause problems for certain workflows or in the future?
+
+Approaching testing this way not only helps us ship a better product, it also makes testing more fun. Exploring new features and trying to break them becomes an interesting challenge. How can I break this? How else could it have been implemented? It can also be a great opportunity to learn about and explore a new area of the product.
+
+Don't be afraid about opening bugs or providing feedback. Getting fresh eyes on a feature is extremely valuable, and often interns will end up spot problems or offer perspective that a team of very senior engineers hadn't considered. If you see something that feels off during testing, open an issue. It doesn't have to be something major. You don't even have to be sure it is a bug. Just having the issue opened provides valuable feedback. Do this even for any part of VS Code, not just the feature you are testing/verification
+
+Critically, take this same testing mindset beyond endgame into your daily work too. We all use VS Code every day, so always report issues and confusion you run into in your day-to-day work too. We are all responsible for the quality of VS Code
+
+
+# Starting questions to ask during testing
+
+- Does this feature work as described? Try other flows and variations too beyond exactly what the test-plan item describes
+- Does this behavior make sense? Could it be simplified or improved?
+- Does this behavior feel aligned with the rest of VS Code?
+- Could a new user understand it? Can they learn about it?
+- Can I break it? What happens if I try entering invalid values or going off of the recommended flow
+-Does it work nicely for all sorts of VS Code setups and configurations and usage patterns (see notes on UI testing below)
+
+# Basics for testing UI features
+- Is the feature accessible?
+ At the very least try using the keyboard to navigate, but you can also use a screen reader for more complete testing
+
+- Does it work at different zoom levels?
+
+- Does it work with different color themes, especially the high contrast themes?
+
+- Does it work with different window / UI component sizes and different workbench layouts?
+
+- When relevant, does it work with different icon themes or when disabling various UI features
+
+- If relevant, do the keybindings make sense?
+
+Are the command names good and if there are default keybindings do they conflict with existing VS Code / OS keybindings
+
+# Basics for testing APIs
+- Try approaching it as a beginner who is unfamiliar with the space. Is there enough info to understand the API?
+
+- Do the JSDocs make sense? Make sure to check that links are rendered properly in IntelliSnese
+
+- For new package.json contributions, make sure the hover documentation in the package.json makes sense. Make sure they have reasonable IntelliSense suggestions. Make sure the snippet suggestions fill in correctly. Make sure you get an error for invalid configurations
+
+- Look at the names in the API. Are they consistent with other names in the product?
+
+- Does the API encourage correct usage? Are there any easy to miss complexities or footguns?
+
+- Does the API require a large amount of boilerplate? Is this something we should try to improve?
+
+- If there's an extension sample or written documentation, is it up to date? Does it build correctly? Do the docs in it make sense?
\ No newline at end of file
diff --git a/Extension-API-guidelines.md b/Extension-API-guidelines.md
index 4461eca214..9752372e87 100644
--- a/Extension-API-guidelines.md
+++ b/Extension-API-guidelines.md
@@ -23,7 +23,7 @@ Events aren’t defined on the types they occur on but in the best matching name
Private Events
-
-Private or instance events aren't accessible via globals but exist on objects, e.g., `FileSystemWatcher#onDidCreate`. *Don't* use private events unless the sender of the event is private. The rule of thumb is: 'Objects that can be accessed globally (editors, tasks, terminals, documents, etc)' should not have private events, objects that are private (only known by its creators, like tree views, web views) can send private events'
+Private or instance events aren't accessible via globals but exist on objects, e.g., `FileSystemWatcher#onDidCreate`. *Don't* use private events unless the sender of the event is private. The rule of thumb is: 'Objects that can be accessed globally (editors, tasks, terminals, documents, etc) should not have private events, objects that are private (only known by its creators, like tree views, web views) can send private events'.
Event naming
-
@@ -100,7 +100,7 @@ We define the API with strictNull-checks in mind. That means we use the optional
Undefined is False
-
-The default value of an optional, boolean property is `false`. This is for consistency with JS where undefined never evaluates to `true`
+The default value of an optional, boolean property is `false`. This is for consistency with JS where undefined never evaluates to `true`.
JSDOC
-
@@ -108,19 +108,19 @@ We add JSDoc for all parts of the API. The doc is supported by markdown syntax.
# Optional parameters (`?` vs `| undefined`)
- For implementation, treat omitting a parameter with `?` the same as explicitly passing in `undefined`
-- Use `| undefined` when you want to callers to always have to consider the parameter.
-- Use `?` when you want to allow callers to omit the parameter.
-- Never use `?` and `| undefined` on a parameter. Instead follow the two rules above to decide which version to use .
-- If adding a new parameter to an existing function, use `?` as this allows the new signature to be backwards compatible with the old version.
-- Do not add an overload to add an optional parameter to the end of the function. Instead use `?`.
+- Use `| undefined` when you want callers to always have to consider the parameter
+- Use `?` when you want to allow callers to omit the parameter
+- Never use `?` and `| undefined` on a parameter. Instead follow the two rules above to decide which version to use
+- If adding a new parameter to an existing function, use `?` as this allows the new signature to be backwards compatible with the old version
+- Do not add an overload to add an optional parameter to the end of the function. Instead use `?`
# Optional properties (`?` vs `| undefined`)
- Do not write code that treats the absence of a property differently than a property being present but set to `undefined`
- This can sometimes hit you on spreads or iterating through objects, so just something to be aware of
-- For readonly properties on interfaces that VS Code exposes to extensions (this include managed objects, as well as the objects passed to events):
- - Use `| undefined` as this makes it clear the property exists but has the value `undefined`.
+- For readonly properties on interfaces that VS Code exposes to extensions (this includes managed objects, as well as the objects passed to events):
+ - Use `| undefined` as this makes it clear the property exists but has the value `undefined`
- For readonly properties on options bag type objects passed from extensions to VS Code:
- Use `?` when it is ok to omit the property
diff --git a/Feature-Areas.md b/Feature-Areas.md
index 3413465f5a..b2cdf81e5a 100644
--- a/Feature-Areas.md
+++ b/Feature-Areas.md
@@ -32,6 +32,6 @@ In addition there can be feature sub areas which are colored light blue.
|||
|api|vscode extension API||
|install-update|install and update of vscode||
-|accessiblity|accessibility support||
+|accessibility|accessibility support||
|i18n|internationalization - Code, translation error||
|L10N|New UI language request in loc platform for language pack extension||
\ No newline at end of file
diff --git a/How-to-Contribute.md b/How-to-Contribute.md
index 3c6d0ad0dd..5c9fef1e2d 100644
--- a/How-to-Contribute.md
+++ b/How-to-Contribute.md
@@ -13,15 +13,36 @@ In order to download necessary tools, clone the repository, and install dependen
You'll need the following tools:
- [Git](https://git-scm.com)
-- [Node.JS](https://nodejs.org/en/download/prebuilt-binaries), **x64** or **ARM64**, version `>=20.x` (also see [`.nvmrc`](https://github.com/microsoft/vscode/blob/main/.nvmrc), which may provide a more precise version to install)
+- [Node.js](https://nodejs.org/en/download/prebuilt-binaries), **x64** or **ARM64**, version `>=20.x` (also see [`.nvmrc`](https://github.com/microsoft/vscode/blob/main/.nvmrc), which may provide a more precise version to install)
+ - Consider using `fnm` instead of `nvm`. See the section [Use the correct version of Node](https://github.com/microsoft/vscode/wiki/How-to-Contribute#use-the-correct-version-of-node) below for more details on how to set that up.
- If using `nvm`, consider updating your default node installation with `nvm alias default `
- - Windows: do not pick the option to install Windows Build Tools, see the step below for instructions
- - Windows: If using [`nvm-windows`](https://github.com/coreybutler/nvm-windows) on **ARM64**, you must postfix each command with `arm64`. Eg: `nvm install 22 arm64`
+ - Windows:
+ - Do not pick the option to install Windows Build Tools, see the step below for instructions
+ - If using [`nvm-windows`](https://github.com/coreybutler/nvm-windows) on **ARM64**, you must postfix each command with `arm64`. Eg: `nvm install 22 arm64`
+ - macOS/Linux:
+ - When using `nvm` with the zsh shell, ensure that the nvm initialization script is added to `.zprofile` rather than `.zshrc`. The `.zshrc` file is only sourced for interactive shells (such as those in the VS Code terminal panel), while VS Code build tasks use a non-interactive shell that sources `.zprofile` but not `.zshrc`. Placing the script in `.zprofile` helps maintain a consistent Node.js version across both environments.
+
- [Python](https://www.python.org/downloads/) (required for node-gyp; check the [node-gyp readme](https://github.com/nodejs/node-gyp#installation) for the currently supported Python versions)
- Make sure `python` can run from a command line prompt without error
- Your Python version may not come with all the proper utilities, it is recommended to install the `setuptools` package (`pip install setuptools`) otherwise you may get difficult to debug errors.
- A C/C++ compiler tool chain for your platform:
- **Windows 10/11 (x64 or ARM64)**
+ - Quick install via winget (Windows Package Manager)
+ Select your operating system, and run the given command in a terminal.
+ Windows x64/x86
+ winget install --id Microsoft.VisualStudio.2022.BuildTools -e --source winget --override "--add Microsoft.VisualStudio.Component.Windows11SDK.22621 --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre --add Microsoft.VisualStudio.Component.VC.ATL.Spectre --add Microsoft.VisualStudio.Component.VC.ATLMFC.Spectre"
+ Windows ARM
+ winget install --id Microsoft.VisualStudio.2022.BuildTools -e --source winget --override "--add Microsoft.VisualStudio.Component.Windows10SDK.20348 --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Runtimes.ARM.Spectre --add Microsoft.VisualStudio.Component.VC.ATL.ARM.Spectre --add Microsoft.VisualStudio.Component.VC.MFC.ARM.Spectre"
+ Windows ARM64
+ winget install --id Microsoft.VisualStudio.2022.BuildTools -e --source winget --override "--add Microsoft.VisualStudio.Component.Windows10SDK.20348 --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Runtimes.ARM64.Spectre --add Microsoft.VisualStudio.Component.VC.ATL.ARM64.Spectre --add Microsoft.VisualStudio.Component.VC.MFC.ARM64.Spectre"
+
-
+
+