-
Notifications
You must be signed in to change notification settings - Fork 170
Update release steps. #1025
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.
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
Merged
Update release steps. #1025
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,149 +1,3 @@ | ||
| # Release to pub.dev | ||
|
|
||
| # Release process | ||
|
|
||
| Publishing to [pub.dev](https://pub.dev) happens automatically via GitHub Actions, with the help of | ||
| [firehose rules](https://github.com/dart-lang/ecosystem/tree/main/pkgs/firehose). | ||
|
|
||
| There are two CI workflows that enable this automation: | ||
|
|
||
| 1. [post_summaries.yaml](../../.github/workflows/post_summaries.yaml) - job `publish / validate` runs on pre-submit. | ||
| 2. [publish.yaml](../../.github/workflows/publish.yaml) - job `publish / publish` runs on tagging. | ||
|
|
||
| ## Passing the publish / validate job | ||
|
|
||
| In general, the job [publish / validate](https://github.com/flutter/genui/actions/workflows/post_summaries.yaml) checks if all pub.dev packages are ready for publishing. | ||
|
|
||
| To make sure your PR passes this validation, follow [firehose rules](https://github.com/dart-lang/ecosystem/tree/main/pkgs/firehose). | ||
|
|
||
| ## Package categories | ||
|
|
||
| Packages in this repo fall into the following categories: | ||
|
|
||
| 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. | ||
| 3. **Published**: any other package. Each has its own version cadence on pub.dev. | ||
|
|
||
| ## About `resolution: workspace` | ||
|
|
||
| `resolution: workspace` in a `pubspec.yaml`: | ||
|
|
||
| 1. Tells Dart to share dependency resolution and a lockfile with the monorepo. | ||
|
|
||
| 2. Tells to use **current repo as a source** for the package, not pub.dev (for local runs). | ||
|
|
||
| Note that a package can opt out (by omitting `resolution: workspace`) to have separate dependency resolution. | ||
|
|
||
| ## Versioning | ||
|
|
||
| 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. | ||
|
|
||
| <!-- references --> | ||
|
|
||
| [Semver]: https://semver.org/ | ||
|
|
||
| The versions may have postfixes: | ||
|
|
||
| - **`-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. | ||
| - **no postfix**: release ready version, that should be pushed to pub.dev right after merging the PR that introduced the changes. | ||
|
|
||
| The packages code should be always release ready. That means: | ||
|
|
||
| 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. | ||
|
|
||
| 2. Use `-noop` version if your PR touches only non-publishable code or docs (like tests, tools, or not-publishable docs). | ||
|
|
||
| 3. You can publish `-wip<number>` versions, if you need it for development, but do not merge `wip` versions for prod-ready published packages. | ||
|
|
||
| 4. Remove `-noop` suffix from a version in `pubspec.yaml`, if your change is publishable. | ||
|
|
||
| 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? | ||
|
|
||
| 1. **Auto**: The workflow job `publish / validate` will: | ||
| - check if the PR follows [firehose rules](https://github.com/dart-lang/ecosystem/tree/main/pkgs/firehose). | ||
| - add a table [like this](https://github.com/flutter/genui/pull/941#issuecomment-4556675732) to each PR. | ||
|
|
||
| 2. **Manual**: After reviewing and merging the versioning PR, the releaser should: | ||
| 1. Ensure you are working from a clean repository on the `main` branch and that git submodules are up to date: | ||
| ```bash | ||
| git checkout main | ||
| git pull | ||
| git submodule update --init --recursive | ||
| ``` | ||
| 2. **For each package** that needs to be published: | ||
| 1. Ensure that the `CHANGELOG.md` and `pubspec.yaml` versions agree. | ||
| 2. Run `flutter pub get`. | ||
| 3. Run `flutter test`. | ||
| 4. (Optionally) Run `flutter pub publish --dry-run` to verify the publishability of the package. | ||
| 5. Run `flutter pub publish` and check its output to ensure the package was published without warnings or errors. | ||
| 6. Check [pub.dev](https://pub.dev/) to verify the package was actually published. | ||
|
|
||
| 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: | ||
|
|
||
| Make sure each releasable dart package is released (TODO: [auto-create P0 bug](https://github.com/dart-lang/ecosystem/issues/423)) | ||
| 1. Check the `Package publishing` table in the [latest merged PR that touches releasable code](https://github.com/flutter/genui/pulls?q=is%3Apr+is%3Amerged+%22Package+publishing%22) to see if all non-wip versions are marked `already published`. | ||
| 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). | ||
|
|
||
| ## How upgrade of dependencies happens? | ||
|
|
||
| ### For run in workspace | ||
|
|
||
| For packages with `resolution: workspace` in their pubspec.yaml, pub resolves every sibling from its local source directory — not from pub.dev, as long as its `version:` satisfies the consumer's constraint. | ||
|
|
||
| If a local bump escapes that constraint (e.g. `^0.9.0` → `0.10.0`), you must update the consumer's `pubspec.yaml` in the same PR. While `dart pub` natively silently falls back to the published version on pub.dev, **our `test_and_fix` CI suite contains a verification step that will explicitly throw an error** and fail your PR if internal workspace version constraints are not met. | ||
|
|
||
| ### For global dependencies | ||
|
|
||
| After a new version of a dependency is published, this is how upgrade will happen: | ||
|
|
||
| 1. [Dependabot] detects the new version on pub.dev and opens a PR per dependency, bumping the constraint in each consuming `pubspec.yaml`. See [About Dependabot version updates] for details. | ||
| 2. The PR runs `publish / validate` and the rest of CI. | ||
| 3. A maintainer reviews and merges the PR. | ||
|
|
||
| TODO: Consume solution for [dependabot issue][dependabot/dependabot-core#15057] when it is fixed. | ||
|
|
||
| [Dependabot]: ../../.github/dependabot.yaml | ||
| [About Dependabot version updates]: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates | ||
| [dependabot/dependabot-core#15057]: https://github.com/dependabot/dependabot-core/issues/15057 | ||
|
|
||
| ## How to configure GitHub and pub.dev for auto-publishing? | ||
|
|
||
| GitHub and pub.dev are already configured for auto-publishing. This section is here in case this needs to be reproduced for new repo or new package. | ||
|
|
||
| Note that you need to have administrative permissions to update configuration. | ||
|
|
||
| ### Setup org permissions | ||
|
|
||
| In https://github.com/organizations/flutter/settings/actions: | ||
|
|
||
| 1. Find the section "Allow or block specified actions and reusable workflows" | ||
| 2. Add these values (if they are already here, they will be de-dupped automatically): | ||
|
|
||
| ``` | ||
| peter-evans/create-or-update-comment@*, | ||
| peter-evans/create-pull-request@*, | ||
| peter-evans/repository-dispatch@*, | ||
| 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 | ||
|
|
||
| This requires uploader/admin rights on the package. | ||
|
|
||
| 1. Go to https://pub.dev/packages/<YOUR_PACKAGE_NAME>/admin | ||
| 2. Under "Automated publishing", enable "Publishing from GitHub Actions" for both `push` and `workflow_dispatch` events. | ||
| 3. Set Repository to `<YOUR_ORG>/<YOUR_REPO>`. | ||
| 4. Set Tag pattern to `<YOUR_PACKAGE_NAME>-v{{version}}`. | ||
| See [release.md](https://github.com/a2ui-project/a2ui/blob/main/docs/contributing/release.md#pubdev) on a2ui repo. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For better readability and style, consider using more descriptive link text (e.g., 'release guide' instead of the file name) and referring to the repository more formally as 'the a2ui repository'.