You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: .github/contributing.md
+47-36
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ Hi! I'm really excited that you are interested in contributing to Vue Router. Be
17
17
18
18
## Pull Request Guidelines
19
19
20
-
-Checkout a topic branch from a base branch, e.g. `main`, and merge back against that branch.
20
+
-Check out a topic branch from a base branch, e.g. `main`, and merge back against that branch.
21
21
22
22
- If adding a new feature:
23
23
@@ -26,7 +26,7 @@ Hi! I'm really excited that you are interested in contributing to Vue Router. Be
26
26
27
27
- If fixing bug:
28
28
29
-
- 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)`.
29
+
- If you are resolving a particular 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)`.
30
30
- Provide a detailed description of the bug in the PR. Live demo preferred.
31
31
- Add appropriate test coverage if applicable. You can check the coverage of your code addition by running `pnpm test --coverage`.
32
32
@@ -48,7 +48,7 @@ After cloning the repo, run:
48
48
pnpm install # install the dependencies of the project
49
49
```
50
50
51
-
A highlevel overview of tools used:
51
+
A high-level overview of tools used:
52
52
53
53
-[TypeScript](https://www.typescriptlang.org/) as the development language
54
54
-[Rollup](https://rollupjs.org) for bundling
@@ -63,7 +63,7 @@ The `build` script builds vue-router
63
63
64
64
### `pnpm play`
65
65
66
-
The `play`scripts starts a playground project located at `playground/` that allows you to test things on a browser.
66
+
The `play`script starts a playground project located at `playground/`, allowing you to test things on a browser.
67
67
68
68
```bash
69
69
pnpm play
@@ -91,66 +91,77 @@ $ pnpm jest --watch
91
91
Vue Router source code can be found in the `src` directory:
92
92
93
93
-`src/history`: history implementations that are instantiable with `create*History()`. This folder contains code related to using the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API).
94
-
-`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.
95
-
-`src/utils`: contains small utility functions that are used across other sections of the router but are not contained by them.
96
-
-`src/router`: contains the router creation, navigation execution, using the matcher, the history implementation. It runs navigation guards.
97
-
-`src/location`: helpers related to route location and urls
98
-
-`src/encoding`: helpers related to url encoding
94
+
-`src/matcher`: RouteMatcher implementation. Contains the code that transforms paths like `/users/:id` into regexps and handles 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 correct order.
95
+
-`src/utils`: contains small utility functions used across other router
96
+
-`src/router`: contains the router creation, navigation execution, matcher use, and history implementation. It runs navigation guards.
97
+
-`src/location`: helpers related to route location and URLs
98
+
-`src/encoding`: helpers related to URL encoding
99
99
-`src/errors`: different internal and external errors with their messages
100
-
-`src/index`: contains all public API as exports.
101
-
-`src/types`: contains global types that are used across multiple sections of the router.
100
+
-`src/index` contains all public APIs as exports.
101
+
-`src/types`: contains global types used across multiple router sections.
102
102
103
103
## Contributing Tests
104
104
105
105
Unit tests are located inside `__tests__`. Consult the [Jest docs](https://jestjs.io/docs/en/using-matchers) and existing test cases for how to write new test specs. Here are some additional guidelines:
106
106
107
107
- 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.
108
-
- 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.
108
+
- 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 required properties instead.
109
109
- Write a unit test whenever possible
110
-
- If a test is specific to a browser, create an e2e (end to end) test and make sure to indicate it on the test
110
+
- If a test is specific to a browser, create an e2e (end-to-end) test and make sure to indicate it on the test
111
111
112
112
## Contributing Docs
113
113
114
-
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):
114
+
All the documentation files can be found in `packages/docs`. It contains the English markdown files while translation(s) are stored in their corresponding `<lang>` sub-folder(s):
115
115
116
116
-[`zh`](https://github.com/vuejs/router/tree/main/packages/docs/zh): Chinese translation.
117
117
118
-
Besides that, the `.vitepress` sub-folder is used to put the config and theme, including the i18n information.
118
+
Besides that, the `.vitepress` sub-folder contains the config and theme, including the i18n information.
119
119
120
-
Consider the following two options in order to contribute to the translations:
120
+
Contributing to the English docs is the same as contributing to the source code. You can create a pull request to our GitHub repo. However, if you would like to contribute to the translations, there are two options and some extra steps to follow:
121
121
122
122
### Translate in a `<lang>` sub-folder and host it on our official repo
123
123
124
-
If you want to start translating the docs in a new language:
124
+
If you want to start translating the docs in a _new_ language:
125
125
126
126
1. Create the corresponding `<lang>` sub-folder for your translation.
127
-
2. Modify the i18n config in `.vitepress` sub-folder.
127
+
2. Modify the i18n configuration in the`.vitepress` sub-folder.
128
128
3. Translate the docs and run the doc site to self-test locally.
129
-
4. Once you have done all above, create a pull request to our GitHub repo.
129
+
4. Create a checkpoint for your language by running `pnpm run docs:translation:update <lang> [<commit>]`. A checkpoint is the hash and date of the latest commit when you do the translation. The checkpoint information is stored in the status file `packages/docs/.vitepress/translation-status.json`. _It's crucial for long-term maintenance since all the further translation sync-ups are based on their previous checkpoints._ Usually, you can skip the commit argument because the default value is `main`.
130
+
5. Commit all the changes and create a pull request to our GitHub repo.
130
131
131
-
If you want to maintain a existing translation:
132
+
We will have a paragraph at the top of each translation page that shows the translation status. That way, users can quickly determine if the translation is up-to-date or lags behind the English version.
132
133
133
-
1. (Repo permission required) First of all, make sure there is a _checkpoint_ branch for the language. Usually it's named as `docs-sync-<lang>`. Notice that:
134
-
- This branch is always synced to the commit of the original docs that the latest translation of your language is corresponding to. Like `docs-sync-zh` is always to the commit of the original docs that the latest Chinese translation is corresponding to.
135
-
- Technically, this checkpoint branch should be only updated if the translation is synced to a nearer commit of the original docs. Usually the commit is the HEAD of the `main` branch at that moment.
136
-
2. See what translation you need to do to sync up with the original docs. There are 2 popular ways:
137
-
- Git diff command: e.g. `git diff docs-sync-zh..main packages/docs # > debug.log`, or
138
-
- GitHub Compare page: e.g. https://github.com/vuejs/router/compare/docs-sync-zh...main (only see the changes in `packages/docs/*`)
139
-
3. Create your own branch and start the translation update, following the diff or compare.
140
-
4. Once you have done all above, create a pull request to our GitHub repo.
141
-
- It's highly recommended to commit with message like `docs(<lang>): sync update to <the-latest-commit>`. e.g. `docs(zh): sync update to e008551`.
142
-
5. (Repo permission required) **VERY IMPORTANT**: after the pull request is merged, for the future batch of sync-up, do another merge from the latest commit at that moment to the checkpoint branch. e.g. merge commit `e008551` to branch `docs-sync-zh`.
134
+
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:
143
135
144
-
For more real examples, please check out [all the PRs with title "docs(zh): sync" after 2023-01-01](https://github.com/vuejs/router/pulls?q=is%3Apr+created%3A%3E2023-01-01+docs%28zh%29+sync).
136
+
1. See what translation you need to sync up with the original docs. There are two popular ways:
137
+
1. Via the [GitHub Compare](https://github.com/vuejs/router/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`. 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
138
+
2. Via a local command: `pnpm run docs:translation:compare <lang> [<commit>]`.
139
+
2. Create your own branch and start the translation update, following the previous comparison.
140
+
3. Create a checkpoint for your language by running `pnpm run docs:translation:update <lang> [<commit>]`.
141
+
4. Commit all the changes and create a pull request to our GitHub repo.
142
+
143
+
<!-- TODO: add an example once we have got one -->
145
144
146
145
### Self-host the translation
147
146
148
-
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:
147
+
You can also host the translation on your own. To create one, 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:
148
+
149
+
- Ensure you maintain the _checkpoint_ properly. Also, ensure the _translation status_ is well-displayed on the top of each translation page.
150
+
- Utilize the diff result between the latest official repository and your own checkpoint to guide your translation.
151
+
152
+
Tip: you can add the official repo as a remote to your forked repo. This way, you can still run `pnpm run docs:translation:update <lang> [<commit>]` and `npm run docs:translation:compare <lang> [<commit>]` to get the checkpoint and diff result:
149
153
150
-
1. Ensure you create a _checkpoint branch_ (for example, a branch named sync). This branch should always align with the commit of the original documentation that corresponds to your most recent translation.
151
-
2. Utilize the diff result between the latest official repository and your own by using the git diff command or the GitHub Compare page to guide your translation.
While the discovery of new vulnerabilities is rare, we also recommend always using the latest versions of Vue and its official companion libraries to ensure your application remains as secure as possible.
0 commit comments