diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 84b9fd214751..ec9a6dd6ab92 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -8,7 +8,7 @@ - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] I read the [Tree Hygiene] wiki page, which explains my responsibilities. -- [ ] I read and followed the [Flutter Style Guide] and the [C++, Objective-C, Java style guides]. +- [ ] I read and followed the [Flutter Style Guide] and the [C++, Objective-C, Java style guides]. (Note that unlike the flutter/flutter repo, the flutter/plugins repo does use `dart format`. See [plugin_tool format](../script/tool/README.md#format-code)) - [ ] I signed the [CLA]. - [ ] The title of the PR starts with the name of the plugin surrounded by square brackets, e.g. `[shared_preferences]` - [ ] I listed at least one issue that this PR fixes in the description above. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f307695b5956..9524af1c2f31 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,5 @@ # Contributing to Flutter Plugins - [![Build Status](https://api.cirrus-ci.com/github/flutter/plugins.svg)](https://cirrus-ci.com/github/flutter/plugins/master) _See also: [Flutter's code of conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md)_ @@ -26,14 +25,12 @@ for any of the following plugins, we encourage you to submit it ## Things you will need - * Linux, Mac OS X, or Windows. * git (used for source version control). * An ssh client (used to authenticate with GitHub). ## Getting the code and configuring your environment - * Ensure all the dependencies described in the previous section are installed. * Fork `https://github.com/flutter/plugins` into your own GitHub account. If you already have a fork, and are now installing a development environment on @@ -48,8 +45,13 @@ for any of the following plugins, we encourage you to submit it fetch from the master repository, not your clone, when running `git fetch` et al.) -## Running the examples +## Setting up tools + +There are scripts for many common tasks (testing, formatting, etc.) that will likely be useful in preparing a PR. +See [plugin_tools](./script/tool/README.MD) for more details. + +## Running the examples To run an example with a prebuilt binary from the cloud, switch to that example's directory, run `pub get` to make sure its dependencies have been @@ -137,13 +139,7 @@ pod lib lint --allow-warnings XCUITests aren't usually configured with cocoapods in this repo. They are configured in a xcode workspace target named RunnerUITests. To run all the XCUITests in a plugin, follow the steps in a regular iOS development workflow [here](https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/testing_with_xcode/chapters/05-running_tests.html) -For convenience, a [flutter_plugin_tools](https://pub.dev/packages/flutter_plugin_tools) command `xctest` could also be used to run all the XCUITests in the repo: - -```console -pub global activate flutter_plugin_tools -cd /packages -pub global run flutter_plugin_tools xctest --target RunnerUITests --skip -``` +For convenience, a [plugin_tools](./script/tool/README.MD) command [xctest](./script/tool/README.MD#run-xctests) could also be used to run all the XCUITests in the repo. ## Contributing code @@ -159,12 +155,12 @@ To start working on a patch: * `git fetch upstream` * `git checkout upstream/master -b ` * Hack away. - * Verify changes with [flutter_plugin_tools](https://pub.dev/packages/flutter_plugin_tools) -``` -pub global activate flutter_plugin_tools -pub global run flutter_plugin_tools format --plugins plugin_name -pub global run flutter_plugin_tools analyze --plugins plugin_name -pub global run flutter_plugin_tools test --plugins plugin_name + * Verify changes with [plugin_tools](./script/tool/README.MD). +```sh +cd script/tool && pub get && cd ../../ +dart ./script/tool/lib/src/main.dart format --plugins plugin_name +dart ./script/tool/lib/src/main.dart analyze --plugins plugin_name +dart ./script/tool/lib/src/main.dart test --plugins plugin_name ``` * `git commit -a -m ""` * `git push origin ` @@ -194,8 +190,6 @@ You may also add it to the AUTHORS file for [the repository](AUTHORS). ### The review process -* This is a new process we are currently experimenting with, feedback on the process is welcomed at the Gitter contributors channel. * - Reviewing PRs often requires a non trivial amount of time. We prioritize issues, not PRs, so that we use our maintainers' time in the most impactful way. Issues pertaining to this repository are managed in the [flutter/flutter issue tracker and are labeled with "plugin"](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3Aplugin+sort%3Areactions-%2B1-desc). Non trivial PRs should have an associated issue that will be used for prioritization. See the [prioritization section](https://github.com/flutter/flutter/wiki/Issue-hygiene#prioritization) in the Flutter wiki to understand how issues are prioritized. Newly opened PRs first go through initial triage which results in one of: @@ -237,45 +231,12 @@ Some things to keep in mind before publishing the release: 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. +To release a package, a [publish-plugin](./script/tool/README.MD#publish-and-tag-release) tool script should be used. This command publishes the new version to pub.dev, and tags the commit in the format of `-v` then pushes it to upstream. + +Alternatively, one can release a package in the below 2-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 `-v`, 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). diff --git a/script/tool/README.md b/script/tool/README.md index 162ca0d98a74..daea4d86390b 100644 --- a/script/tool/README.md +++ b/script/tool/README.md @@ -1,8 +1,61 @@ # Flutter Plugin Tools +Note: The commands in tools are designed to run at the root of the repository or `/packages/`. + To run the tool: ```sh -dart pub get -dart run lib/src/main.dart +cd /script/tool && dart pub get && cd ../../ +dart run ./script/tool/lib/src/main.dart +``` + +## Format Code + +```sh +cd +dart run /script/tool/lib/src/main.dart format --plugins plugin_name +``` + +## Run static analyzer + +```sh +cd +pub run ./script/tool/lib/src/main.dart analyze --plugins plugin_name +``` + +## Run Dart unit tests + +```sh +cd +pub run ./script/tool/lib/src/main.dart test --plugins plugin_name +``` + +## Run XCTests + +```sh +cd +dart run lib/src/main.dart xctest --target RunnerUITests --skip ``` + +## Publish and tag release + +``sh +cd +git checkout +dart run ./script/tool/lib/src/main.dart publish-plugin --package +`` + +By default the tool tries to push tags to the `upstream` remote, but some +additional settings can be configured. Run `dart run ./script/tool/lib/src/main.dart publish-plugin --help` for more usage information. + +The tool wraps `pub publish` for pushing the package to pub, and then will +automatically use git to try to 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. +`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).