From: Eduardo San Martin Morote Date: Fri, 15 Dec 2023 06:08:23 +0000 (+0100) Subject: chore: rewording [skip ci] X-Git-Tag: v4.3.0~44 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1bbf2a990c0e57e214128b55eb0eb3c4b07391cc;p=thirdparty%2Fvuejs%2Frouter.git chore: rewording [skip ci] --- diff --git a/.github/contributing.md b/.github/contributing.md index 0f488556..523323d6 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -17,7 +17,7 @@ Hi! I'm really excited that you are interested in contributing to Vue Router. Be ## Pull Request Guidelines -- Checkout a topic branch from a base branch, e.g. `main`, and merge back against that branch. +- Check out a topic branch from a base branch, e.g. `main`, and merge back against that branch. - If adding a new feature: @@ -26,7 +26,7 @@ Hi! I'm really excited that you are interested in contributing to Vue Router. Be - 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)`. + - 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)`. - 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`. @@ -48,7 +48,7 @@ After cloning the repo, run: pnpm install # install the dependencies of the project ``` -A high level overview of tools used: +A high-level overview of tools used: - [TypeScript](https://www.typescriptlang.org/) as the development language - [Rollup](https://rollupjs.org) for bundling @@ -63,7 +63,7 @@ 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. +The `play` script starts a playground project located at `playground/`, allowing you to test things on a browser. ```bash pnpm play @@ -91,51 +91,51 @@ $ pnpm jest --watch 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](https://developer.mozilla.org/en-US/docs/Web/API/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/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. +- `src/utils`: contains small utility functions used across other router +- `src/router`: contains the router creation, navigation execution, matcher use, and 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. +- `src/index` contains all public APIs as exports. +- `src/types`: contains global types used across multiple router sections. ## Contributing Tests 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: - 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. +- 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. - 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 +- 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 `` sub-folder(s): +All the documentation files can be found in `packages/docs`. It contains the English markdown files while translation(s) are stored in their corresponding `` sub-folder(s): - [`zh`](https://github.com/vuejs/router/tree/main/packages/docs/zh): Chinese translation. -Besides that, the `.vitepress` sub-folder is used to put the config and theme, including the i18n information. +Besides that, the `.vitepress` sub-folder contains 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: +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: ### Translate in a `` 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 `` sub-folder for your translation. -2. Modify the i18n config in `.vitepress` sub-folder. +2. Modify the i18n configuration in the `.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 []`. 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`. +4. Create a checkpoint for your language by running `pnpm run docs:translation-status []`. 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`. 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. +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. 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](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`. 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 []`. +1. See what translation you need to sync up with the original docs. There are two popular ways: + 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 + 2. Via a local command: `pnpm run docs:compare-to-translate []`. 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 []`. 4. Commit all the changes and create a pull request to our GitHub repo. @@ -144,12 +144,12 @@ Speaking of the up-to-date translation, we also need good long-term maintenance ### 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: +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: -- Ensure you maintain the _checkpoint_ properly. And also ensure the _translation status_ is well-displayed on the top of each translation page. +- Ensure you maintain the _checkpoint_ properly. 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 []` and `npm run docs:compare-to-translate []` to get the checkpoint and diff result: +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 []` and `npm run docs:compare-to-translate []` to get the checkpoint and diff result: ```bash # prepare the upstream remote