Skip to content

Update publishing to pub.dev #963

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
polina-c merged 14 commits into from
Jun 15, 2026
Merged

Update publishing to pub.dev #963

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
05b7015
Update publishing.md
polina-c Jun 10, 2026
cf77f7a
Update docs/contributing/publishing.md
polina-c Jun 10, 2026
93750dd
-
polina-c Jun 10, 2026
5dfe991
Update publishing.md
polina-c Jun 11, 2026
0ad23ad
-
polina-c Jun 15, 2026
4f5118e
Update health.yaml
polina-c Jun 15, 2026
aec683a
-
polina-c Jun 15, 2026
825ea07
Update pub_health.yaml
polina-c Jun 15, 2026
6c929ec
Update pub_health.yaml
polina-c Jun 15, 2026
ccda324
Update pub_health.yaml
polina-c Jun 15, 2026
a415838
-
polina-c Jun 15, 2026
e795adc
Update publishing.md
polina-c Jun 15, 2026
987b529
Update publishing.md
polina-c Jun 15, 2026
d326f11
Update publishing.md
polina-c Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/workflows/pub_health.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Copyright 2025 The Flutter Authors.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

# Checks changelog has been modified for changed packages.

# TODO(polina-c): add `dart-lang/ecosystem/.github/workflows/post_summaries.yaml@*,`
# to the org termissions, to enable this workflow

name: Health
on:
pull_request:
branches: [ main ]
types: [opened, synchronize, reopened, labeled, unlabeled]
jobs:
health:
uses: dart-lang/ecosystem/.github/workflows/health.yaml@main

@ditman ditman Jun 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be pinned at a specific revision of the workflow, and not let it be @main?

