Use an inline script tag with unpkg to explicitly show what we're including. It allows to easily test regressions by appending @2.x.x at the end of the of the link. It also allows to directly check if the repro is using the latest version
9.1 KiB
Vue.js Contributing Guide
Hi! I’m really excited that you are interested in contributing to Vue.js. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.
- Code of Conduct
- Issue Reporting Guidelines
- Pull Request Guidelines
- Development Setup
- Project Structure
Issue Reporting Guidelines
-
The issue list of this repo is exclusively for bug reports and feature requests. Non-conforming issues will be closed immediately.
-
For simple beginner questions, you can get quick answers from The Gitter chat room.
-
For more complicated questions, you can use the official forum or StackOverflow. Make sure to provide enough information when asking your questions - this makes it easier for others to help you!
-
-
Try to search for your issue, it may have already been answered or even fixed in the development branch.
-
Check if the issue is reproducible with the latest stable version of Vue. If you are using a pre-release, please indicate the specific version you are using.
-
It is required that you clearly describe the steps necessary to reproduce the issue you are running into. Although we would love to help our users as much as possible, diagnosing issues without clear reproduction steps is extremely time-consuming and simply not sustainable.
-
Use only the minimum amount of code necessary to reproduce the unexpected behavior. A good bug report should isolate specific methods that exhibit unexpected behavior and precisely define how expectations were violated. What did you expect the method or methods to do, and how did the observed behavior differ? The more precisely you isolate the issue, the faster we can investigate.
-
Issues with no clear repro steps will not be triaged. If an issue labeled "need repro" receives no further input from the issue author for more than 5 days, it will be closed.
-
It is recommended that you make a JSFiddle/JSBin/Codepen to demonstrate your issue. You could start with this template that already includes the latest version of Vue.
-
For potential SSR (Server Side Rendering) issue or bugs that involves build setups, you can create a reproduction repository with steps in the README.
-
If your issue is resolved but still open, don’t hesitate to close it. In case you found a solution by yourself, it could be helpful to explain how you fixed it.
-
Most importantly, we beg your patience: the team must balance your request against many other responsibilities — fixing other bugs, answering other questions, new features, new documentation, etc. The issue list is not paid support and we cannot make guarantees about how fast your issue can be resolved.
Pull Request Guidelines
-
The
master
branch is basically just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against themaster
branch. -
Checkout a topic branch from the relevant branch, e.g.
dev
, and merge back against that branch. -
Work in the
src
folder and DO NOT checkindist
in the commits. -
It's OK to have multiple small commits as you work on the PR - we will let GitHub automatically squash it before merging.
-
Make sure
npm test
passes. (see development setup) -
If adding new feature:
- Add accompanying test case.
- Provide convincing reason to add this feature. Ideally you should open a suggestion issue first and have it greenlighted before working on it.
-
If fixing a bug:
- If you are resolving a special issue, add
(fix #xxxx[,#xxx])
(#xxxx is the issue id) in your PR title for a better release log, e.g.update entities encoding/decoding (fix #3899)
. - Provide detailed description of the bug in the PR. Live demo preferred.
- Add appropriate test coverage if applicable.
- If you are resolving a special issue, add
Development Setup
You will need Node.js version 6+ and Java Runtime Environment (needed for running Selenium server during e2e tests).
After cloning the repo, run:
$ npm install
If you are on a Unix-like system, optionally install the Git pre-commit hook with:
$ npm run install:hooks
This will run ESLint on changed files before each commit.
Commonly used NPM scripts
# watch and auto re-build dist/vue.js
$ npm run dev
# watch and auto re-run unit tests in Chrome
$ npm run dev:test
# build all dist files, including npm packages
$ npm run build
# run the full test suite, include linting / type checking
$ npm test
There are some other scripts available in the scripts
section of the package.json
file.
The 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 beforehand.
Project Structure
-
build
: contains build-related configuration files. In most cases you don't need to touch them. -
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. -
flow
: contains type declarations for Flow. These declarations are loaded globally and you will see them used in type annotations in normal source code. -
packages
: containsvue-server-renderer
andvue-template-compiler
, which are distributed as separate NPM packages. They are automatically generated from the source code and always have the same version with the mainvue
package. -
test
: contains all tests. The unit tests are written with Jasmine and run with Karma. The e2e tests are written for and run with Nightwatch.js. -
src
: contains the source code, obviously. The codebase is written in ES2015 with Flow type annotations.-
entries
: contains entries for different builds and packages.-
web-runtime
: the entry fordist/vue.common.js
, a.k.a the runtime-only build. It does not include the template to render function compiler, so it does not support thetemplate
option. This is set as themain
field inpackage.json
so it is the default export when you import Vue as an NPM package. -
web-runtime-with-compiler
: the entry fordist/vue.js
, a.k.a the standalone build. It includes the template to render function compiler. To use this build from the NPM packages, doimport Vue from 'vue/dist/vue'
, or aliasvue
tovue/dist/vue
in your build tool configuration. -
web-compiler.js
: the entry for thevue-template-compiler
NPM package. -
web-server-renderer.js
: the entry for thevue-server-renderer
NPM package.
-
-
compiler
: contains code for the template-to-render-function compiler.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 the 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.
-
core
: contains universal, platform-agnostic runtime code.The Vue 2.0 core is platform-agnostic - which means code inside
core
should be able to run in any JavaScript environment, be it the browser, Node.js, or an embedded JavaScript runtime in native applications.-
observer
: contains code related to the reactivity system. -
vdom
: contains code related to vdom element creation and patching. -
instance
: contains Vue instance constructor and prototype methods. -
global-api
: as the name suggests. -
components
: universal abstract components. Currentlykeep-alive
is the only one.
-
-
server
: contains code related to server-side rendering. -
platforms
: contains platform-specific code.Each platform module contains three parts:
compiler
,runtime
andserver
, corresponding to the three directories above. Each part contains platform-specific modules/utilities which are then imported and injected to the core counterparts in platform-specific entry files. For example, the code implementing the logic behindv-bind:class
is inplatforms/web/runtime/modules/class.js
- which is imported inentries/web-runtime.js
and used to create the browser-specific vdom patching function. -
sfc
: contains single-file component (*.vue
files) parsing logic. This is used in thevue-template-compiler
package. -
shared
: contains utilities shared across the entire codebase.
-