diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 50cfc2845db..9429ac4482a 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -9,6 +9,64 @@ repo. Xliff-Tasks will continue to be used in addition to OneLocBuild. To make OneLocBuild easier to use, we have integrated the task into Arcade. This integration is a job template ([here](/eng/common/templates/job/onelocbuild.yml)) that is described in this document. +## Onboarding to OneLocBuild Using Arcade + +Onboarding to OneLocBuild is a simple process: + +1. Ensure that your repository is on the latest version of Arcade. +2. Create a test branch (e.g. `LocalizationTests`) in your repository and add the following job template to your YAML: +```yaml +- template: /eng/common/templates/job/onelocbuild.yml + parameters: + CreatePr: false +``` +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). Include the link to the + test build you've done. +5. The loc team will generate an LCL package for you and send you its ID. It will be something like + `LCL-JUNO-PROD-YOURREPO`. +6. Change your YAML (subbing `'LCL-JUNO-PROD-YOURREPO'` for the package ID given to you) to: +```yaml +- template: /eng/common/templates/job/onelocbuild.yml + parameters: + LclSource: lclFilesfromPackage + LclPackageId: 'LCL-JUNO-PROD-YOURREPO' +``` +7. Merge the changes to your main branch and then open a + [repo modification ticket](https://ceapex.visualstudio.com/CEINTL/_workitems/create/Loc%20Request) with the loc team + to let them know to retarget the branch. + +As of 12 May 2021, if your repository is mirrored to internal with Maestro, you will also need to keep +`CreatePr: false` in your YAML. Currently, OneLocBuild does not support our scenario. The step to create a PR back to +GitHub expects a GitHub repository with the same name as the internal repo, so the step to create PRs fails, +breaking the build. Thus, we turn off automated PR creation to skip this step and we are creating PRs manually prior to +releases as a workaround. Please [get a hold of Engineering Services](https://github.com/dotnet/core-eng/wiki/How-to-get-a-hold-of-Engineering-Servicing) +so that you can be updated when automated PR creation is supported. + +## Releasing with OneLocBuild Using Arcade + +**Note: The SLA for translations is one week. Please allow at least two weeks from the release for this process.** + +### If You're Releasing from `main` +If you're releasing from the main branch of your repository, all that you need to do is ensure that you're merging +PRs from OneLocBuild as they are made and that you allow the translator SLA for any new strings prior to the release. + +### If You're Releasing from a Branch Other Than `main` (Including Servicing Branches) +If you're releasing from any other branch (including servicing branches), you must do the following: + +1. Add the OneLocBuild job template to the pipeline YAML of the release branch +2. Open a [repo modification ticket](https://ceapex.visualstudio.com/CEINTL/_workitems/create/Loc%20Request) with the + loc team at least two weeks before the release and request that they re-target your repository to the release branch. +4. Merge the OneLocBuild PRs to your release branch. +5. After the release, open another repo modification ticket to re-target your repository to the `main` branch again. + +## Filing Issues for Translation Issues + +File a translation issue ticket with the localization team (see documentation [here](https://dev.azure.com/ceapex/CEINTL/_wiki/wikis/CEINTL.wiki/1361/Provide-Enough-Information-in-DevRel-Feedback-Ticket)). + +# Technical Documentation + ## LocProject.json Index File The core component of OneLocBuild is the LocProject.json file. This file is an index file containing references to @@ -30,8 +88,8 @@ which include `test.xlf` in its name. } ``` -The selected files are then added to a generated LocProject.json file. At this point, template currently provides two options -for how to proceed. +The selected files are then added to a generated LocProject.json file. At this point, template currently provides two +options for how to proceed. ### Build-Time Generation