Skip to content

Latest commit

聽

History

History
172 lines (112 loc) 路 9.42 KB

contributing.md

File metadata and controls

172 lines (112 loc) 路 9.42 KB
Raw

Vue Router Contributing Guide

Hi! I'm really excited that you are interested in contributing to Vue Router. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

Issue Reporting Guidelines

Pull Request Guidelines

  • 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.

  • If fixing 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. 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. You can check the coverage of your code addition by running pnpm test --coverage.

  • 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 so that the changelog can be automatically generated. Commit messages are automatically validated before commit (by invoking Git Hooks via 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 via yorkie).

Development Setup

You will need Node.js version 10+, and Pnpm.

After cloning the repo, run:

pnpm install # install the dependencies of the project

A high level overview of tools used:

Scripts

pnpm build

The build script builds vue-router

pnpm play

The play scripts starts a playground project located at playground/ that allows you to test things on a browser.

pnpm play

pnpm test

The pnpm test script runs all checks:

  • Typings: test:types
  • Linting: test:lint
  • Unit tests: test:unit
  • Building: build
# run all tests
$ pnpm test

# run unit tests in watch mode
$ pnpm jest --watch

Project Structure

Vue Router source code can be found in the src directory:

  • src/history: history implementations that are instantiable with create*History(). This folder contains code related to using the History API.
  • src/matcher: RouteMatcher implementation. Contains the code that transforms paths like /users/:id into regexps and handle the transformation of locations like { name: 'UserDetail', params: { id: '2' } } to strings. It contains path ranking logic and the part of dynamic routing that concerns matching urls in the right order.
  • src/utils: contains small utility functions that are used across other sections of the router but are not contained by them.
  • src/router: contains the router creation, navigation execution, using the matcher, the history implementation. It runs navigation guards.
  • src/location: helpers related to route location and urls
  • src/encoding: helpers related to url encoding
  • src/errors: different internal and external errors with their messages
  • src/index: contains all public API as exports.
  • src/types: contains global types that are used across multiple sections of the router.

Contributing Tests

Unit tests are located inside __tests__. Consult the Jest docs and existing test cases for how to write new test specs. Here are some additional guidelines:

  • Use the minimal API needed for a test case. For example, if a test can be written without involving the reactivity system or a component, it should be written so. This limits the test's exposure to changes in unrelated parts and makes it more stable.
  • Use the minimal API needed for a test case. For example, if a test concerns the router-link component, don't create a router instance, mock the needed properties instead.
  • Write a unit test whenever possible
  • If a test is specific to a browser, create an e2e (end to end) test and make sure to indicate it on the test

Contributing Docs

Currently, all the docs can be found in packages/docs. It contains the English markdown files while translation(s) are stored in their corresponding <lang> sub-folder(s):

  • zh: Chinese translation.

Besides that, the .vitepress sub-folder is used to put the config and theme, including the i18n information.

Contributing to the English docs is the same as contributing to the source code. You can simply create a pull request to our GitHub repo. However, if you would like to contribute to the translations, there are 2 options and some extra steps to follow:

Translate in a <lang> sub-folder and host it on our official repo

If you want to start translating the docs in a new language:

  1. Create the corresponding <lang> sub-folder for your translation.
  2. Modify the i18n config in .vitepress sub-folder.
  3. Translate the docs and run the doc site to self-test locally.
  4. Create a checkpoint for your language by running pnpm run docs:translation-status <lang> [<commit>]. A checkpoint is the hash and date of the latest commit when you do the translation. The checkpoint information would be stored in the status file packages/docs/.vitepress/translation-status.json. It's important for the long-term maintenance since all the further translation sync-ups would be based on their previous checkpoints. Usually you can skip the commit argument because the default value is main.
  5. Commit all the changes and create a pull request to our GitHub repo.

We will have a paragraph right at the top of each translation page that shows the status of the translation. That way, users can easily figure out if the translation is up-to-date or lags behind the English version.

Speaking of the up-to-date translation, we also need good long-term maintenance for every language. If you want to update an existing translation:

  1. See what translation you need to sync up with the original docs. There are 2 popular ways:
    1. Via the GitHub Compare page: only see the changes in packages/docs/* from the checkpoint hash to main branch. You can find the checkpoint hash for your language via the translation status file packages/docs/.vitepress/translation-status.json. And the compare page can be directly opened with the hash as part of the URL e.g. https://github.com/vuejs/router/compare/e008551...main
    2. Via a local command: pnpm run docs:compare-to-translate <lang> [<commit>].
  2. Create your own branch and start the translation update, following the previous comparison.
  3. Create a checkpoint for your language by running pnpm run docs:translation-status <lang> [<commit>].
  4. Commit all the changes and create a pull request to our GitHub repo.

Self-host the translation

You can also host the translation on your own. To create one, just simply fork our GitHub repo and change the content and site config in packages/docs. To long-term maintain it, we highly recommend a similar way that we do above for our officially hosted translations:

  • Ensure you maintain the checkpoint properly. And also ensure the translation status is well-displayed on the top of each translation page.
  • Utilize the diff result between the latest official repository and your own checkpoint to guide your translation.

Tip: you can add the official repo as a remote to your forked repo, this way you can still run pnpm run docs:translation-status <lang> [<commit>] and npm run docs:compare-to-translate <lang> [<commit>] to get the checkpoint and diff result:

# prepare the upstream remote
git remote add upstream git@github.com:vuejs/router.git
git fetch upstream main

# set the checkpoint
pnpm run docs:translation-status <lang> upstream/main

# get the diff result
pnpm run docs:compare-to-translate <lang> upstream/main

Credits

Thank you to all the people who have already contributed to Vue Router!