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.
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.
First, add the images to the flutter_template_images package:
- Fork the flutter/packages repo on GitHub.
- 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 theflutter
tool. They should not include a.img.tmpl
suffix. - Update the version in
pubspec.yaml
. For new assets, increment the minor version in themajor.minor.patch
version number; for updates to existing assets, increment the patch version. - Add new heading for this version in
CHANGELOG.md
and add a line describing your change. Follow the Changelog Style guidelines. - Commit your changes and send a pull request.
- 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.
Once the updated package has been published on Pub, roll your changes into the main Flutter repository.
- Fork the flutter/flutter repo on GitHub.
- Edit
packages/flutter_tools/lib/src/commands/update_packages.dart
and update the pinned version number for theflutter_template_images
to the new version. - From within the repo directory, run
flutter update-packages --force-upgrade
. - 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 thetemplates
directory of theflutter_tools
package. - Edit
packages/flutter_tools/templates/template_manifest.json
and add an entry for each file you added, including the.img.tmpl
suffix. - Commit your changes, and perform a test run to be sure they're emitted successfully by the
flutter
tool. - Assuming everything looks good, send a pull request.
(This page is referenced by an error message in the Flutter presubmit checks.)
- Home of the Wiki
- Roadmap
- API Reference (stable)
- API Reference (main)
- Glossary
- Contributor Guide
- Chat on Discord
- Design documents
- Code of Conduct
- Issue triage reports (latest)
- Our Values
- Tree hygiene
- Issue hygiene and Triage
- Style guide for Flutter repo
- Project teams
- Contributor access
- What should I work on?
- Popular issues
- Running and writing tests
- Release process
- Flutter Framework Gardener Rotation
- Rolling Dart
- Manual Engine Roll with Breaking Commits
- Updating Material Design Fonts & Icons
- Postmortems and Retrospectives
- Hotfix Documentation Best Practices
- In case of emergency
- Landing Changes With Autosubmit
- Setting up the Framework development environment
- The Framework architecture
- API Docs code block generation
- Running examples
- Using the Dart analyzer
- The flutter run variants
- Test coverage for package:flutter
- Writing a golden-file test for package:flutter
- Managing template image assets
- Setting up the Engine development environment
- Compiling the engine
- Debugging the engine
- Using Sanitizers with the Flutter Engine
- Testing the engine
- The Engine architecture
- Flutter's modes
- Crashes
- more...
- Setting up the Packages development environment
- Plugins and Packages repository structure
- Contributing to Plugins and Packages
- Understanding Packages tests
- Plugin Tests
- Releasing a Plugin or Package
- more...