1# Vue.js Contributing Guide23Hi! I'm really excited that you are interested in contributing to Vue.js. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:45- [Code of Conduct](https://github.com/vuejs/vue/blob/dev/.github/CODE_OF_CONDUCT.md)6- [Issue Reporting Guidelines](#issue-reporting-guidelines)7- [Pull Request Guidelines](#pull-request-guidelines)8- [Development Setup](#development-setup)9- [Project Structure](#project-structure)1011## Issue Reporting Guidelines1213- Always use [https://new-issue.vuejs.org/](https://new-issue.vuejs.org/) to create new issues.1415## Pull Request Guidelines1617- The `master` branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. **Do not submit PRs against the `master` branch.**1819- Checkout a topic branch from the relevant branch, e.g. `dev`, and merge back against that branch.2021- Work in the `src` folder and **DO NOT** checkin `dist` in the commits.2223- It's OK to have multiple small commits as you work on the PR - GitHub will automatically squash it before merging.2425- Make sure `npm test` passes. (see [development setup](#development-setup))2627- If adding a new feature:2829  - Add accompanying test case.30  - Provide a convincing reason to add this feature. Ideally, you should open a suggestion issue first and have it approved before working on it.3132- If fixing bug:33  - 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. `update entities encoding/decoding (fix #3899)`.34  - Provide a detailed description of the bug in the PR. Live demo preferred.35  - Add appropriate test coverage if applicable.3637## Development Setup3839You will need [Node.js](https://nodejs.org) **version 18+** and [pnpm](https://pnpm.io/) **version 8+**.4041After cloning the repo, run:4243```bash44$ pnpm i # install the dependencies of the project45```4647### Committing Changes4849Commit messages should follow the [commit message convention](./COMMIT_CONVENTION.md) so that changelogs can be automatically generated. Commit messages will be automatically validated upon commit. If you are not familiar with the commit message convention, you can use `npm run commit` instead of `git commit`, which provides an interactive CLI for generating proper commit messages.5051### Commonly used NPM scripts5253```bash54# watch and auto re-build dist/vue.js55$ npm run dev5657# run unit tests58$ npm run test:unit5960# run specific tests in watch mode61$ npx vitest {test_file_name_pattern_to_match}6263# build all dist files, including npm packages64$ npm run build6566# run the full test suite, including unit/e2e/type checking67$ npm test68```6970There are some other scripts available in the `scripts` section of the `package.json` file.7172The default test script will do the following: lint with ESLint -> type check with Flow -> unit tests with coverage -> e2e tests. **Please make sure to have this pass successfully before submitting a PR.** Although the same tests will be run against your PR on the CI server, it is better to have it working locally.7374## Project Structure7576- **`scripts`**: contains build-related scripts and configuration files. Usually, you don't need to touch them. However, it would be helpful to familiarize yourself with the following files:7778  - `scripts/alias.js`: module import aliases used across all source code and tests.7980  - `scripts/config.js`: contains the build configurations for all files found in `dist/`. Check this file if you want to find out the entry source file for a dist file.8182- **`dist`**: contains built files for distribution. Note this directory is only updated when a release happens; they do not reflect the latest changes in development branches.8384  See [dist/README.md](https://github.com/vuejs/vue/blob/dev/dist/README.md) for more details on dist files.8586- **`types`**: contains public types published to npm (note the types shipped here could be different from `src/types`). These were hand-authored before we moved the codebase from Flow to TypeScript. To ensure backwards compatibility, we keep using these manually authored types.8788  Types for new features added in 2.7 (Composition API) are auto-generated from source code as `types/v3-generated.d.ts` and re-exported from `types/index.d.ts`.8990- **`packages`**:9192  - `vue-server-renderer` and `vue-template-compiler` are distributed as separate NPM packages. They are automatically generated from the source code and always have the same version with the main `vue` package.9394  - `compiler-sfc` is an internal package that is distributed as part of the main `vue` package. It's aliased and can be imported as `vue/compiler-sfc` similar to Vue 3.9596- **`test`**: contains all tests. The unit tests are written with [Jasmine](http://jasmine.github.io/2.3/introduction.html) and run with [Karma](http://karma-runner.github.io/0.13/index.html). The e2e tests are written for and run with [Nightwatch.js](http://nightwatchjs.org/).9798- **`src`**: contains the source code. The codebase is written in ES2015 with [Flow](https://flowtype.org/) type annotations.99100  - **`compiler`**: contains code for the template-to-render-function compiler.101102    The compiler consists of a parser (converts template strings to element ASTs), an optimizer (detects static trees for vdom render optimization), and a code generator (generate render function code from element ASTs). Note that codegen directly generates code strings from the element AST - it's done this way for smaller code size because the compiler is shipped to the browser in the standalone build.103104  - **`core`**: contains universal, platform-agnostic runtime code.105106    The Vue 2.0 core is platform-agnostic. That is, the code inside `core` is able to be run in any JavaScript environment, be it the browser, Node.js, or an embedded JavaScript runtime in native applications.107108    - **`observer`**: contains code related to the reactivity system.109110    - **`vdom`**: contains code related to vdom element creation and patching.111112    - **`instance`**: contains Vue instance constructor and prototype methods.113114    - **`global-api`**: contains Vue global api.115116    - **`components`**: contains universal abstract components.117118  - **`server`**: contains code related to server-side rendering.119120  - **`platforms`**: contains platform-specific code.121122    Entry files for dist builds are located in their respective platform directory.123124    Each platform module contains three parts: `compiler`, `runtime` and `server`, corresponding to the three directories above. Each part contains platform-specific modules/utilities which are imported and injected to the core counterparts in platform-specific entry files. For example, the code implementing the logic behind `v-bind:class` is in `platforms/web/runtime/modules/class.js` - which is imported in `platforms/web/entry-runtime.ts` and used to create the browser-specific vdom patching function.125126  - **`sfc`**: contains single-file component (`*.vue` files) parsing logic. This is used in the `vue-template-compiler` package.127128  - **`shared`**: contains utilities shared across the entire codebase.129130  - **`types`**: contains type declarations added when we ported the codebase from Flow to TypeScript. These types should be considered internal - they care less about type inference for end-user scenarios and prioritize working with internal source code.131132## Financial Contribution133134As a pure community-driven project without major corporate backing, we also welcome financial contributions via GitHub Sponsors and OpenCollective. Please consult the [Sponsor Page](https://vuejs.org/sponsor/) for more details.135136## Credits137138Thank you to all the people who have already contributed to Vue.js!139140<a href="https://github.com/vuejs/vue/graphs/contributors"><img src="https://opencollective.com/vuejs/contributors.svg?width=890" /></a>