Skip to content

Latest commit

 

History

History
190 lines (153 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

190 lines (153 loc) · 10.3 KB
Raw

Contributing & Development Guide

Thank you for your interest in contributing to the VSCode Adblock Syntax project! This guide aims to provide essential information about the project and outlines steps to contribute effectively.

Contributors to AdGuard projects can receive various rewards; please check this page for details.

Table of Contents:

Prerequisites

Ensure that the following software is installed on your computer:

Initial setup

After cloning the repository, follow these steps to initialize the project:

  1. Install dependencies by calling yarn. This will also install client and server dependencies via postinstall scripts. After installation, it will initialize Husky Git hooks through the prepare script.
  2. Install recommended VSCode extensions (refer to the .vscode/extensions.json file). These extensions are REQUIRED for the development process.

Project structure

The most important folders in the project are:

  • client: VSCode extension code which has access to all VS Code Namespace API.
  • server: Language analysis tool running in a separate process.
  • syntaxes: TextMate grammars for syntax highlighting.
  • test: Various tests for the extension.
    • grammar: Unit tests for the TextMate grammar.
    • static: Static test files for testing the extension in development mode.
      • aglint: AGLint test project.
      • rules: Rules for testing the syntax highlighting visually.

Note

To learn more about the client-server architecture of VSCode extensions, refer to the VSCode Language Server Extension Guide.

Running the extension in development mode

If you've made changes to the extension code and want to test them, follow these steps:

  1. Open the project's root folder in VSCode.
  2. Select Run > Start Debugging menu item in VSCode (or just press the F5 key). This starts the watch build process in the background, opening a new VSCode window called "Extension Development Host" where you can test the extension.
  3. Watch build does not automatically update the extension in the "Extension Development Host" window. You'll need to reload the window manually by pressing Ctrl + R or selecting Developer: Reload Window command in the command palette (Ctrl + Shift + P).

Important

When you start the debugging, VSCode starts the watch build commands in separate terminals. To interpret the terminal output correctly, VSCode relies on problem matchers. Since ESBuild is not supported by VSCode by default, you need to install the ESBuild Problem Matchers extension to make able VSCode to parse its output. Without this extension, VSCode cannot recognize when ESBuild completes its build or encounters errors. This results in an endless run, preventing the opening of the Extension Development Host.

Creating a production build

To create a production build of the extension:

  1. Run yarn build:prod command. This generates a production build and a .vsix file in the out folder.
  2. To ensure the build is correct, install the generated .vsix file in VSCode. Open the command palette (Ctrl + Shift + P), select "Extensions: Install from VSIX...", and choose the vscode-adblock.vsix file.

Updating integrated AGLint

Note

This extension includes an integrated AGLint. It's a bundled version, avoiding the need for a separate AGLint installation. However, the extension can use an external AGLint version if installed by a package manager.

  1. Update AGLint in the server/package.json file. Alternatively, link the local AGLint repository if it hasn't been released on NPM.
  2. If there are breaking changes in the AGLint API, update the server code accordingly, changing the minimum supported AGLint version in server/index.ts (MIN_AGLINT_VERSION constant).
  3. Test the extension with the new AGLint version by running it in debug mode (see Running the extension in development mode section). In the "Extension Development Host" window, you should open the test project (see test/static folder) and check if the extension works as expected.
  4. If needed, update the test project (e.g., update the config file, add new example rules).

Updating syntax highlighting

  1. Update the TM grammar in the syntaxes/adblock.yaml-tmLanguage file.
  2. Create/modify example rules in the test/static/rules folder. Add link for GitHub issues to rules if related to some issue.
  3. Create/modify unit tests in test/grammar. Ensure tests pass by running yarn test.

Tip

Open the test/static folder in the "Extension Development Host" window and you can check the syntax highlighting visually. This is useful when you want to check how the highlighting works with specific rules.

Note

You can use the Online test page for TextMate grammars to test the TM grammars.

Available commands

During development, you can use the following commands (listed in package.json).

  • yarn build:grammar - Compiles the TextMate (TM) grammar into a PList format, since VSCode does not natively support YAML grammars.
  • yarn build:prod - Generates a production build of the extension, including a .vsix file in the out directory for VSCode installation.
  • yarn build:txt - Creates a build.txt file in the out directory containing the current version number, primarily for Continuous Integration (CI) purposes.
  • yarn build:vsix - Produces a .vsix file in the out directory, which is used to install the extension in VSCode.
  • yarn clean - Removes all generated files in the output directories, cleaning up the build results.
  • yarn esbuild:aglint - Base ESBuild command for building integrated AGLint with the common options.
  • yarn esbuild:agtree - Base ESBuild command for building integrated AGTree with the common options. Integrated AGTree comes with the integrated AGLint, this command just helps to bundle it to a separate file. This is needed because AGTree is also used by the server, and by bundling it to a separate file, we can avoid double-bundling AGTree.
  • yarn esbuild:server - Base ESBuild command for building the server with the common options.
  • yarn esbuild:client - Base ESBuild command for building the client with the common options.
  • yarn extract-changelog - Extract changes from the CHANGELOG.md for a specific version. Typically, this is used by CI.
  • yarn increment - Increment the patch version number of the extension in the package.json file. Typically, this is used by CI.
  • yarn lint:md - Lint the markdown files with markdownlint.
  • yarn lint:staged - Run linters on staged files. Typically, this is used by Husky Git hooks.
  • yarn lint:ts - Lint the code with ESLint.
  • yarn lint - Run all linters.
  • yarn test:compile - Check if the code compiles with TypeScript.
  • yarn test - Run tests with Jest.
  • yarn watch:aglint - Watch for changes in the AGLint code and create a development build automatically.
  • yarn watch:agtree - Watch for changes in the AGTree code and create a development build automatically.
  • yarn watch:client - Watch for changes in the client code and create a development build automatically.
  • yarn watch:grammar - Watch for changes in the TM grammar and rebuild it automatically.
  • yarn watch:server - Watch for changes in the server code and create a development build automatically.

Note

Watch commands (e.g., yarn watch:client) are typically used by VSCode tasks (see .vscode/tasks.json file and Running the extension in development mode section). In most cases, you don't need to run them manually.

Note

Linting and testing commands are called automatically by Husky Git hooks and CI. You can run them manually if needed.

Useful links

Explore the following links for more information on development: