How to Contribute

First things first: Get familiar with the codebase, principles, and architecture

Read the wiki pages

• Codebase Overview
• Codebase Principles and Styleguide
• Architecture and Libraries
• Testing

Development Environment

Operating System

All of the options below should work:

• Windows
• Ubuntu
• Mac OS (with or without Apple Silicon CPU)
• WSL2 Ubuntu (with WSLg support)

Prerequisites

• Follow the "Prerequisites" installation guide of microsoft/vscode/wiki/How-to-Contribute#prerequisites.

  • For the NodeJS version to use, please refer to the file .nvmrc file of this project. This is the version of NodeJS the project should be developed with.
    It is recommended to use nvm and run nvm use, this will automatically switch to the NodeJS version mentioned in .nvmrc.

• This monorepo uses pnpm as package manager.
  For installation instructions see pnpm.io/installation; it should boil down to this command:

  npm i -g pnpm

• Docker and Docker-Compose are required in order to run the Visual Regression Tests. See code.visualstudio.com/docs/remote/containers#_system-requirements for a list of options you can choose from.

IDE

It is recommended to install plugins for the following libraries/technologies:

• ESLint
• Prettier
• Styled-Components
• React/JSX

It is recommended to enable ESLint autofix and Prettier format "on save" for the IDE in use.
Prettier, and the ESLint rules related to codestyle, will then automatically format&structure the code on save.

Setup, Run, Build

Setup

pnpm install

Run

Development mode of the Electron app:

# compile & watch (i.e. automatic reload on file changes)
pnpm run start

Electron applications have 2 processes (some have even more!): the "main" process and the "renderer" process. You can read more about that in the section "Process Model" of the Electron documentation.
One thing you should know is that the watcher of pnpm run start does only reload the renderer process on file changes. So if you are working on stuff happening in the main process (should be the exception, e.g. window handling or some IPC handler), then you can type rs in the terminal you started pnpm run start in.
This reloads the entire application.
Furthermore, you can reload just the UI using the shortcut CTRL+SHIFT+R.

Instead of running the Electron application, Storybook can be used for development.
This is useful for two reasons:

• you can render just parts of the application
• the UI is isolated from the actual system (in-memory file system instead of real file system, etc.)

pnpm run storybook

For fast feedback while doing large-scaled code changes (e.g. refactoring), you might want to not run the Electron app or Storybook but instead run the TypeScript compilation watcher only:

pnpm run compile:watch

Build

Create a packaged version of the application for the current OS:

pnpm run package

This will produce a directory "out" which contains the production build of the app.

Run tests

Unit Tests

pnpm run test:unit

Logic and Visual Regression Tests

First note that Logic Tests and Visual Regression Tests need the Storybook server running.

Depending on what should be accomplished, one of the following approaches should be taken:

• If you iterate on the application or on a Playwright test case, you should run the development version of storybook (pnpm run storybook) and run the tests with "update-snapshots" activated (pnpm run test:pw:update). You can also focus on a specific test case (via test.only) if needed.
  But you should not commit any of the screenshots generated by this approach because different machines and configurations can lead to different screenshot results and thus, non-consistent results in case of subsequent test runs.
• If you want to generate screenshots to check into the repository, or if just want to validate that no regression occured, you should first build the Storybook UI (pnpm run build-and-serve-storybook) and then run all Playwright tests via Docker (test:pw-docker).
  Running the tests using Docker guarantees that test results are consistent, even on different machines. See the README of file-explorer/playwright for more information.

Sending a Pull Request

Make sure the following is true:

• No compilation errors (pnpm run compile)
• No linting errors or warnings (pnpm run lint)
• Code is formatted (pnpm run format)
• Unit Tests do not fail (pnpm run test:unit)
• Logic and Visual Regression Tests do not fail (pnpm run build-and-serve-storybook && pnpm run test:pw-docker)