Skip to content

Commit

Permalink
chore: update contributing file (firebase#2963)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ehesp
Ehesp authored Oct 1, 2020
1 parent f7d163b commit 7b82c07
Show file tree
Hide file tree
Showing 2 changed files with 141 additions and 118 deletions.
5 changes: 2 additions & 3 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@

## Checklist

Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes (`[x]`). This will ensure a smooth and quick review process.
Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes (`[x]`).
This will ensure a smooth and quick review process. Updating the `pubspec.yaml` and changelogs is not required.

- [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs.
- [ ] If the pull request affects only one plugin, the PR title starts with the name of the plugin in brackets (e.g. [cloud_firestore])
Expand All @@ -17,8 +18,6 @@ Before you create this PR confirm that it meets all requirements listed below by
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [ ] The analyzer (`flutter analyze`) does not report any problems on my PR.
- [ ] I read and followed the [Flutter Style Guide].
- [ ] I updated pubspec.yaml with an appropriate new version according to the [pub versioning philosophy].
- [ ] I updated CHANGELOG.md to add a description of the change.
- [ ] I signed the [CLA].
- [ ] I am willing to follow-up on review comments in a timely manner.

Expand Down
254 changes: 139 additions & 115 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,61 +1,122 @@
# Contributing to FlutterFire

[![Build Status](https://api.cirrus-ci.com/github/FirebaseExtended/flutterfire.svg)](https://cirrus-ci.com/github/FirebaseExtended/flutterfire/master)
<a href="https://github.com/FirebaseExtended/flutterfire/actions?query=workflow%3Aall_plugins">
<img src="https://github.com/FirebaseExtended/flutterfire/workflows/all_plugins/badge.svg" alt="all_plugins GitHub Workflow Status"/>
</a>

_See also: [Flutter's code of conduct](https://flutter.io/design-principles/#code-of-conduct)_

## Things you will need
## 1. Things you will need

* Linux, Mac OS X, or Windows.
* git (used for source version control).
* An ssh client (used to authenticate with GitHub).
- Linux, Mac OS X, or Windows.
- [git](https://git-scm.com) (used for source version control).
- An ssh client (used to authenticate with GitHub).
- An IDE such as [Android Studio](https://developer.android.com/studio) or [Visual Studio Code](https://code.visualstudio.com/).
- [`flutter_plugin_tools`](https://pub.dartlang.org/packages/flutter_plugin_tools) locally activated.
- [`tuneup`](https://pub.dev/packages/tuneup) locally activated.

## Getting the code and configuring your environment
## 2. Forking & cloning the repository

- Ensure all the dependencies described in the previous section are installed.
- Fork `https://github.com/FirebaseExtended/flutterfire` into your own GitHub account. If
you already have a fork, and are now installing a development environment on
a new machine, make sure you've updated your fork so that you don't use stale
configuration options from long ago.
- If you haven't configured your machine with an SSH key that's known to github, then
follow [GitHub's directions](https://help.github.com/articles/generating-ssh-keys/)
to generate an SSH key.
- `git clone [email protected]:<your_name_here>/flutterfire.git`
- `git remote add upstream [email protected]:FirebaseExtended/flutterfire.git` (So that you
fetch from the master repository, not your clone, when running `git fetch`
et al.)

* Ensure all the dependencies described in the previous section are installed.
* Fork `https://github.com/FirebaseExtended/flutterfire` into your own GitHub account. If
you already have a fork, and are now installing a development environment on
a new machine, make sure you've updated your fork so that you don't use stale
configuration options from long ago.
* If you haven't configured your machine with an SSH key that's known to github, then
follow [GitHub's directions](https://help.github.com/articles/generating-ssh-keys/)
to generate an SSH key.
* `git clone [email protected]:<your_name_here>/flutterfire.git`
* `cd plugins`
* `git remote add upstream [email protected]:FirebaseExtended/flutterfire.git` (So that you
fetch from the master repository, not your clone, when running `git fetch`
et al.)
## 3. Environment Setup

## Running the examples
FlutterFire uses [Melos](https://github.com/invertase/melos) to manage the project and dependencies.

To install Melos, run the following command from your SSH client:

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
downloaded, and use `flutter run`. Make sure you have a device connected over
USB and debugging enabled on that device.
```bash
pub global activate melos
```

Next, at the root of your locally cloned repository bootstrap the projects dependencies:

```bash
melos bootstrap
```

The bootstrap command locally links all dependencies within the project without having to
provide manual [`dependency_overrides`](https://dart.dev/tools/pub/pubspec). This allows all
plugins, examples and tests to build from the local clone project.

> You do not need to run `flutter pub get` once bootstrap has been completed.
## 4. Running an example

Each plugin provides an example app which aims to showcase the main use-cases of each plugin.

To run an example, run the `flutter run` command from the `example` directory of each plugins main
directory. For example, for Firebase Auth example:

```bash
cd packages/firebase_auth/firebase_auth/example
flutter run
```

Using Melos (installed in step 3), any changes made to the plugins locally will also be reflected within all
example applications code automatically.

* `cd packages/cloud_firestore/cloud_firestore/example`
* `flutter run`
## 4. Running tests

## Running the tests
FlutterFire comprises of a number of tests for each plugin, either end-to-end (e2e) or unit tests.

Flutter plugins have both unit tests of their Dart API and integration tests that run on a virtual or actual device.
### Unit tests

To run the unit tests:
Unit tests are responsible for ensuring expected behavior whilst developing the plugins Dart code. Unit tests do not
interact with 3rd party Firebase services, and mock where possible. To run unit tests for a specific plugin, run the
`flutter test` command from the plugins root directory. For example, Firebase Auth platform interface tests can be run
with the following commands:

```bash
cd packages/firebase_auth/firebase_auth_platform_interface
flutter test
```
flutter test test/<name_of_plugin>_test.dart

### End-to-end (e2e) tests

E2e tests are those which directly communicate with Firebase, whose results cannot be mocked. These tests run directly from
an example application. To run e2e tests, run the `flutter drive` command from the plugins main `example` directory, targeting the
entry e2e test file.

> Some packages use Firebase Emulator Suite to run tests. To learn more, [visit the official documentation](https://firebase.google.com/docs/emulator-suite).
```bash
cd packages/firebase_auth/firebase_auth/example
flutter drive --target=./test_driver/firebase_auth_e2e.dart
```

To run the integration tests:
To run tests against web environments, run the command as a release build:

```bash
cd packages/firebase_auth/firebase_auth/example
flutter drive --target=./test_driver/firebase_auth_e2e.dart --release -d chrome
```
cd example
flutter drive test_driver/<name_of_plugin>.dart

### Using Melos

To help aid developer workflow, Melos provides a number of commands to quickly run
tests against plugins. For example, to run all e2e tests across all plugins at once,
run the following command from the root of your cloned repository:

```bash
melos run test:e2e
```

## Contributing code
A full list of all commands can be found within the [`melos.yaml`](https://github.com/FirebaseExtended/flutterfire/blob/master/melos.yaml)
file.

## 5. Contributing code

We gladly accept contributions via GitHub pull requests.

Expand All @@ -67,37 +128,45 @@ keep the code consistent and avoid common pitfalls.

To start working on a patch:

* `git fetch upstream`
* `git checkout upstream/master -b <name_of_your_branch>`
* 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
1. `git fetch upstream`
2. `git checkout upstream/master -b <name_of_your_branch>`
3. Hack away!

Once you have made your changes, ensure that it passes the internal analyzer & formatting checks. The following
commands can be run locally to highlight any issues before committing your code:

```bash
# Run the analyze check
melos run analyze

# Format code
melos run format
```
* `git commit -a -m "<your informative commit message>"`
* `git push origin <name_of_your_branch>`

Assuming all is successful, commit and push your code:

1. `git commit -a -m "<your informative commit message>"`
2. `git push origin <name_of_your_branch>`

To send us a pull request:

* `git pull-request` (if you are using [Hub](http://github.com/github/hub/)) or
- `git pull-request` (if you are using [Hub](http://github.com/github/hub/)) or
go to `https://github.com/FirebaseExtended/flutterfire` and click the
"Compare & pull request" button

Please make sure all your checkins have detailed commit messages explaining the patch.
Please make sure all your check-ins have detailed commit messages explaining the patch.

When naming the title of your pull request, please follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/)
guide. For example, for a fix to the Firebase Auth plugin:

For pull requests that affect only one Flutterfire plugin, use a title that starts
with the name of the plugin in brackets (e.g. [cloud_firestore]).
`fix(firebase_auth): fixed a bug!`

Plugins tests are run automatically on contributions using Cirrus CI. However, due to
cost constraints, pull requests from non-committers may not run all the tests
automatically.
Plugins tests are run automatically on contributions using GitHub Actions. Depending on
your code contributions, various tests will be run against your updated code automatically.

Once you've gotten an LGTM from a project maintainer and once your PR has received
the green light from all our automated testing, wait for one the package maintainers
to merge the pull request and `pub submit` any affected packages.
to merge the pull request.

You must complete the
[Contributor License Agreement](https://cla.developers.google.com/clas).
Expand All @@ -107,30 +176,26 @@ organization's) name and contact info to the [AUTHORS](AUTHORS) file.

### 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:
* **Merging the PR** - if the PR can be quickly reviewed and looks good.
* **Closing the PR** - if the PR maintainer decides that the PR should not be merged.
* **Moving the PR to the backlog** - if the review requires non trivial effort and the issue isn't a priority; in this case the maintainer will:
* Make sure that the PR has an associated issue labeled with "plugin".
* Add the "backlog" label to the issue.
* Leave a comment on the PR explaining that the review is not trivial and that the issue will be looked at according to priority order.
* **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.

- **Merging the PR** - if the PR can be quickly reviewed and looks good.
- **Closing the PR** - if the PR maintainer decides that the PR should not be merged.
- **Moving the PR to the backlog** - if the review requires non trivial effort and the issue isn't a priority; in this case the maintainer will:
- Make sure that the PR has an associated issue labeled with "plugin".
- Add the "backlog" label to the issue.
- Leave a comment on the PR explaining that the review is not trivial and that the issue will be looked at according to priority order.
- **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.
We push releases manually, using [Melos](https://github.com/invertase/melos)
to take care of the hard work.

Changelogs and version updates are automatically updated by a project maintainer
(via [Melos](https://github.com/invertase/melos)). The new version is automatically
generated via the commit types and changelogs via the commit messages.

Some things to keep in mind before publishing the release:

Expand All @@ -150,45 +215,4 @@ 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.

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).
TODO(ehesp): detail melos release process

0 comments on commit 7b82c07

Please sign in to comment.