Skip to content

Latest commit

 

History

History
296 lines (201 loc) · 10.5 KB

CONTRIBUTING.md

File metadata and controls

296 lines (201 loc) · 10.5 KB
Raw

Contributing to Google Maps Navigation Flutter Plugins

See also: Flutter's code of conduct

1. Essential Setup for Contributors

  • Operating System: Linux, macOS, or Windows.
  • Version Control: git.
  • Development Environment: An IDE such as Android Studio or Visual Studio Code.
  • Code Formatting: swiftformat (available via brew on macOS, on Windows install Swift toolchain and build SwiftFormat from git sources).

1.1. Installing swiftformat

The CI is locked to swiftformat 0.54.6 version which you can install with the command below:

curl -O https://raw.githubusercontent.com/Homebrew/homebrew-core/4564fbc21a326c4eb349327ce327cbe983bf302a/Formula/s/swiftformat.rb
brew install swiftformat.rb

2. Setting Up Your Local Repository

  • Preparation: Before starting, make sure you have all dependencies installed as mentioned in the prior section.
  • Fork the Repository: Navigate to https://github.com/googlemaps/flutter-navigation-sdk and create a fork in your GitHub account.
  • SSH Key Configuration: If your machine doesn't have an SSH key registered with GitHub, generate one following the instructions at Generating SSH Keys on GitHub..
  • Clone Your Fork: Use the command git clone [email protected]:<your_name_here>/google_maps_flutter_navigation.git to clone the repository to your local machine.
  • Add remote upstream: Establish a link to the main repository for updates using command git remote add upstream [email protected]:googlemaps/flutter-navigation-sdk.git This ensures you pull changes from the original source, not just your clone, when using git fetch and similar commands.

3. Install Melos

This project leverages Melos to manage the project and its dependencies.

Run the following command to install Melos:

dart pub global activate melos

4. Automatically generated MethodChannel with Pigeon

Using pigeon

Google Maps Navigation Flutter Plugins utilizes pigeon to generate the MethodChannel API layer between Dart and the native platforms. To modify the messages sent with Pigeon (i.e., the API code between Dart and native platforms), you can edit the pigeons/messages.dart file in the corresponding folder and regenerate the code by running the following melos command:

melos run generate:pigeon

Remember to format the generated files using the formatter.

Note

The melos script automatically runs the formatter after pigeon generation.

Testing pigeon generated code

To test the created interface, you can mock the interface directly with:

late MockTestNAMEHostApi mockApi;
TestNAMEHostApi.setup(mockApi);

Add a unit test to a new method:

  1. Mock the return value (if the function has one).
when(mockApi.newMethod(any)).thenReturn(returnValueIn);
  1. Call the public API.
returnValueOut = await GoogleMapsNavigationPlatform.instance.newMethod(parameterIn)
  1. Check that the parameters and return values passed between the public API and platform match.
final VerificationResult result = verify(mockApi.newMethod(captureAny));
final MyType parameterOut = result.captured[0] as MyType;
expect(parameterIn.param, parameterOut.param)
expect(returnValueIn.param, returnValueOut.param)

See examples in test/ folders.

5. Running the Navigation Example

The Google Maps Flutter Navigation plugin provides an example app that showcases its main use-cases.

To run the Navigation example, navigate to the example directory of the plugin and run the app:

cd example
flutter run --dart-define MAPS_API_KEY=YOUR_API_KEY

6. Running tests

Google Maps Flutter Navigation package has integration and unit tests.

Unit tests

To run unit tests for the Google Maps Flutter Navigation plugin, navigate to the plugin's root directory and execute the flutter test command. Use the following command:

melos run test:dart

To run unit tests on Android call

melos run test:android

To run unit tests on iOS, follow these steps:

  1. Open Xcode.
  2. Navigate to the Test Navigator.
  3. Find and select the "RunnerTests" target.
  4. Click on the play icon button to run the tests.

Or to run the iOS unit tests from command line, call

DEVICE='iPhone 15' melos run ios:test

Specify the device you want to run the tests on with the DEVICE env variable.

Integration tests

Integration tests are responsible for ensuring that the plugin works against the native Navigation SDK for both Android and iOS platforms. Patrol is used for the integration tests to simplify interactions with native elements. To use patrol, you first need to activate the patrol_cli.

flutter pub global activate patrol_cli 3.2.0

To ensure that all necessary dependencies for patrol are properly set up, run the following command:

patrol doctor

Google Maps Flutter Navigation integration tests can be run with the following command:

cd ./example
patrol test --dart-define MAPS_API_KEY=YOUR_API_KEY

To only run a specific test file, use patrol command with -t flag. For example to run a navigation_test.dart run it with the following command:

cd ./example
patrol test --dart-define MAPS_API_KEY=YOUR_API_KEY -t integration_test/navigation_test.dart

Test report should appear in the build folder:

Android - example/build/app/reports/androidTests/connected/debug/index.html
iOS - example/build/ios_results_*.xcresult

When adding new tests, add the location dialog and ToS check to the beginning of each test.

    await checkLocationDialogAndTosAcceptance($);

For debugging the tests, you can add debugPrint() functions in your test and use patrol develop mode with the --verbose flag to see the printed messages. To run navigation_test.dart in develop mode, use the following command:

cd ./example
patrol develop --dart-define MAPS_API_KEY=YOUR_API_KEY --verbose -t integration_test/navigation_test.dart

Please note that the "hot restart" feature in patrol's develop mode may not work correctly with all test files.

Android emulator setup

If the patrol tests fail to run on the Android emulator due to insufficient RAM, increase the emulator's default RAM allocation to ensure proper test execution.

7. Contributing code

We welcome contributions through GitHub pull requests.

Before working on any significant changes, please review the Flutter style guide and design principles. These guidelines help maintain code consistency and avoid common pitfalls.

To begin working on a patch, follow these steps:

  1. Fetch the latest changes from the upstream repository:

    git fetch upstream

  2. Create a new branch based on the latest upstream master branch:

    git checkout upstream/master -b <name_of_your_branch>

  3. Start coding!

Before committing your changes, it's important to ensure that your code passes the internal analyzer and formatting checks. You can run the following commands locally to identify any issues:

  • Run the analyze check:

    melos run flutter-analyze

  • Format your code:

    melos run format

If you have made changes to pigeon messages, don't forget to generate the necessary code by running:

melos run generate:pigeon

If you have changed files that have mocked tests, make sure to run the following command:

melos run generate:mocks

And run affecting tests locally to make sure they still pass.

Assuming all is successful, commit and push your code using the following commands:

  1. Stage your changes:
git add .
  1. Commit your changes with an informative commit message:
git commit -m "<your informative commit message>"
  1. Push your changes to the remote repository:
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/googlemaps/flutter-navigation-sdk and click the "Compare & pull request" button

Please ensure that all your commits have detailed commit messages explaining the changes made.

When naming the title of your pull request, please follow the Conventional Commits guide. For example, for a fix to the plugin:

fix: Fixed a bug!

Automated tests will be run on your contributions using GitHub Actions. Depending on your code changes, various tests will be performed automatically.

Once you have received an LGTM (Looks Good To Me) from a project maintainer and once your pull request has passed all automated tests, please wait for one of the package maintainers to merge your changes.

Before contributing, please ensure that you have completed the Contributor License Agreement. This can be done online and only takes a few moments. If you are submitting code for the first time, please add your (or your organization's) name and contact information to the AUTHORS file.

This project uses Google's addlicense here tool to add the license header to all necessary files. Running addlicense is a required step before committing any new files.

To install addlicense, run:

go install github.com/google/addlicense@latest

Make sure to include $HOME/go/bin in your PATH environment variable. If you are using Bash on Linux or macOS, add export PATH="$HOME/go/bin:$PATH" to your .bash_profile.

To add the license header to all files, run the following command from the root of the repository:

melos run add-license-header

This command uses addlicense with all necessary flags.

To check the license header of all files, run from the root of the repository:

melos run check-license-header

8. Contributing documentation

We welcome contributions to the plugin documentation. The documentation for this project is generated using Dart Docs. All documentation for the app-facing API is described in Dart files.

Please refer to the "Contributing code" section above for instructions on how to prepare and submit a pull request to the repository.