Skip to content

Commit

Permalink
Update CONTRIBUTING.md to match flutter/plugins (firebase#1587)
Browse files Browse the repository at this point in the history
Copy-pasted from the flutter/plugins README. It's a bit wasteful to duplicate all this text, but we want to let the FlutterFire repo evolve in its own direction over time so maybe it's better not to try to point to the same place.
  • Loading branch information
collinjackson authored and Michael Klimushyn committed Dec 9, 2019
1 parent d9c3b88 commit 0ed8cdd
Showing 1 changed file with 71 additions and 0 deletions.
71 changes: 71 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,74 @@ Newly opened PRs first go through initial triage which results in one of:
* **Starting a non trivial review** - if the review requires non trivial effort and the issue is a priority; in this case the maintainer will:
* Add the "in review" label to the issue.
* Self assign the PR.

### The release process

We push releases manually. Generally every merged PR upgrades at least one
plugin's `pubspec.yaml`, so also needs to be published as a package release. The
FlutterFire maintainer most involved with the PR should be the person responsible
for publishing the package release. In cases where the PR is authored by a
FlutterFire maintainer, the publisher should probably be the author. In other cases
where the PR is from a contributor, it's up to the reviewing Flutter team member
to publish the release instead.

Some things to keep in mind before publishing the release:

- Has CI ran on the master commit and gone green? Even if CI shows as green on
the PR it's still possible for it to fail on merge, for multiple reasons.
There may have been some bug in the merge that introduced new failures. CI
runs on PRs as it's configured on their branch state, and not on tip of tree.
CI on PRs also only runs tests for packages that it detects have been directly
changed, vs running on every single package on master.
- [Publishing is
forever.](https://dart.dev/tools/pub/publishing#publishing-is-forever)
Hopefully any bugs or breaking in changes in this PR have already been caught
in PR review, but now's a second chance to revert before anything goes live.
- "Don't deploy on a Friday." Consider carefully whether or not it's worth
immediately publishing an update before a stretch of time where you're going
to be unavailable. There may be bugs with the release or questions about it
from people that immediately adopt it, and uncovering and resolving those
support issues will take more time if you're unavailable.

Releasing a package is a two-step process.

1. Push the package update to [pub.dev](https://pub.dev) using `pub publish`.
2. Tag the commit with git in the format of `<package_name>-v<package_version>`,
and then push the tag to the `flutter/plugins` master branch. This can be
done manually with `git tag $tagname && git push upstream $tagname` while
checked out on the commit that updated `version` in `pubspec.yaml`.

We've recently updated
[flutter_plugin_tools](https://github.com/flutter/plugin_tools) to wrap both of
those steps into one command to make it a little easier. This new tool is
experimental. Feel free to fall back on manually running `pub publish` and
creating and pushing the tag in git if there are issues with it.

Install the tool by running:

```terminal
$ pub global activate flutter_plugin_tools
```

Then, from the root of your local `flutter/plugins` repo, use the tool to
publish a release.

```terminal
$ pub global run flutter_plugin_tools publish-plugin --package $package
```

By default the tool tries to push tags to the `upstream` remote, but that and
some additional settings can be configured. Run `pub global activate
flutter_plugin_tools --help` for more usage information.

The tool wraps `pub publish` for pushing the package to pub, and then will
automatically use git to try and create and push tags. It has some additional
safety checking around `pub publish` too. By default `pub publish` publishes
_everything_, including untracked or uncommitted files in version control.
`flutter_plugin_tools publish-plugin` will first check the status of the local
directory and refuse to publish if there are any mismatched files with version
control present.

There is a lot about this process that is still to be desired. Some top level
items are being tracked in
[flutter/flutter#27258](https://github.com/flutter/flutter/issues/27258).

0 comments on commit 0ed8cdd

Please sign in to comment.