Guidelines for responding to private pull requests from localization team

Time to time, Loc team receives queries from translators about English (EN) source content in articles during translation. They can be about possible typos, terminology issues, formatting issues, or request for clarification for meaning or context of the source text. We agreed with content manager team to utilize the Pull Request (PR) to communicate these queries directly with the writers. Loc team should submit PR to EN private repository, instead of public repo.

What Loc team will do: Loc team will only submit PR to articles that are released to public (articles that are merged to master branch).

What Loc team will not do: Loc team will not merge the Loc PR. Loc team will notify the writer when submitting the Loc PR by mentioning the 'author' name in comments section. If the writer does not respond, Loc team will simply re-send notification to the writer through the Loc PR every week, which may be escalated to the manager to follow up.

  • Loc team will not #sign-off the Loc PR unless writer authorizes in PR comment or e-mail.
  • If the ms.author value is out of date, please notify the correct article owner and Loc PR escalator.

Types of PR from Localization team

  • Type 1: PR for simple fix If the query is clearly about formatting issue in metadata where fix is straight forward, then Loc team will submit a PR and #sign-off (authorized by Tyson Nevil). If the query is clearly about simple typo or formatting issue where fix is straight forward, then Loc team will submit a PR that contains suggested fix in the article body. Writer will need to either confirm the suggested fix and "#sign-off" on the Loc PR, or reply with comment otherwise.

  • Type 2: PR for question requiring answer and possible fix If the query is about possible source text issue where fix/update may or may not be needed, then Loc team will add a comment tag in the article body near the related text as '' containing the question. There will be no suggested fix in the article body. Loc team will also provide additional info or explanation in the PR Comment section if needed.

    Note

    If you are seeing pull requests come through your public repositories from Microsoft employees that are trusted contributors, you should encourage them to become an internal contributor. This is mainly because internal repositories typically offer better quality enabled thorough automated validation and preview features, especially for large contributions.

Step-by-Step workflow

Type 1: PR for simple fix Writer receives the PR with the potential fix (Loc team make sure the fix passes the Validation), then:

  • If agree with the suggested fix, then comment "#sign-off" on the Loc PR;
  • If agree to fix but need further modification, then please correct the Loc fix (please refer to the Type2 - 2nd point below);
  • If do not agree with the fix at all (no fix needed), then please respond in PR Comment section.

Type 2: PR for question requiring answer and possible fix Writer receives the PR with the comment tag only, then:

  1. If no content needs to be updated, writer only respond to the question with answer by leaving a comment in the 'Conversation' tab.
  2. If the writer needs to fix/update the content as a result: ​​​ - Submitting PR to the original loc PR/branch, please refer to Make changes to another person's pending pull request "Method 1"

    Note

    Then Loc PM will merge writer's PR to the original PR, verify the CI validation with writer's fix and "#sign-off" on the Loc PR, so it will be ready to merge to master branch.

  3. After the writer responds to the PR, if no fix is needed, then Loc PM will confirm the response and close the PR.

Note

After Loc PR was submitted, if content of the same article is updated before responding to the Loc PR, then there may be a PR conflict. In that case, please still respond to the Loc PR with either request for Loc team to create a new PR based on the updated article, or explaining why fix is not needed.