Dart Package Maintenance

Guidelines for maintaining Dart packages in alignment with Dart team best practices.

Versioning

Semantic Versioning

• Major: Breaking changes.

• Minor: New features (non-breaking API changes).

• Patch: Bug fixes, documentation, or non-impacting changes.

• Unstable packages: Use 0.major.minor+patch .

• Recommendation: Aim for 1.0.0 as soon as the package is stable.

Pre-Edit Verification

Check Published Versions: Before modifying CHANGELOG.md or pubspec.yaml , ALWAYS check the currently released version (e.g., via git tag or pub.dev ).

Do Not Amend Released Versions: Never add new entries to a version header that corresponds to a released tag.

Increment for New Changes: If the current version in pubspec.yaml

matches a released tag, increment the version (e.g., usually to -wip ) and create a new section in CHANGELOG.md .

Consistency: The CHANGELOG.md header must match the new pubspec.yaml version.

SemVer Guidelines:

• Breaking Changes: Bump Major, reset Minor/Patch (e.g., 2.0.0-wip , 0.5.0-wip ).

• New Features: Bump Minor, reset Patch (e.g., 1.1.0-wip , 0.4.5-wip ).

• Bug Fixes: Bump Patch (e.g., 1.0.1-wip ).

Work-in-Progress (WIP) Versions

• Immediately after a publish, or on the first change after a publish, update pubspec.yaml and CHANGELOG.md with a -wip suffix (e.g., 1.1.0-wip ).

• This indicates the current state is not yet published.

Breaking Changes

• Evaluate the impact on dependent packages and internal projects.

• Consider running changes through internal presubmits if possible.

• Prefer incremental rollouts (e.g., new behavior as opt-in) to minimize downstream breakage.

Publishing Process

• Preparation: Remove the -wip suffix from pubspec.yaml and CHANGELOG.md in a dedicated pull request.

• Execution: Run dart pub publish (or flutter pub publish ) and resolve all warnings and errors.

• Tagging: Create and push a git tag for the published version:

• For single-package repos: v1.2.3

• For monorepos: package_name-v1.2.3

• Example: git tag v1.2.3 && git push --tags

Pull Request Management

• Commits: Each PR should generally correspond to a single squashed commit upon merging.

• Shared History: Once a PR is open, avoid force pushing to the branch.

• Conflict Resolution: Prefer merging main into the PR branch rather than rebasing to resolve conflicts. This preserves the review history and comments.

• Reviewing: Add comments from the "Files changed" view to batch them.

• Local Inspection: Use gh pr checkout <number> to inspect changes locally in your IDE.