-
Notifications
You must be signed in to change notification settings - Fork 166
Description
Migrating between major versions of a package (e.g., from 1.x.x to 2.x.x) often involves breaking changes that require significant effort from the user. While the CHANGELOG.md is required and lists changes, it often mixes new features, bug fixes, and breaking changes, making it difficult to extract a clear migration path.
I propose adding a dedicated Migration Guide tab to the package page on pub.dev.
- File Convention: The pub.dev site should check for a top-level file named
MIGRATION.md(or alternatively, a file specified inpubspec.yaml, though a simple convention is better). - New Tab: If
MIGRATION.mdexists in the package archive, a new tab labeledMigration Guideshould appear next to the existing tabs (Readme,Changelog,Example, etc.). - Content: The content of this tab would be the rendered Markdown from the
MIGRATION.mdfile.
This dedicated location would allow package authors to write comprehensive, version-specific guides (e.g., "Migrating from 1.x to 2.x") without cluttering the main README.md or the general-purpose CHANGELOG.md.
Additional Context
This feature would significantly improve the maintainability score and overall user experience for consumers of Dart/Flutter packages, especially large ones that iterate quickly. It encourages a best practice of providing clear migration instructions, leading to faster adoption of new major versions.