From 52476e9119685f8effc7f79f0a5982e9d98ef086 Mon Sep 17 00:00:00 2001
From: Jon Fortescue <jofortes@microsoft.com>
Date: Tue, 15 Jun 2021 13:09:16 -0700
Subject: [PATCH] Incorporate feedback on OneLocBuild doc (#7522)

---
 Documentation/OneLocBuild.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md
index 9a5b7b4f890..edcd824c5dc 100644
--- a/Documentation/OneLocBuild.md
+++ b/Documentation/OneLocBuild.md
@@ -20,6 +20,12 @@ Onboarding to OneLocBuild is a simple process:
   parameters:
     CreatePr: false
 ```
+Note: If you are running your PR builds and official builds off of the same definition and are on dnceng,
+you will want to conditionalize this step with the following:
+```yaml
+- ${{ if and(ne(variables['System.TeamProject'], 'public'), notin(variables['Build.Reason'], 'PullRequest')) }}:
+```
+To prevent OneLocBuild from running in the public project where it will fail.
 3. Run the pipeline you want to use OneLocBuild on your test branch.
 4. Open a ticket with the localization team using
    [this template](https://ceapex.visualstudio.com/CEINTL/_workitems/create/Loc%20Request?templateId=60b0dcf9-9892-4910-934e-d5becddd1bc1&ownerId=c2e38d3d-0e9e-429f-955d-6e39fc6f0457).
@@ -28,17 +34,31 @@ Onboarding to OneLocBuild is a simple process:
    `LCL-JUNO-PROD-YOURREPO`.
 6. Change your YAML (subbing `'LCL-JUNO-PROD-YOURREPO'` for the package ID given to you) to:
 ```yaml
-- {{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
+- ${{ if eq(variables['Build.SourceBranch'], 'refs/heads/main') }}:
   - template: /eng/common/templates/job/onelocbuild.yml
     parameters:
       LclSource: lclFilesfromPackage
       LclPackageId: 'LCL-JUNO-PROD-YOURREPO'
 ```
+Make sure to remove the `CreatePr: false` line from step 2. Additionally, if you added the YAML condition from step
+2, make sure that your new YAML condition now looks like:
+```yaml
+- ${{ if and(and(ne(variables['System.TeamProject'], 'public'), notin(variables['Build.Reason'], 'PullRequest')), eq(variables['Build.SourceBranch'], 'refs/heads/main')) }}:
+```
+
 7. If using a mirrored repository (your code is mirrored to a trusted repository which your official build uses),
    add the following parameter to your YAML (subbing e.g. `sdk` for the value):
 ```yaml
-    MirrorRepo: {{name of your GitHub repository}}
+    MirrorRepo: name of your GitHub repository, e.g. 'sdk'
 ```
+This naming might be confusing for repositories using code mirroring through Maestro, as typically the
+"mirror repository" refers to the trusted Azure DevOps repository our GitHub repositories mirror to.
+In this case, however, it refers to the repository that _mirrors to_ the Azure DevOps repository
+that the official build is based on.
+
+As a further note, the template by default assumes that your mirror repository is located in the dotnet GitHub
+organization. If that is not the case, you will need to specify `GitHubOrg` as well.
+
 8. Merge the changes to your main branch and then open a
    [repo modification ticket](https://ceapex.visualstudio.com/CEINTL/_workitems/create/Loc%20Request?templateId=415a0569-35ed-45c3-9321-8b1affff1f52&ownerId=c2e38d3d-0e9e-429f-955d-6e39fc6f0457)
    with the loc team to let them know to retarget the branch.