dart-package-maintenance

Dart packages follow semantic versioning: major for breaking changes, minor for new features, patch for bug fixes. Check the currently released version via git tags or pub.dev first, then increment pubspec.yaml and add a matching CHANGELOG.md section, typically with a -wip suffix.

Remove the -wip suffix from pubspec.yaml and CHANGELOG.md in a dedicated pull request, then run dart pub publish or flutter pub publish and resolve all warnings. After publishing, create and push a git tag like v1.2.3, or package_name-v1.2.3 for monorepos.

No, never add new entries to a version header that corresponds to a released tag. Instead, increment the version in pubspec.yaml, usually with a -wip suffix, and create a new CHANGELOG.md section whose header matches the new version.

Prefer merging main into the PR branch rather than rebasing, since rebasing rewrites shared history and loses review comments. Avoid force pushing once a PR is open, and use gh pr checkout <number> to inspect changes locally.

Unstable packages use the 0.major.minor+patch format while the API is still evolving. Once the package is stable, aim to release 1.0.0 as soon as possible to signal a dependable public API to consumers.