Skip to content

Add a dedicated Migration Guide tab for packages #9061

@NattyPluz

Description

@NattyPluz

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.

  1. File Convention: The pub.dev site should check for a top-level file named MIGRATION.md (or alternatively, a file specified in pubspec.yaml, though a simple convention is better).
  2. New Tab: If MIGRATION.md exists in the package archive, a new tab labeled Migration Guide should appear next to the existing tabs (Readme, Changelog, Example, etc.).
  3. Content: The content of this tab would be the rendered Markdown from the MIGRATION.md file.

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions