Managing template image assets

Image assets used in templates in the flutter tool are maintained in the flutter_template_images package on Pub.dev and are not checked into the main flutter/flutter repository.

Flutter's presubmit checks prevent binaries from being checked in to the repository. Binary files add significant size to the repository and produce large diffs when updated. This negatively impacts Flutter users when running flutter upgrade. Downloading a pub package does not involve a full sync of the git history, and is therefore significantly lighter weight.

Adding/Updating template image assets

In order to add or update image assets, two patches are required: one to the flutter/packages repository and one to the flutter/flutter repository.

The flutter_template_images package repository contains a templates directory laid out identically to the templates directory in the flutter_tools package in the main repository. Assets are first added to the flutter_template_images repo, which is then rolled into the main repository, where the template files and manifest must be updated.

Add the assets to flutter_template_images

First, add the images to the flutter_template_images package:

  1. Fork the flutter/packages repo on GitHub.
  2. Add the images at the relevant path under the templates directory. Filenames should be the exact final filenames as they will appear in a project generated by the flutter tool. They should not include a .img.tmpl suffix.
  3. Update the version in pubspec.yaml. For new assets, increment the minor version in the major.minor.patch version number; for updates to existing assets, increment the patch version.
  4. Add new heading for this version in CHANGELOG.md and add a line describing your change. Follow the Changelog Style guidelines.
  5. Commit your changes and send a pull request.
  6. Once your changes are landed, a post-submit job will automatically publish the new version on Pub. You can verify this has occurred under the Versions tab of the flutter_template_images page.

Update Flutter package dependencies

Once the updated package has been published on Pub, roll your changes into the main Flutter repository.

  1. Fork the flutter/flutter repo on GitHub.
  2. Edit packages/flutter_tools/lib/src/commands/update_packages.dart and update the pinned version number for the flutter_template_images to the new version.
  3. From within the repo directory, run flutter update-packages --force-upgrade.
  4. For each image that you added to flutter_template_images, add a zero-byte file with a .img.tmpl suffix in the corresponding location under the templates directory of the flutter_tools package.
  5. Edit packages/flutter_tools/templates/template_manifest.json and add an entry for each file you added, including the .img.tmpl suffix.
  6. Commit your changes, and perform a test run to be sure they're emitted successfully by the flutter tool.
  7. Assuming everything looks good, send a pull request.

(This page is referenced by an error message in the Flutter presubmit checks.)