Merge pull request #33 from microsoft/bamurtaugh/nes

NES docs

Author: ntrogh

docs/copilot/ai-powered-suggestions.md

@@ -12,6 +12,23 @@ MetaSocialImage: images/shared/github-copilot-social.png
 
 GitHub Copilot acts as an AI-powered pair programmer, automatically offering suggestions to complete your code, comments, tests, and more. It provides these suggestions directly in the editor while you write your code, and it can work with a broad range of programming languages and frameworks.
 
+Copilot provides two kinds of suggestions:
+* **Code completions** - Start typing in the editor, and Copilot provides code suggestions that match your coding style and take your existing code into account.
+* **Next Edit Suggestions (preview)** - Predict your next code edit with Copilot Next Edit Suggestions, aka Copilot NES. Based on the edits you're making, NES both predicts the location of the next edit you'll want to make and what that edit should be.
+
+## Getting started
+
+1. Install the GitHub Copilot extensions.
+
+    > <a class="install-extension-btn" href="vscode:extension/GitHub.copilot?referrer=docs-copilot-ai-powered-suggestions">Install the GitHub Copilot extensions</a>
+
+1. Sign in with your GitHub account to use Copilot.
+
+    > [!TIP]
+    > If you don't yet have a Copilot subscription, you can use Copilot for free by signing up for the [Copilot Free plan](https://github.com/github-copilot/signup) and get a monthly limit of completions and chat interactions.
+
+1. Discover the key features of Copilot in VS Code with our [Copilot Quickstart](/docs/copilot/getting-started.md).
+
 ## Inline suggestions
 
 Copilot offers code suggestions as you type: sometimes the completion of the current line, sometimes a whole new block of code. You can accept all, or part of a suggestion, or you can keep typing and ignore the suggestions.
@@ -44,7 +61,85 @@ The following example shows how to instruct Copilot to create a class in TypeScr
 
 ![Use code comments to let Copilot generate a Student class in TypeScript with properties and methods.](images/inline-suggestions/ts-suggest-code-comment.png)
 
