Skip to content

Commit 3e60288

Browse files
committed
chore: update contributing guide [ci skip]
1 parent 2b19965 commit 3e60288

File tree

1 file changed

+18
-24
lines changed

1 file changed

+18
-24
lines changed

.github/contributing.md

+18-24
Original file line numberDiff line numberDiff line change
@@ -74,30 +74,18 @@ yarn build runtime --all
7474

7575
By default, each package will be built in multiple distribution formats as specified in the `buildOptions.formats` field in its `package.json`. These can be overwritten via the `-f` flag. The following formats are supported:
7676

77-
- **`global`**:
77+
- **`global`**
78+
- **`esm-bundler`**
79+
- **`esm-browser`**
80+
- **`cjs`**
7881

79-
- For direct use via `<script>` in the browser. The global variable exposed is specified via the `buildOptions.name` field in a package's `package.json`.
80-
- Note: global builds are not [UMD](https://github.com/umdjs/umd) builds. Instead they are built as [IIFEs](https://developer.mozilla.org/en-US/docs/Glossary/IIFE).
82+
Additional formats that only apply to the main `vue` package:
8183

82-
- **`esm-bundler`**:
84+
- **`global-runtime`**
85+
- **`esm-bundler-runtime`**
86+
- **`esm-browser-runtime`**
8387

84-
- Leaves prod/dev branches with `process.env.NODE_ENV` guards (to be replaced by bundler)
85-
- Does not ship a minified build (to be done together with the rest of the code after bundling)
86-
- For use with bundlers like `webpack`, `rollup` and `parcel`.
87-
- Imports dependencies (e.g. `@vue/runtime-core`, `@vue/runtime-compiler`)
88-
- Imported dependencies are also `esm-bundler` builds and will in turn import their dependencies (e.g. `@vue/runtime-core` imports `@vue/reactivity`)
89-
- This means you **can** install/import these deps without ending up with different instances of these dependencies
90-
91-
- **`esm`**:
92-
93-
- For usage via native ES modules imports (in browser via `<script type="module">`, or via Node.js native ES modules support in the future)
94-
- Inlines all dependencies - i.e. it's a single ES module with no imports from other files
95-
- This means you **must** import everything from this file and this file only to ensure you are getting the same instance of code.
96-
- Hard-coded prod/dev branches, and the prod build is pre-minified (you will have to use different paths/aliases for dev/prod)
97-
98-
- **`cjs`**:
99-
- For use in Node.js server-side rendering via `require()`.
100-
- The dev/prod files are pre-built, but are dynamically required based on `process.env.NODE_ENV` in `index.js`, which is the default entry when you do `require('vue')`.
88+
More details about each of these formats can be found in the [`vue` package README](https://github.com/vuejs/vue-next/blob/master/packages/vue/README.md#which-dist-file-to-use) and the [Rollup config file](https://github.com/vuejs/vue-next/blob/master/rollup.config.js).
10189

10290
For example, to build `runtime-core` with the global build only:
10391

@@ -108,7 +96,7 @@ yarn build runtime-core -f global
10896
Multiple formats can be specified as a comma-separated list:
10997

11098
```bash
111-
yarn build runtime-core -f esm,cjs
99+
yarn build runtime-core -f esm-browser,cjs
112100
```
113101

114102
#### Build with Source Maps
@@ -140,9 +128,13 @@ $ yarn dev
140128

141129
- The `dev` script also supports the `-s` flag for generating source maps, but it will make rebuilds slower.
142130

131+
### `yarn dev-compiler`
132+
133+
The `dev-compiler` script builds, watches and serves the [Template Explorer](https://github.com/vuejs/vue-next/tree/master/packages/template-explorer) at `http://localhost:5000`. This is extremely useful when working on the compiler.
134+
143135
### `yarn test`
144136

145-
The `yarn test` script simply calls the `jest` binary, so all [Jest CLI Options](https://jestjs.io/docs/en/cli) can be used. Some examples:
137+
The `test` script simply calls the `jest` binary, so all [Jest CLI Options](https://jestjs.io/docs/en/cli) can be used. Some examples:
146138

147139
```bash
148140
# run all tests
@@ -234,7 +226,7 @@ There are some rules to follow when importing across package boundaries:
234226

235227
- Compiler packages should not import items from the runtime, and vice versa. If something needs to be shared between the compiler-side and runtime-side, it should be extracted into `@vue/shared` instead.
236228

237-
- If a package (A) has a non-type import from another package (B), package (B) should be listed as a dependency in the `package.json` of package (A). This is because the packages are externalized in the ESM-bundler/CJS builds and type declaration files, so the dependency packages must be actually installed as a dependency when consumed from package registries.
229+
- If a package (A) has a non-type import, or re-exports a type from another package (B), then (B) should be listed as a dependency in (A)'s `package.json`. This is because the packages are externalized in the ESM-bundler/CJS builds and type declaration files, so the dependency packages must be actually installed as a dependency when consumed from package registries.
238230

239231
## Contributing Tests
240232

@@ -246,6 +238,8 @@ Unit tests are collocated with the code being tested in each package, inside dir
246238

247239
- Only use platform-specific runtimes if the test is asserting platform-specific behavior.
248240

241+
Test coverage is continuously deployed at https://vue-next-coverage.netlify.app/. PRs that improve test coverage are welcome, but in general the test coverage should be used as a guidance for finding API use cases that are not covered by tests. We don't recommend adding tests that only improve coverage but not actually test a meaning use case.
242+
249243
### Testing Type Definition Correctness
250244

251245
This project uses [tsd](https://github.com/SamVerschueren/tsd) to test the built definition files (`*.d.ts`).

0 commit comments

Comments
 (0)