Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add onboarding & release info to OneLocBuild doc #7374

Merged
merged 6 commits into from
May 12, 2021
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 60 additions & 2 deletions Documentation/OneLocBuild.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down