(Also it's a little bit weird that we're depending on actions directly like this, instead of on something that has been "published", are we allowed to take this dependency from outside dart-lang? (I'm assuming yes)

@polina-c polina-c Jun 15, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am working with flutter org owners to explicitely allow these workflows.

See https://github.com/flutter/genui/blob/main/docs/contributing/publishing.md#setup-org-permissions

So, no, we do not need version

And, yes, everything is secure enough

with:
checks: "changelog"
permissions:
pull-requests: write
0 .github/workflows/post_summaries.yaml → .github/workflows/pub_post_summaries.yaml
View file
Open in desktop
File renamed without changes.
0 .github/workflows/publish.yaml → .github/workflows/pub_publish.yaml
View file
Open in desktop
File renamed without changes.
65 changes: 46 additions & 19 deletions docs/contributing/publishing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ To make sure your PR passes this validation, follow [firehose rules](https://git

Packages in this repo fall into the following categories:

1. **Not published**: `pubspec.yaml` contains `publish_to: none`. Workspace tools and example apps that are never pushed to pub.dev.
2. **Not yet published**: the package's `version:` ends with a `-wip<N>` suffix (see "`-wip` vs non-`-wip`" below). Published to pub.dev to reserve the name or to test the package; not ready for general use yet.
1. **Not planned to be published**: `pubspec.yaml` contains `publish_to: none`. Workspace tools and example apps that are never pushed to pub.dev.
2. **Not yet published**: the package's `version:` ends with a `-wip<N>` suffix (see "Versioning" below). Not-ready-for-production versions are pushed to pub.dev to reserve the name and maybe to try the package in dev purposes.

@ditman ditman Jun 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reserving the name only matters the first time that the package is published (and it could be version 0.0.0), I don't think we'll ever publish a -wip version to reserve a name (but yes for dev purposes)

3. **Published**: any other package. Each has its own version cadence on pub.dev.

## About `resolution: workspace`
Expand All @@ -33,32 +33,34 @@ Packages in this repo fall into the following categories:

Note that a package can opt out (by omitting `resolution: workspace`) to have separate dependency resolution.

## `-wip` vs non-`-wip` (production ready) versions
## Versioning

The packages code should be always release ready. That means:
We use [Semver] for package versioning, although before 1.0.0, we will be
incrementing only the minor number for breaking changes and the patch number for
non-breaking changes. After 1.0.0, we will be using standard Semver, bumping the
major number for breaking changes.

1. Use `-wip` version (format `0.1.0-wip002`) if **at least one** of the following statements is true:
<!-- references -->

1.1. The package is planned to be released in the future. In this case it is published with `-wip` suffix in order to reserve the package name.
[Semver]: https://semver.org/

1.2. The package's last changes touch only non-publishable code or docs (like tests, tools, or not-publishable docs).
The versions may have postfixes:

You can publish `-wip<number>` versions (where `<number>` is a three-digit, zero padded integer like `-wip003`), if you need it for development.
- **`-wip<three digit number>`**: not ready for production
- **`-noop`**: used in CHANGELOG.md and pubspec.yaml to indicate that the code does not contain publishable changes comparing to the previously published version and thus should not be published to pub.dev.

@ditman ditman Jun 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that instead of a -noop suffix (that changes the effective version of the package), changes that don't need to be published should just not upgrade the version of the package (and maybe have an "Unpublished" section in the CHANGELOG if they ever need a version). That way the tooling that we have, will not even let us publish the version (because it'd be "already published")

-wip to release things for "integration" testing or pre-release validation, a full normal version (which should be the same as "removing -wip") to fully publish the package in a way that would get picked up by pub get.

(We do the "Unreleased" thing in the npm packages already; keeping track of unreleased changes and making a note there if they're breaking/non-breaking in the changelog makes picking the next correct version very easy later)

@polina-c polina-c Jun 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks.

We will need unreleased/noop in order to be compliant with automation, that verifies version in md is intact with pub.dev and pubspec.yaml.

I prefer 'noop' here, because we want 'op' changes to be released immediately after merge.

@ditman ditman Jun 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand the need for noop:

  • The first time you push a "noop" change, it makes the package publishable, so I may end up with a "-noop" version on pub. (This is probably not what I want)
  • Other "noop" changes result in non-publishable changes (this is wanted)

Wouldn't it be easier for "noop" changes to not change the pubspec.yaml at all, so they're effectively non-publishable (because we can't re-publish a version that already exists?)

- **no postfix**: release ready version, that should be pushed to pub.dev right after merging the PR that introduced the changes.

2. Remove `-wip` suffix from a version in `pubspec.yaml`, if your change in this package is publishable.
The packages code should be always release ready. That means:

3. If your feature is partially implemented, hide the feature's code behind a false-by-default flag, and use **release-ready** version. (There is no detailed guidance how to define this flag yet. It should be outlined when it is needed. Please create an issue if you need it soon.)
1. Use `-wip` version (format `0.1.0-wip002`) if ready versions for this packages were never published yet, and are planned to be published in the future.

## Versioning
2. Use `-noop` version if your PR touches only non-publishable code or docs (like tests, tools, or not-publishable docs).

We use [Semver] for package versioning, although before 1.0.0, we will be
incrementing only the minor number for breaking changes and the patch number for
non-breaking changes. After 1.0.0, we will be using standard Semver, bumping the
major number for breaking changes.
3. You can publish `-wip<number>` versions, if you need it for development, but do not merge `wip` versions for prod-ready published packages.

<!-- references -->
4. Remove `-noop` suffix from a version in `pubspec.yaml`, if your change is publishable.

[Semver]: https://semver.org/
5. If your feature is partially implemented, hide the feature's code behind a false-by-default flag, and use **release-ready** version. (There is no detailed guidance how to define this flag yet. It should be outlined when it is needed. Please create an issue if you need it soon.)

## How publishing happens?

Expand All @@ -68,7 +70,31 @@ major number for breaking changes.

2. **Manual**: After reviewing and merging the PR, for each 'ready to publish' version the author of the PR should run `flutter pub publish` or `dart pub publish`.

TODO(polinach): update this section after fix of https://github.com/dart-lang/ecosystem/issues/418.
TODO(polina-c): add validation that all PRs include CHANGELOG.md entries: https://github.com/flutter/genui/issues/967.

TODO(polina-c): update this section after fix of https://github.com/dart-lang/ecosystem/issues/418.

## On-call responsibilities

Weekly:

1. Make sure each releasable dart package is released (TODO: [auto-create P0 bug](https://github.com/dart-lang/ecosystem/issues/423))
1.1. Check the `Package publishing` table in the latest merged PR to see if all non-wip versions are marked `already published`.
1.2. For packages not yet published, publish them by running `flutter pub publish` (if you do not have permissions, ask in the team chat to be made an admin on the admin page of the package).

2. Make sure publishable changes are not under `wip` in `CHANGELOG.md` (should be [auto-validated](https://github.com/dart-lang/ecosystem/issues/422) in future).

If publishable changes are under `wip` in `CHANGELOG.md`:

2.1. Convert the wip version to a non-wip version in `CHANGELOG.md`.

2.2. Publish the new version.

2.3. Comment on the PR that merged publishable changes under `wip`:

> This PR wrongly placed publishable changes under a `wip` version. This is corrected in PR <link>. See guidelines [here](https://github.com/flutter/genui/blob/main/docs/contributing/publishing.md#-wip-vs-non--wip-production-ready-versions).

@ditman ditman Jun 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needing this makes me feel that there's a point in the process that introduces ambiguity when reviewing. Do you think the "-wip" should be just a "escape hatch" when a change really really does not need to be published, that the reviewers can suggest to do?

For example, in flutter/packages, there's the same expectation of "auto-publish after every push", but what this flow calls "-wip" is called "NEXT" there (see this). NEXT changes are not expected to be published at all (and the automation skips them), and only when a real release happens, their changelog entries get merged into that of the release.

@polina-c polina-c Jun 10, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting.

I like the direction.

For me "NEXT" also means some changes.

I like 'noop' more.

And, 'wip' versions still may exist as development artifact, needed for testing.

I will review the doc from this perspective.


2.4. Make sure the PR author and reviewers acknowledged the comment.

## How upgrade of dependencies happens?

Expand Down Expand Up @@ -109,8 +135,9 @@ In https://github.com/organizations/flutter/settings/actions:
peter-evans/create-or-update-comment@*,
peter-evans/create-pull-request@*,
peter-evans/repository-dispatch@*,
dart-lang/ecosystem/.github/workflows/publish.yaml@*,
dart-lang/ecosystem/.github/workflows/health.yaml@*,
dart-lang/ecosystem/.github/workflows/post_summaries.yaml@*,
dart-lang/ecosystem/.github/workflows/publish.yaml@*,
```

### Configure pub.dev for each package
Expand Down
2 changes: 1 addition & 1 deletion packages/genai_primitives/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# `genai_primitives` Changelog

## 0.2.4-wip001
## 0.2.4

- **Feature**: Use `log` instead of `print` in example ([#546dab9be](https://github.com/flutter/genui/commit/546dab9be)).

Expand Down
2 changes: 1 addition & 1 deletion packages/genai_primitives/pubspec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

name: genai_primitives
description: A set of primitives for working with generative AI.
version: 0.2.4-wip001
version: 0.2.4
homepage: https://github.com/flutter/genui/tree/main/packages/genai_primitives
license: BSD-3-Clause
issue_tracker: https://github.com/flutter/genui/issues
Expand Down
Loading