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 to inspect changes locally in your IDE.