From 0c78864d68c2ce292fa6d7e3be6a7271df0d789d Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Tue, 11 May 2021 14:56:32 -0700 Subject: [PATCH 1/6] Add onboarding & release info to OneLocBuild doc --- Documentation/OneLocBuild.md | 52 ++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 50cfc2845db..18552332dc1 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -9,6 +9,54 @@ 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. Send the test run of that pipeline to Cristiano Suzuki and ask for an LCL package. +5. Cristiano will generate an LCL package for you and send you its name. It will be something like + `LCL-JUNO-PROD-YOURREPO`. +6. Change your YAML (subbing `'LCL-JUNO-PROD-YOURREPO'` with the package ID Cristiano gave 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 let Cristiano know to re-target the package to your main branch. + +*Note: 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, so PRs are being made* +*manually before release. Please notify Jon Fortescue (jofortes) if you're following this step so that you can* +*be updated when PR creation is supported.* + +## Releasing with OneLocBuild Using Arcade + +**NB: 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 task to the pipeline YAML of the release branch +2. Contact Cristiano Suzuki at least two weeks before the release and tell him to re-target your repository to the + release branch. +3. Merge the OneLocBuild PRs to your release branch. +4. After the release, tell Cristiano to re-target your repository to the `main` branch again. + +# 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 +78,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 From 796d01586e0533a632b1ad3074daa7b6dbc2bef1 Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Wed, 12 May 2021 11:25:22 -0700 Subject: [PATCH 2/6] Update with ticket information. --- Documentation/OneLocBuild.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 18552332dc1..1b836023bb5 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -21,17 +21,21 @@ Onboarding to OneLocBuild is a simple process: CreatePr: false ``` 3. Run the pipeline you want to use OneLocBuild on your test branch. -4. Send the test run of that pipeline to Cristiano Suzuki and ask for an LCL package. -5. Cristiano will generate an LCL package for you and send you its name. It will be something like +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 name. It will be something like `LCL-JUNO-PROD-YOURREPO`. -6. Change your YAML (subbing `'LCL-JUNO-PROD-YOURREPO'` with the package ID Cristiano gave you) to: +6. Change your YAML (subbing `'LCL-JUNO-PROD-YOURREPO'` with 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 let Cristiano know to re-target the package to your main branch. +7. Merge the changes to your main branch and then let 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. *Note: 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, so PRs are being made* @@ -50,10 +54,14 @@ PRs from OneLocBuild as they are made and that you allow the translator SLA for If you're releasing from any other branch (including servicing branches), you must do the following: 1. Add the OneLocBuild task to the pipeline YAML of the release branch -2. Contact Cristiano Suzuki at least two weeks before the release and tell him to re-target your repository to the - release branch. -3. Merge the OneLocBuild PRs to your release branch. -4. After the release, tell Cristiano to re-target your repository to the `main` branch again. +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 tell them to re-target your repository to the release branch. +4. Merge the OneLocBuild PRs to your release branch. +5. After the release, tell Cristiano 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 From a77a724480ce723f8e228c3c57ea2abda71739b6 Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Wed, 12 May 2021 14:35:48 -0700 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Michael Stuckey --- Documentation/OneLocBuild.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 1b836023bb5..3c4a9c33566 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -24,7 +24,7 @@ Onboarding to OneLocBuild is a simple process: 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 name. It will be something like +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'` with the package ID given to you) to: ```yaml @@ -33,7 +33,7 @@ Onboarding to OneLocBuild is a simple process: LclSource: lclFilesfromPackage LclPackageId: 'LCL-JUNO-PROD-YOURREPO' ``` -7. Merge the changes to your main branch and then let open a +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. @@ -55,7 +55,7 @@ If you're releasing from any other branch (including servicing branches), you mu 1. Add the OneLocBuild task 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 tell them to re-target your repository to the release branch. + 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, tell Cristiano to re-target your repository to the `main` branch again. From 7276801090a3e6a71b7de34bb107437336deb6b8 Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Wed, 12 May 2021 14:47:57 -0700 Subject: [PATCH 4/6] Updates from feedback --- Documentation/OneLocBuild.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 3c4a9c33566..37129e4edb9 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -26,7 +26,7 @@ Onboarding to OneLocBuild is a simple process: 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'` with the package ID given to you) to: +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: @@ -37,14 +37,14 @@ Onboarding to OneLocBuild is a simple process: [repo modification ticket](https://ceapex.visualstudio.com/CEINTL/_workitems/create/Loc%20Request) with the loc team to let them know to retarget the branch. -*Note: 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, so PRs are being made* -*manually before release. Please notify Jon Fortescue (jofortes) if you're following this step so that you can* -*be updated when PR creation is supported.* +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, so we are PRs are being made +manually before release 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) +if you're following this step so that you can be updated when PR creation is supported. ## Releasing with OneLocBuild Using Arcade -**NB: The SLA for translations is one week. Please allow at least two weeks from the release for this process.** +**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 @@ -53,11 +53,11 @@ PRs from OneLocBuild as they are made and that you allow the translator SLA for ### 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 task to the pipeline YAML of the release branch +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, tell Cristiano to re-target your repository to the `main` branch again. +5. After the release, open another repo modification ticket to re-target your repository to the `main` branch again. ## Filing Issues for Translation Issues From 73663c13b26513f404a40cb6e3d33e0b3ebc0a02 Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Wed, 12 May 2021 14:54:47 -0700 Subject: [PATCH 5/6] Update section on PR creation workaround --- Documentation/OneLocBuild.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 37129e4edb9..8abf8e212a1 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -38,9 +38,9 @@ Onboarding to OneLocBuild is a simple process: 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, so we are PRs are being made -manually before release 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) -if you're following this step so that you can be updated when PR creation is supported. +`CreatePr: false` in your YAML. Currently, OneLocBuild does not support our scenario, so the step to create PRs fails, +breaking the build. As a workaround, we are creating PRs manually prior to releases. 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 From d20884dc96a5221ef8a5178aea065adaa4fc18f6 Mon Sep 17 00:00:00 2001 From: Jon Fortescue Date: Wed, 12 May 2021 14:57:04 -0700 Subject: [PATCH 6/6] Update PR creation paragraph more --- Documentation/OneLocBuild.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/OneLocBuild.md b/Documentation/OneLocBuild.md index 8abf8e212a1..9429ac4482a 100644 --- a/Documentation/OneLocBuild.md +++ b/Documentation/OneLocBuild.md @@ -38,8 +38,10 @@ Onboarding to OneLocBuild is a simple process: 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, so the step to create PRs fails, -breaking the build. As a workaround, we are creating PRs manually prior to releases. Please [get a hold of Engineering Services](https://github.com/dotnet/core-eng/wiki/How-to-get-a-hold-of-Engineering-Servicing) +`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