Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
239 lines (178 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

239 lines (178 loc) · 10.7 KB

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 pnpm install. 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

This project uses a monorepo structure with pnpm workspaces. Each package is independent with its own package.json, build system, and tests.

Main packages

  • client: VSCode extension code which has access to all VS Code Namespace API.
    • Built with Rspack
    • Contains the extension activation logic and VSCode integration
  • server: Language server running in a separate process.
    • Built with Rspack with code splitting for large dependencies
    • Handles AGLint integration, diagnostics, and language features
  • shared: Shared utilities used by both client and server packages.
    • Built with Rspack
    • Contains common types and utilities
  • syntaxes: TextMate grammars for syntax highlighting.
    • Converts YAML grammar to PList format for VSCode
    • Contains grammar tests and utilities

Supporting folders

  • test: Static test files and test workspaces.
  • tools: Build and utility scripts for the project.
  • bamboo-specs: CI/CD pipeline configurations.

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, otherwise the watch build will not stop when it encounters an error.

Creating a production build

To create a production build of the extension:

  1. Run pnpm build command to build packages.
  2. Run pnpm package command to package the extension into a .vsix file.
  3. 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 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 syntaxes/test/adblock. Ensure tests pass by running pnpm --filter @vscode-adblock-syntax/syntaxes 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).

Build commands

  • pnpm build - Build all packages recursively with minification enabled.

Package commands

  • pnpm package - Package the extension into a .vsix file in the out directory.
  • pnpm package:pre - Package the extension with the --pre-release flag for prerelease builds.

Package-level build commands

Each package can be built independently using pnpm workspace filters:

  • pnpm --filter @vscode-adblock-syntax/shared build - Build the shared package with Rspack.
  • pnpm --filter @vscode-adblock-syntax/client build - Build the client package with Rspack.
  • pnpm --filter @vscode-adblock-syntax/server build - Build the server package with Rspack (includes code splitting).
  • pnpm --filter @vscode-adblock-syntax/syntaxes build - Build the syntaxes package (converts grammar to PList format).

Note

Rspack builds are configured via rspack.config.ts files in each package. Production mode is enabled via NODE_ENV=production environment variable, which is set automatically by the root pnpm build command.

Utility commands

  • pnpm clean - Removes all generated files using the clean utility script.
  • pnpm increment - Increment the patch version number in the package.json file. Typically used by CI.

Linting & testing commands

  • pnpm lint - Run all linters recursively across all packages.
  • pnpm lint:code - Lint the code with ESLint.
  • pnpm lint:md - Lint the markdown files with markdownlint.
  • pnpm test - Run tests recursively across all packages with Vitest.
  • pnpm test:compile - Type-check all packages without emitting files.

You can also run linting and tests for individual packages:

  • pnpm --filter @vscode-adblock-syntax/shared lint / test
  • pnpm --filter @vscode-adblock-syntax/client lint / test
  • pnpm --filter @vscode-adblock-syntax/server lint / test
  • pnpm --filter @vscode-adblock-syntax/syntaxes lint / test

Note

Watch builds are handled automatically by VSCode tasks when you start debugging (see .vscode/tasks.json file). Each package (shared, client, server, syntaxes) has its own watch task that rebuilds on file changes.

Note

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

Versioning policy

This project follows Semantic Versioning (SemVer) with specific requirements for VS Code extensions. See VS Code pre-release extensions documentation for more details.

VS Code extension versioning requirements

Important

VS Code Marketplace and Open VSX only support major.minor.patch format. Pre-release tags like 1.0.0-alpha or 1.0.0-beta are NOT supported and will be rejected by the stores.

Pre-release versioning strategy

To support pre-release versions while maintaining compatibility, we use an odd/even minor version scheme:

  • Release versions: major.EVEN.patch → e.g., 2.0.0, 2.0.1, 2.2.0
  • Pre-release versions: major.ODD.patch → e.g., 2.1.0, 2.1.1, 2.3.0

Version progression example:

2.0.0 → 2.1.0 (start pre-release)  → 2.1.1 (pre-release update)  → 2.2.0 (promote to release)

Warning

VS Code auto-updates to the highest version. Always ensure pre-release versions are higher than release versions to prevent downgrading pre-release users.

Useful links

Explore the following links for more information on development: