Skip to content

Latest commit

 

History

History
164 lines (122 loc) · 6.72 KB

CONTRIBUTING.md

File metadata and controls

164 lines (122 loc) · 6.72 KB
Raw

Contributing

See also: Flutter's code of conduct

Contributor License Agreement

Contributions to this project must be accompanied by a Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

1. Things you will need

2. Forking & cloning the repository

  • Ensure all the dependencies described in the previous section are installed.
  • Fork https://github.com/googleads/googleads-mobile-flutter 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 to generate an SSH key.
  • git clone [email protected]:<your_name_here>/googleads-mobile-flutter.git
  • git remote add upstream [email protected]:googleads/googleads-mobile-flutter.git (So that you fetch from the master repository, not your clone, when running git fetch et al.)

3. Environment Setup

Follow the steps for installing Flutter and setting up an editor.

4. Running the example app

Run flutter pub get:

cd packages/google_mobile_ads
flutter pub get

Run the example app:

cd packages/google_mobile_ads/example
flutter run

4. Running tests

Unit tests

To run unit tests, use the following commands:

cd packages/google_mobile_ads
flutter test

5. Contributing code

We gladly accept contributions via GitHub pull requests.

Please peruse the Flutter style guide and design principles before working on anything non-trivial. These guidelines are intended to keep the code consistent and avoid common pitfalls.

To start working on a patch:

  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:

# Run the analyze check
dart analyze

# Format code. 
# Requires `flutter_plugin_tools` (`pub global activate flutter_plugin_tools`).
# Requires `clang-format` (can be installed via Brew on macOS).
dart pub global run flutter_plugin_tools format

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) or go to https://github.com/googleads/googleads-mobile-flutter and click the "Compare & pull request" button

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 guide.

Plugins tests are run automatically on contributions using GitHub Actions.

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.

You must complete the Contributor License Agreement. You can do this online, and it only takes a minute. If you've never submitted code before, you must add your (or your organization's) name and contact info to the AUTHORS file.

The review process

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.

The release process

We push releases manually. Changelogs and version updates are updated by a project maintainer.

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. 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.