-## Enable or disable inline suggestions
+## Next Edit Suggestions (preview)
+
+Inline suggestions are great at autocompleting a section of code. But since most coding activity is editing existing code, it's a natural evolution of Copilot code completions to also help with edits, both at the cursor and further away. Edits are often not made in isolation - there's a logical flow of what edits need to be made in different scenarios. Copilot Next Edit Suggestions (aka "Copilot NES") is this evolution.
+
+<video src="./images/inline-suggestions/nes-video.mp4" title="Copilot NES video" controls poster="./images/inline-suggestions/point3d.png"></video>
+
+Based on the edits you're making, Copilot NES both predicts the location of the next edit you'll want to make and what that edit should be. NES helps you stay in the flow, suggesting future changes relevant to your current work, and you can simply `kbstyle(Tab)` to quickly navigate and accept Copilot's suggestions. Suggestions may span a single symbol, an entire line, or multiple lines, depending on the scope of the potential change.
+
+### Enabling edit suggestions
+
+Copilot NES is currently in preview. You can enable NES via the VS Code setting `setting(github.copilot.nextEditSuggestions.enabled)`, using the following steps:
+* Open the VS Code Settings editor (`kb(workbench.action.openSettings)`)
+* Search for `setting(github.copilot.nextEditSuggestions.enabled)`
+* Enable the setting
+
+If you are a Copilot Business or Enterprise user, an administrator of your organization must opt in to the use of Copilot editor preview features, in addition to you setting `setting(github.copilot.nextEditSuggestions.enabled)` in your editor.
+
+You can learn more about [managing policies for Copilot in your organization](https://docs.github.com/en/copilot/managing-copilot/managing-github-copilot-in-your-organization/managing-policies-for-copilot-in-your-organization#enabling-copilot-features-in-your-organization).
+
+### Navigate and accept edit suggestions
+
+You can quickly navigate suggested code changes with the `kbstyle(Tab)` key, saving you time to find the next relevant edit (no manual searching through files or references required). You can then accept a suggestion with the `kbstyle(Tab)` key again.
+
+An arrow in the gutter indicates if there is an edit suggestion available. You can hover over the arrow to explore the edit suggestion menu, which includes keyboard shortcuts and settings configuration:
+![NES gutter menu expanded](./images/inline-suggestions/gutter-menu-highlighted-updated.png)
+
+If an edit suggestion is below the current editor view, the arrow will point down instead of right:
+![NES with arrow directions changing](./images/inline-suggestions/nes-arrow-directions.gif)
+<!-- ![NES with right arrow](./images/inline-suggestions/scan-right-highlight.png) -->
+<!-- ![NES with down arrow](./images/inline-suggestions/scan-down-highlight.png) -->
+
+### Use cases for Next Edit Suggestions
+
+**Catching and correcting mistakes**
+
+* **Copilot helps with simple mistakes like typos.** It'll suggest fixes where letters are missing or swapped, like `cont x = 5` or `conts x = 5`, which should've been `const x = 5`.
+![NES fixing a typo from "conts" to "const"](./images/inline-suggestions/nes-typo.gif)
+* **Copilot can also help with more challenging mistakes in logic**, like an inverted ternary expression:
+![NES fixing a fibonacci logic mistake](./images/inline-suggestions/nes-fib-logic.gif)
+Or a comparison that should've used `&&` instead of `||`:
+![NES fixing an if statement mistake](./images/inline-suggestions/nes-de-morgan.gif)
+
+**Changing intent**
+
+* **Copilot suggests changes to the rest of your code that match a new change in intent.** For example, when changing a class from `Point` to `Point3D`, Copilot will suggest to add a `z` variable to the class definition. After accepting the change, NES next recommends adding `z` to the distance calculation:
+![NES gif for updating Point to Point3D](./images/inline-suggestions/nes-point.gif)
+<!-- ![NES for updating Point to Point3D](./images/inline-suggestions/point3d.png)
+![NES for adding z to distance calculation of Point3D](./images/inline-suggestions/point3d-distance.png) -->
+
+**Adding new variables or logic**
+
+* **Using newly added arguments, variables, or functions**. Copilot helps you use new code you just added. This may be a small change, like calling a new method parameter in the actual method.
+
+It could also be more complex: if you added a new command to your VS Code extension's `extension.ts`, Copilot will first suggest to clean up the command in `extension.ts`. Then when you open `package.json`, Copilot suggests registering that command as well:
+![Updating extension.ts and package.json with a new command](./images/inline-suggestions/nes-extension-and-package.gif)
+<!-- ![Add command in package.json](./images/inline-suggestions/add-disposable.png)
+![Add command in package.json](./images/inline-suggestions/call-disposable-full.png) -->
+
+**Refactoring**
+
+* **Rename a variable once in a file, and Copilot will suggest to update it everywhere else.** If you use a new name or naming pattern, Copilot suggests to update subsequent code similarly.
+![NES suggesting change after updating function name](./images/inline-suggestions/nes-gutter.gif)
+* **Matching code style**. After copy-pasting some code, Copilot will suggest how to adjust it to match the current code where the paste happened.
+
+### Further configuring edit suggestions
+
+You use Copilot NES, you must set `setting(github.copilot.nextEditSuggestions.enabled)`. There are a couple of additional settings you can also use to configure your NES experience:
+* `setting(editor.inlineSuggest.edits.codeShifting)`: You can disable this setting if you never want NES to shift your code to show a suggestion.
+* `setting(editor.inlineSuggest.edits.renderSideBySide)`:
+     * **auto (default)**: Show larger suggestions side-by-side if there is enough space in the viewport, otherwise the suggestions is shown below the relevant code.
+     * **never**: Always show larger suggestions below the relevant code.
+
+## Tips & tricks
+
+### Context
+
+To give you relevant inline suggestions, Copilot looks at the current and open files in your editor to analyze the context and create appropriate suggestions. Having related files open in VS Code while using Copilot helps set this context and lets Copilot get a bigger picture of your project.
+
+### Enable or disable code completions
 
 You can temporarily enable or disable code completions either for all languages, or for specific languages only.
 
@@ -61,12 +156,6 @@ You can temporarily enable or disable code completions either for all languages,
 
     ![Screenshot showing the VS Code command menu for Copilot, highlighting the options to disable completions.](./images/inline-suggestions/copilot-disable-completions.png)
 
-## Tips & tricks
-
-### Context
-
-To give you relevant inline suggestions, Copilot looks at the current and open files in your editor to analyze the context and create appropriate suggestions. Having related files open in VS Code while using Copilot helps set this context and lets the Copilot see a bigger picture of your project.
-
 ### Settings
 
 * `setting(editor.inlineSuggest.enabled)` - enable or disable inline completions.
@@ -77,6 +166,12 @@ To give you relevant inline suggestions, Copilot looks at the current and open f
 
 * `setting(editor.inlineSuggest.syntaxHighlightingEnabled)` - enable or disable syntax highlighting for inline completions.
 
+* `setting(github.copilot.nextEditSuggestions.enabled)` - enable Copilot Next Edit Suggestions (Copilot NES).
+
+* `setting(editor.inlineSuggest.edits.codeShifting)` - configure if NES is able to shift your code to show a suggestion.
+
+* `setting(editor.inlineSuggest.edits.renderSideBySide)` - configure if NES can show larger suggestions side-by-side if possible, or if NES should always show larger suggestions below the relevant code.
+
 ## Next steps
 
 * Get started with the introductory [Copilot tutorial](/docs/copilot/getting-started-chat.md) to get set up with Copilot in VS Code and experience Copilot hands-on.

docs/copilot/copilot-settings.md

@@ -26,6 +26,9 @@ The team is continuously working on improving Copilot in VS Code and adding new
 * `setting(chat.commandCenter.enabled)` <i class="codicon codicon-beaker"></i>: Controls whether the command center shows a menu for chat actions.
 * `setting(workbench.commandPalette.experimental.askChatLocation)` <i class="codicon codicon-beaker"></i>: Controls where the Command Palette should ask chat questions.
 * `setting(github.copilot.chat.search.semanticTextResults)` <i class="codicon codicon-beaker"></i>: Enables semantic search results in the Search view.
+* `setting(github.copilot.nextEditSuggestions.enabled)` <i class="codicon codicon-beaker"></i>: Enables Copilot Next Edit Suggestions (preview, aka "Copilot NES").
+* `setting(editor.inlineSuggest.edits.codeShifting)` <i class="codicon codicon-beaker"></i>: Configure if NES is able to shift your code to show a suggestion.
+* `setting(editor.inlineSuggest.edits.renderSideBySide)` <i class="codicon codicon-beaker"></i>: Configure if NES can show larger suggestions side-by-side if possible, or if NES should always show larger suggestions below the relevant code.
 
 ## Chat settings
 

docs/copilot/copilot-vscode-features.md

@@ -114,6 +114,7 @@ As you're coding in the editor, you can use Copilot to generate code completions
 | Action | Description |
 |--------|-------------|
 | Code completions | Start typing in the editor and Copilot provides code suggestions that match your coding style and take your existing code into account. |
+| Next Edit Suggestions (preview) | Predict your next code edit with Copilot Next Edit Suggestions, aka Copilot NES. Based on the edits you're making, NES both predicts the location of the next edit you'll want to make and what that edit should be. You can enable NES via the VS Code setting `setting(github.copilot.nextEditSuggestions.enabled)`. |
 | Code comments | Provide a code completion prompt to Copilot by writing instructions in a code comment.<br/>Example: `# write a calculator class with methods for add, subtract, and multiply. Use static methods.` |
 | `kb(inlinechat.start)` | Start **Inline Chat** to send a chat request to Copilot directly from the editor. Use natural language or use `/` commands to give instructions to Copilot. |
 | Prompt from the editor <i class="codicon codicon-beaker"></i> | Start typing natural language directly in code and Copilot detects that you're not writing code but prompting, and will automatically start Inline Chat for your prompt. |