diff --git a/.github/contributing.md b/.github/contributing.md index ad26f287b..d9e1fd2ba 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -109,6 +109,36 @@ Unit tests are located inside `__tests__`. Consult the [Jest docs](https://jestj - 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 has a English version by default, and translation(s) in corresponding `` sub-folder(s): + +- `zh`: Chinese translation. + +Besides that, the `.vitepress` sub-folder is used to put the config and theme, including the i18n information. + +If you want to start to translate the docs in a new language: + +1. Create the corresponding `` 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. Once you have done all above, create a pull request to our GitHub repo. + +If you want to maintain a existing translation: + +1. (Repo permission required) First of all, make sure there is a _checkpoint_ branch for the language. Usually it's named as `docs-sync-`. Notice that: + - 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. + - 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. +2. See what translation you need to do to sync up with the original docs. There are 2 popular ways: + - Git diff command: e.g. `git diff docs-sync-zh..main packages/docs # > debug.log`, or + - GitHub Compare page: e.g. https://github.com/vuejs/router/compare/docs-sync-zh...main (only see the changes in `packages/docs/*`) +3. Create your own branch and start the translation update, following the diff or compare. +4. Once you have done all above, create a pull request to our GitHub repo. + - It's highly recommended to commit with message like `docs(): sync update to `. e.g. `docs(zh): sync update to e008551`. +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`. + +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). + ## Credits Thank you to all the people who have already contributed to Vue Router!