From ae5639ccfa29c056fbb1a3ebb55070b65392168d Mon Sep 17 00:00:00 2001 From: Tony Trinh Date: Tue, 19 Jul 2022 12:17:21 -0500 Subject: [PATCH] docs: update CONTRIBUTING.md (#9127) --- CONTRIBUTING.md | 117 ++++++++++++++++++++---------------------------- 1 file changed, 48 insertions(+), 69 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 65fb07f88fad9d..350f36b0f25351 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Vite Contributing Guide -Hi! We are really excited that you are interested in contributing to Vite. Before submitting your contribution, please make sure to take a moment and read through the following guide: +Hi! We're really excited that you're interested in contributing to Vite! Before submitting your contribution, please read through the following guide. ## Repo Setup @@ -8,7 +8,7 @@ The Vite repo is a monorepo using pnpm workspaces. The package manager used to i To develop and test the core `vite` package: -1. Run `pnpm i` in Vite's root folder +1. Run `pnpm i` in Vite's root folder. 2. Run `pnpm run build` in Vite's root folder. @@ -16,41 +16,41 @@ To develop and test the core `vite` package: You can alternatively use [Vite.js Docker Dev](https://github.com/nystudio107/vitejs-docker-dev) for a containerized Docker setup for Vite.js development. -> Vite uses pnpm v7. If you are working on multiple projects with different versions of pnpm, it's recommend to enable [Corepack](https://github.com/nodejs/corepack) by running `corepack enable`. +> Vite uses pnpm v7. If you are working on multiple projects with different versions of pnpm, it's recommended to enable [Corepack](https://github.com/nodejs/corepack) by running `corepack enable`. ## Debugging -If you want to use break point and explore code execution you can use the ["Run and debug"](https://code.visualstudio.com/docs/editor/debugging) feature from vscode. +To use breakpoints and explore code execution, you can use the ["Run and Debug"](https://code.visualstudio.com/docs/editor/debugging) feature from VS Code. 1. Add a `debugger` statement where you want to stop the code execution. -2. Click on the "Run and Debug" icon in the activity bar of the editor. +2. Click the "Run and Debug" icon in the activity bar of the editor, which opens the [_Run and Debug view_](https://code.visualstudio.com/docs/editor/debugging#_run-and-debug-view). -3. Click on the "JavaScript Debug Terminal" button. +3. Click the "JavaScript Debug Termimal" button in the _Run and Debug view_, which opens a terminal in VS Code. -4. It will open a terminal, then go to `playground/xxx` and run `pnpm run dev`. +4. From that terminal, go to `playground/xxx`, and run `pnpm run dev`. -5. The execution will stop and you'll use the [Debug toolbar](https://code.visualstudio.com/docs/editor/debugging#_debug-actions) to continue, step over, restart the process... +5. The execution will stop at the `debugger` statement, and you can use the [Debug toolbar](https://code.visualstudio.com/docs/editor/debugging#_debug-actions) to continue, step over, and restart the process... -### Debugging errors in Vitest tests using Playwright (Chromium) +### Debugging Errors in Vitest Tests Using Playwright (Chromium) Some errors are masked and hidden away because of the layers of abstraction and sandboxed nature added by Vitest, Playwright, and Chromium. In order to see what's actually going wrong and the contents of the devtools console in those instances, follow this setup: 1. Add a `debugger` statement to the `playground/vitestSetup.ts` -> `afterAll` hook. This will pause execution before the tests quit and the Playwright browser instance exits. -1. Run the tests with the `debug-serve` script command which will enable remote debugging: `pnpm run debug-serve resolve`. +2. Run the tests with the `debug-serve` script command, which will enable remote debugging: `pnpm run debug-serve resolve`. -1. Wait for inspector devtools to open in your browser and the debugger to attach. +3. Wait for inspector devtools to open in your browser and the debugger to attach. -1. In the sources panel in the right column, click the play button to resume execution and allow the tests to run which will open a Chromium instance. +4. In the sources panel in the right column, click the play button to resume execution, and allow the tests to run, which will open a Chromium instance. -1. Focusing the Chromium instance, you can open the browser devtools and inspect the console there to find the underlying problems. +5. Focusing the Chromium instance, you can open the browser devtools and inspect the console there to find the underlying problems. -1. To close everything, just stop the test process back in your terminal. +6. To close everything, just stop the test process back in your terminal. ## Testing Vite against external packages -You may wish to test your locally-modified copy of Vite against another package that is built with Vite. For pnpm, after building Vite, you can use [`pnpm.overrides`](https://pnpm.io/package_json#pnpmoverrides). Please note that `pnpm.overrides` must be specified in the root `package.json` and you must first list the package as a dependency in the root `package.json`: +You may wish to test your locally modified copy of Vite against another package that is built with Vite. For pnpm, after building Vite, you can use [`pnpm.overrides`](https://pnpm.io/package_json#pnpmoverrides) to do this. Note that `pnpm.overrides` must be specified in the root `package.json`, and you must list the package as a dependency in the root `package.json`: ```json { @@ -73,7 +73,7 @@ And re-run `pnpm install` to link the package. Each package under `playground/` contains a `__tests__` directory. The tests are run using [Vitest](https://vitest.dev/) + [Playwright](https://playwright.dev/) with custom integrations to make writing tests simple. The detailed setup is inside `vitest.config.e2e.js` and `playground/vitest*` files. -Before running the tests, make sure that [Vite has been built](#repo-setup). On Windows, you may want to [activate Developer Mode](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) to solve [issues with symlink creation for non-admins](https://github.com/vitejs/vite/issues/7390). Also you may want to [set git `core.symlinks` to `true` to solve issues with symlinks in git](https://github.com/vitejs/vite/issues/5242). +Before running the tests, make sure that [Vite has been built](#repo-setup). On Windows, you may want to [activate Developer Mode](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) to resolve [issues with symlink creation for non-admins](https://github.com/vitejs/vite/issues/7390). Also, you may want to [set git `core.symlinks` to `true` to resolve issues with symlinks in git](https://github.com/vitejs/vite/issues/5242). Each integration test can be run under either dev server mode or build mode. @@ -83,21 +83,21 @@ Each integration test can be run under either dev server mode or build mode. - `pnpm run test-build` runs tests only under build mode. -- You can also use `pnpm run test-serve [match]` or `pnpm run test-build [match]` to run tests in a specific playground package, e.g. `pnpm run test-serve asset` will run tests for both `playground/asset` and `vite/src/node/__tests__/asset` under serve mode and `vite/src/node/__tests__/**/*` just run in serve mode. +- `pnpm run test-serve [match]` or `pnpm run test-build [match]` runs tests in specific packages that match the given filter. e.g. `pnpm run test-serve asset` runs tests for both `playground/asset` and `vite/src/node/__tests__/asset` under serve mode. Note package matching is not available for the `pnpm test` script, which always runs all tests. ### Unit Tests -Other than tests under `playground/` for integration tests, packages might contains unit tests under their `__tests__` directory. Unit tests are powered by [Vitest](https://vitest.dev/). The detailed config is inside `vitest.config.ts` files. +Other than tests under `playground/` for integration tests, packages might contain unit tests under their `__tests__` directory. Unit tests are powered by [Vitest](https://vitest.dev/). The detailed config is inside `vitest.config.ts` files. - `pnpm run test-unit` runs unit tests under each package. -- You can also use `pnpm run test-unit [match]` to run related tests. +- `pnpm run test-unit [match]` runs tests in specific packages that match the given filter. ### Test Env and Helpers -Inside playground tests, you can import the `page` object from `~utils`, which is a Playwright [`Page`](https://playwright.dev/docs/api/class-page) instance that has already navigated to the served page of the current playground. So writing a test is as simple as: +Inside playground tests, you can import the `page` object from `~utils`, which is a Playwright [`Page`](https://playwright.dev/docs/api/class-page) instance that has already navigated to the served page of the current playground. So, writing a test is as simple as: ```js import { page } from '~utils' @@ -107,13 +107,13 @@ test('should work', async () => { }) ``` -Some common test helpers, e.g. `testDir`, `isBuild` or `editFile` are also available in the utils. Source code is located at `playground/test-utils.ts`. +Some common test helpers (e.g. `testDir`, `isBuild`, or `editFile`) are also available in the utils. Source code is located at `playground/test-utils.ts`. Note: The test build environment uses a [different default set of Vite config](https://github.com/vitejs/vite/blob/main/playground/vitestSetup.ts#L102-L122) to skip transpilation during tests to make it faster. This may produce a different result compared to the default production build. ### Extending the Test Suite -To add new tests, you should find a related playground to the fix or feature (or create a new one). As an example, static assets loading are tested in the [assets playground](https://github.com/vitejs/vite/tree/main/playground/assets). In this Vite App, there is a test for `?raw` imports, with [a section is defined in the `index.html` for it](https://github.com/vitejs/vite/blob/main/playground/assets/index.html#L121): +To add new tests, you should find a related playground to the fix or feature (or create a new one). As an example, static assets loading is tested in the [assets playground](https://github.com/vitejs/vite/tree/main/playground/assets). In this Vite app, there is a test for `?raw` imports with [a section defined in the `index.html` for it](https://github.com/vitejs/vite/blob/main/playground/assets/index.html#L121): ```html

?raw import

@@ -127,7 +127,7 @@ import rawSvg from './nested/fragment.svg?raw' text('.raw', rawSvg) ``` -Where the `text` util is defined as: +...where the `text` util is defined as: ```js function text(el, text) { @@ -145,34 +145,34 @@ test('?raw import', async () => { ## Note on Test Dependencies -In many test cases we need to mock dependencies using `link:` and `file:` protocols. `pnpm` treats `link:` as symlinks and `file:` as hardlinks. To test dependencies as if they are copied into `node_modules`, use the `file:` protocol, other cases should use the `link:` protocol. +In many test cases, we need to mock dependencies using `link:` and `file:` protocols. `pnpm` treats `link:` as symlinks and `file:` as hardlinks. To test dependencies as if they were copied into `node_modules`, use the `file:` protocol. Otherwise, use the `link:` protocol. ## Debug Logging -You can set the `DEBUG` environment variable to turn on debugging logs. E.g. `DEBUG="vite:resolve"`. To see all debug logs you can set `DEBUG="vite:*"`, but be warned that it will be quite noisy. You can run `grep -r "createDebugger('vite:" packages/vite/src/` to see a list of available debug scopes. +You can set the `DEBUG` environment variable to turn on debugging logs (e.g. `DEBUG="vite:resolve"`). To see all debug logs, you can set `DEBUG="vite:*"`, but be warned that it will be quite noisy. You can run `grep -r "createDebugger('vite:" packages/vite/src/` to see a list of available debug scopes. ## Pull Request Guidelines -- Checkout a topic branch from a base branch, e.g. `main`, and merge back against that branch. +- Checkout a topic branch from a base branch (e.g. `main`), and merge back against that branch. - If adding a new feature: - Add accompanying test case. - - Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first and have it approved before working on it. + - Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first, and have it approved before working on it. -- If fixing bug: +- If fixing a bug: - - If you are resolving a special issue, add `(fix #xxxx[,#xxxx])` (#xxxx is the issue id) in your PR title for a better release log, e.g. `fix: update entities encoding/decoding (fix #3899)`. + - If you are resolving a special issue, add `(fix #xxxx[,#xxxx])` (#xxxx is the issue id) in your PR title for a better release log (e.g. `fix: update entities encoding/decoding (fix #3899)`). - Provide a detailed description of the bug in the PR. Live demo preferred. - Add appropriate test coverage if applicable. -- It's OK to have multiple small commits as you work on the PR - GitHub can automatically squash them before merging. +- It's OK to have multiple small commits as you work on the PR. GitHub can automatically squash them before merging. - Make sure tests pass! - Commit messages must follow the [commit message convention](./.github/commit-convention.md) so that changelogs can be automatically generated. Commit messages are automatically validated before commit (by invoking [Git Hooks](https://git-scm.com/docs/githooks) via [yorkie](https://github.com/yyx990803/yorkie)). -- No need to worry about code style as long as you have installed the dev dependencies - modified files are automatically formatted with Prettier on commit (by invoking [Git Hooks](https://git-scm.com/docs/githooks) via [yorkie](https://github.com/yyx990803/yorkie)). +- No need to worry about code style as long as you have installed the dev dependencies. Modified files are automatically formatted with Prettier on commit (by invoking [Git Hooks](https://git-scm.com/docs/githooks) via [yorkie](https://github.com/yyx990803/yorkie)). ## Maintenance Guidelines @@ -196,62 +196,41 @@ You can set the `DEBUG` environment variable to turn on debugging logs. E.g. `DE Vite aims to be lightweight, and this includes being aware of the number of npm dependencies and their size. -We use rollup to pre-bundle most dependencies before publishing! Therefore most dependencies, even used in src code, should be added under `devDependencies` by default. This also creates a number of constraints that we need to be aware of in the codebase: +We use Rollup to pre-bundle most dependencies before publishing! Therefore, most dependencies, even those used in runtime source code, should be added under `devDependencies` by default. This also creates the following constraints that we need to be aware of in the codebase. ### Usage of `require()` -In some cases we intentionally lazy-require some dependencies to improve startup performance. However, note that we cannot use simple `require('somedep')` calls since these are ignored in ESM files so the dependency won't be included in the bundle, and the actual dependency won't even be there when published since they are in `devDependencies`. +In some cases, we intentionally lazy-require some dependencies to improve start-up performance. However, note that we cannot use simple `require('somedep')` calls since these are ignored in ESM files, so the dependency won't be included in the bundle, and the actual dependency won't even be there when published since they are in `devDependencies`. Instead, use `(await import('somedep')).default`. -### Think before adding a dependency +### Think Before Adding a Dependency Most deps should be added to `devDependencies` even if they are needed at runtime. Some exceptions are: - Type packages. Example: `@types/*`. - Deps that cannot be properly bundled due to binary files. Example: `esbuild`. -- Deps that ships its own types and its type is used in vite's own public types. Example: `rollup`. +- Deps that ship their own types that are used in Vite's own public types. Example: `rollup`. -Avoid deps that has large transitive dependencies that results in bloated size compared to the functionality it provides. For example, `http-proxy` itself plus `@types/http-proxy` is a little over 1MB in size, but `http-proxy-middleware` pulls in a ton of dependencies that makes it 7MB(!) when a minimal custom middleware on top of `http-proxy` only requires a couple lines of code. +Avoid deps with large transitive dependencies that result in bloated size compared to the functionality it provides. For example, `http-proxy` itself plus `@types/http-proxy` is a little over 1MB in size, but `http-proxy-middleware` pulls in a ton of dependencies that make it 7MB(!) when a minimal custom middleware on top of `http-proxy` only requires a couple of lines of code. -### Ensure type support +### Ensure Type Support -Vite aims to be fully usable as a dependency in a TypeScript project (e.g. it should provide proper typings for VitePress), and also in `vite.config.ts`. This means technically a dependency whose types are exposed needs to be part of `dependencies` instead of `devDependencies`. However, these means we won't be able to bundle it. +Vite aims to be fully usable as a dependency in a TypeScript project (e.g. it should provide proper typings for VitePress), and also in `vite.config.ts`. This means technically a dependency whose types are exposed needs to be part of `dependencies` instead of `devDependencies`. However, this also means we won't be able to bundle it. -To get around this, we inline some of these dependencies' types in `packages/vite/types`. This way we can still expose the typing but bundle the dependency's source code. +To get around this, we inline some of these dependencies' types in `packages/vite/types`. This way, we can still expose the typing but bundle the dependency's source code. -Use `pnpm run check-dist-types` to check bundled types does not rely on types in `devDependencies`. If you are adding `dependencies`, make sure to configure `tsconfig.check.json`. +Use `pnpm run check-dist-types` to check that the bundled types do not rely on types in `devDependencies`. If you are adding `dependencies`, make sure to configure `tsconfig.check.json`. -### Think before adding yet another option +### Think Before Adding Yet Another Option -We already have many config options, and we should avoid fixing an issue by adding yet another one. Before adding an option, try to think about: +We already have many config options, and we should avoid fixing an issue by adding yet another one. Before adding an option, consider whether the problem: -- Whether the problem is really worth addressing -- Whether the problem can be fixed with a smarter default -- Whether the problem has workaround using existing options -- Whether the problem can be addressed with a plugin instead +- is really worth addressing +- can be fixed with a smarter default +- has workaround using existing options +- can be addressed with a plugin instead -## Docs translation contribution +## Docs Translation Contribution -If you would like to start a translation in your language, you are welcome to contribute! Please join [the #translations channel in Vite Land](https://chat.vitejs.dev) to discuss and coordinate with others. - -The english docs are embedded in the main Vite repo, to allow contributors to work on docs, tests and implementation in the same PR. Translations are done by forking the main repo. - -### How to start a translation repo - -1. In order to get all doc files, you first need to clone this repo in your personal account. -2. Keep all the files in `docs/` and remove everything else. - - - You should setup your translation site based on all the files in `docs/` folder as a VitePress project. - (that said, `package.json` is need). - - - Refresh git history by removing `.git` and then `git init` - -3. Translate the docs. - - - During this stage, you may be translating documents and synchronizing updates at the same time, but don't worry about that, it's very common in translation contribution. - -4. Push your commits to your GitHub repo. you can setup a netlify preview as well. -5. Use [Ryu-cho](https://github.com/vuejs-translations/ryu-cho) tool to setup a GitHub Action, automatically track English docs update later. - -We recommend talking with others in Vite Land so you find more contributors for your language to share the maintenance work. Once the translation is done, communicate it to the Vite team so the repo can be moved to the official vitejs org in GitHub. +To add a new language to the Vite docs, see [`vite-docs-template`](https://github.com/tony19/vite-docs-template/blob/main/.github/CONTRIBUTING.md).