SAMPLE_GUIDELINE.md

Sample Guideline

Each sample should have the following components and structure, so that users could have a smooth experience when playing with different samples. The quickest way is to start your project by copying .base-sample.

1: Sample Listing

• 1.1: Each sample should add itself to the sample listing at .scripts/samples.js. This file will be used for generating tables in the README and on the Extension Guides / Overview topic of the website.
• 1.2: Each sample should list the API / Contribution that it means to illustrate.

2: README

• 2.1: Each README should start with a short sentence / paragraph that describes what the extensions is and what it is meant to illustrate.
• 2.2: If the sample has a corresponding guide, it should link to the guide.
• 2.3: If the illustrated functionality is visual, a gif/image should follow the explanation. (File should be demo.png/gif/jpg. Use default Dark+/Light+ theme)
• 2.4: A VS Code API section listing the illustrated API, Contribution Points and Activation Events.
• 2.5: A Running the Sample section should describe the actions to run the sample.

3: .vscode

• 3.1: launch.json: use 0.2.0 version.
• 3.2: settings.json: use "editor.insertSpaces": false. This ensures when user opens the subfolder, tab indentation is enforced.

4: Dependencies

• 4.1: Use npm's package-lock.json instead of yarn.lock.
• 4.2: devDependencies should include @types/node, @types/vscode, @typescript-eslint/eslint-plugin, @typescript-eslint/parser, eslint, and typescript.

5: Formatter and Linter

Only deviate from the standard setting if your sample needs to.

• 5.1: Include a .eslintrc.js following https://github.com/microsoft/vscode-extension-samples/blob/main/helloworld-sample/.eslintrc.js.
• 5.2: Include a tsconfig.json following https://github.com/microsoft/vscode-extension-samples/blob/main/helloworld-sample/tsconfig.json.
• 5.3: Your source code should be formatted either using tsfmt or the editor's TS formatter and contain no ESLint/TS errors.

6: Tests

• 6.1: If your extension does not have meaningful tests, remove the src/test folder.
• 6.2: If your extension can be meaningfully tested, include a sample test. If you have an associated guide, explain the test in the guide.