README.md

# Flutter LUCI Service Configurations

Contains configuration and tools related to Flutter's build infrastructure.

Configuration is generated by `lucicfg`, which is part of `depot_tools`. Rather
than updating the individual .cfg files, updates should be made to
`config/main.star`. That file can then be run to regenerate the configuration.

## Updating the configuration

- Edit the desired `.star` files (do not edit `.cfg` files; those are generated).
- Execute `./config/main.star`.
- Observe that the `.cfg` files have been updated (e.g. via `git status`).
- Create a pull request containing changes both to the `.star` files and `.cfg` files.
- Review and submit the pull request as normal.
- Changes propagate to LUCI automatically. Go to [LUCI config UI][3]
  to check that new changes have been applied.

## Adding new framework test shards

This section talks about test shards defined in [dev/bots/test.dart][1] used to
split framework tests into smaller chunks that can be tested in parallel. This
does _not_ refer to [LUCI/Swarming][4] shards.

When you add a new shard it does not automatically run in LUCI. To add it to
LUCI you need to add a new builder in the [framework_config.star][2]. Typically,
you'll add two builders, one "try" builder that tests PRs, and one "prod" builder
that tests submitted PRs on the master branch.

Here's an example of a "try" builder:

```
    common.linux_try_builder(
        name = "Linux web_tests|web_tests",
        recipe = "flutter/flutter",
        repo = repos.FLUTTER,
        list_view_name = list_view_name,
        properties = {
            "shard": "web_tests",
            "subshards": ["0", "1", "2", "3", "4", "5", "6", "7_last"],
            "dependencies": [{"dependency": "android_sdk"}, {"dependency": "chrome_and_driver"}, {"dependency": "goldctl"}],
        },
        caches = [
            swarming.cache(name = "pub_cache", path = ".pub_cache"),
            swarming.cache(name = "android_sdk", path = "android29"),
        ],
    )
```

The easiest way to add a new one is to copy an existing builder and tweak the
parameters.

### Testing new shards

As of today, it is not possible to test configuration changes until after they
propagated to LUCI. One way to mitigate the risk of breakage is to run your test
shard using an existing builder. To do that, find a builder in one of the
`.star` files (e.g. `framework_config.star`) that satisfies the dependencies of
the new test shard, then use the `led` tool (bundled with `depot_tools`) to run
it.

For example, let's say you are adding an integration test shard for web, and the
new shard needs a Linux builder with Chrome and ChromeDriver in order to run.
Luckily, there's already the `Linux web_tests` builder that satisfies these
dependencies. To test the new shard, use the `Linux web_tests` builder, but ask
it to run a different shards and/or subshard. Let's say the new test shard is
called "foo", it has 3 subshards (0, 1, 2_last) and it's currently staged in pull
request 99999. You can run it using the following `led` command:

```
led get-builder "luci.flutter.try:Linux web_tests" \
  | led edit -pa git_ref='refs/pull/99999/head' \
  | led edit -pa git_url='https://github.com/flutter/flutter' \
  | led edit -pa shard='foo' \
  | led edit -pa subshard='1' \
  | led launch
```

## Forcing the propagation of these configurations

One may speed up the propagation of the
new configuration files by visiting the
[luci-config web ui][3], logging in, and
searching for projects/flutter. from there, one may click on the
projects/flutter search result and click the download icon to force an update.

[1]: https://github.com/flutter/flutter/blob/master/dev/bots/test.dart
[2]: https://flutter.googlesource.com/infra/+/refs/heads/main/README.md
[3]: https://luci-config.appspot.com/#/projects/flutter
[4]: https://www.chromium.org/developers/testing/isolated-testing/infrastructure