feat(docs): Guide for syncing translation repos (#21753)

* add the create script * description of env * add reference to comment. * edit README * more information in README * update create script * add pulling logic * add maintainers to organization * add comment * add discord link * add more discord references * Move script explanations to the README * WIP sync script * add stuff * WIP sync * WIP sync * WIP sync * WIP sync * WIP outline of sync script * WIP outline of sync script * get closer to my goal * get closer to my goal * try to do a line counting function * try to do a line counting function * more templates * resolve conflicts * resolve conflicts function * resolve conflicts function * more work on sync script * get the thing to work hopefully * get it to work * get it to work * update stuff on sync * get rid of parse-diff * rever codesandbox * add FIXMEs * fix new repo cloning issue * more stuff * fix issues with deleted file conflicts * add documentation on sync behavior * no github comments * Create another pull request with non-conflicts * add FIXME * fix number issue * almost done! * todo * remember to switch to master branch * all * fix headings on sync guide * add more guide info * extraneous comment * information on the second pull request * add guide * remove fixme * add logging * more silencing * remove script info * add more sync docs * more information on syncing * Update docs/contributing/translation/sync-guide.md Co-Authored-By: Aisha Blake <aisha@gatsbyjs.com> * Update docs/contributing/translation/sync-guide.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> * Update docs/contributing/translation/sync-guide.md Co-Authored-By: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: Aisha Blake <aisha@gatsbyjs.com> Co-authored-by: Michael <184316+muescha@users.noreply.github.com> Co-authored-by: GatsbyJS Bot <mathews.kyle+gatsbybot@gmail.com>
gatsbyjs · Mar 4, 2020 · b2c0700 · b2c0700
1 parent 7fe65c7
commit b2c0700
Showing 1 changed file with 156 additions and 4 deletions.
diff --git a/docs/contributing/translation/sync-guide.md b/docs/contributing/translation/sync-guide.md
@@ -1,13 +1,42 @@
 ---
 title: Keeping Translations Up-to-date
-issue: https://github.com/gatsbyjs/gatsby/issues/21250
 ---
 
-Periodically, gatsbybot will create pull requests to keep translations repos up-to-date with the original English source. Make sure to review these PRs to ensure that your translation remains accurate.
+Periodically, gatsbybot will update your translation repo to be up-to-date with the current English repo. If there is an update to a page that is already translated, gatsbybot will create a pull request listing the conflicts between translation and the new English content. Resolving these conflicts and merging these pull requests is essential to keeping your translation repo up-to-date.
 
-> Note: the bot doesn't work yet but will come soon. Until then, see the next section to learn how to manually sync your repo.
+## Resolving sync pull requests
 
-### Manually syncing translation repos
+When it runs the sync script, gatsbybot will create up to two pull requests. One is named:
+
+```text
+(sync) Sync with gatsby-i18n-source @ {hash}
+```
+
+This pull request contains updates to all files that do not have conflicts. This includes files that have not been translated yet, and files that have been added to Gatsby. In general, these files can be merged in as-is, but it may be worth looking over them to see if there are any new files that were added to the repo that need to be translated.
+
+> 🚨NOTE: Make sure you do **NOT** choose the ["Squash and merge"](https://help.github.com/en/github/administering-a-repository/about-merge-methods-on-github#squashing-your-merge-commits) option when merging this pull request. Squashing will result in Git losing information about the sync, and will lead to extra conflicts on your next sync. Always make sure that you use the "Merge pull request" option.
+
+The second pull request will be named:
+
+```text
+(sync) Resolve conflicts with gatsby-i18n-source @ {hash}
+```
+
+This pull request will list files that have conflicts between translated content and English content. These updates will appear as Git conflicts:
+
+```diff
++ <<<<<<< HEAD
+Ahora, el componente `Box` estará al pendiente del estado de la transición de la página que es hijo, y aparecerá de entrada/salida en consecuencia.
++ =======
++ Now, the `Box` component will be aware of whether the page it's a child of is mounting or unmounting, and it will fade in/out accordingly.
++ >>>>>>> 90932a06db2e297cf416552b84e48b4b82e56fbc
+```
+
+Here, the top block is the original translated line and the bottom block is the updated source content. You should resolve these conflicts by updating the top block to reflect the content of the bottom block.
+
+You may use whatever tools you like to resolve these conflicts: the GitHub UI, the command line, or a code editor like VS Code. See the [Common types of merge issues](#common-types-of-merge-issues) section for how to resolve various conflicts.
+
+## Manually syncing translation repos
 
 If for whatever reason you'd like to manually sync your translation repo, you can do so by running these commands:
 
@@ -17,3 +46,126 @@ git pull source master
 ```
 
 Fix all [merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line) and create a pull request to finish the merge.
+
+## Common types of merge issues
+
+### Frontmatter changes
+
+This type of conflict reflects a change to the [frontmatter]() of a document.
+
+Removing a field:
+
+```diff
++ <<<<<<<
+title: my stub article
+issue: #12345
++ =======
++ title: My Stub Article
++ >>>>>>>
+```
+
+Adding a field:
+
+```diff
++ <<<<<<<
+title: Documentacion
++ =======
++ title: Docs
++ description: The one-stop shop for documentation in Gatsby!
++ >>>>>>>
+```
+
+Changing a field:
+
+```diff
++ <<<<<<<
+title: My old title
++ =======
++ title: My new title
++ >>>>>>>
+```
+
+### Typos fixes
+
+Sometimes there is a typo or grammatical error in the English source that gets fixed in an update.
+
+```diff
+- Let's all use Gabsty!
++ Let's all use Gatsby!
+```
+
+```diff
+- Gatsby is awesome framework!
++ Gatsby is an awesome framework!
+```
+
+Since these typos most likely don't exist in the translated version, you can most likely use the translated version as-is.
+
+### Formatting changes
+
+Sometimes the only difference is a change in formatting, such as adding back-ticks to annotate something as code, or changing the level of headings:
+
+```diff
+- Sass files have the extension .scss.
++ Sass files have the extension `.scss`.
+```
+
+```diff
+- #### Formatting changes
++ ### Formatting changes
+```
+
+The only necessary change is to ensure the translated content carries over these formatting updates.
+
+### Link updates
+
+These changes involve updating the URL of a link:
+
+```diff
+- Please see our [plugins page](/packages).
++ Please see our [plugins page](/plugins).
+```
+
+```diff
+- Check out our [GitHub](http://github.com/gatsbyjs/gatsby)
++ Check out our [GitHub](https://github.com/gatsbyjs/gatsby)
+```
+
+Resolve these changes by updating the link.
+
+### Content changes
+
+Sometimes, the content of the source page is actually updated and needs a translation. Make sure to read the change carefully and change the translation to match its meaning.
+
+### Conflicts in untranslated files
+
+Sometimes, you may find conflicts in files that haven't been translated yet:
+
+```diff
++ <<<<<<<
+This is old English content.
++ =======
++ This is new English content.
++ >>>>>>>
+```
+
+This is usually because of a previous improper merge (for example, using the "Squash and merge" option). In this case, it's usually alright to accept the new content. In VS Code, this is done using the "Accept Incoming Change" option:
+
+```diff
+- This is old English content.
++ This is new English content.
+```
+
+## Creating a separate pull request
+
+If a page has significant changes, it may be worth splitting it into its own pull request:
+
+```shell
+git checkout conflicts-9032a0
+git checkout -b sync-tutorial-0
+# Fix conflicts in /docs/tutorial/part-zero/index.md
+git commit -am "Fix conflicts in tutorial part zero"
+git push -u origin sync-tutorial-0
+```
+
+Once the branch is pushed, create a pull request for branch `sync-tutorial-0` with `conflicts-9032a0` as the base branch.