Contributing to OpenTelemetry SDK for Flutter

May 27, 2025 · View on GitHub

Thank you for your interest in contributing to the OpenTelemetry SDK for Flutter! This document provides guidelines and instructions for contributing to this project.

Code of Conduct

This project follows the CNCF Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Ways to Contribute

There are many ways to contribute to this project:

Code contributions: Implement new features or fix bugs
Documentation: Improve or extend documentation
Bug reports: Submit detailed bug reports
Feature requests: Suggest new features or improvements
Reviews: Review pull requests from other contributors
Discussions: Participate in discussions and help shape the project

Getting Started

Setting Up Development Environment

Fork the repository

Clone your fork:

git clone https://github.com/YOUR_USERNAME/flutterrific_opentelemetry.git
cd flutterrific_opentelemetry

Add the upstream repository:

git remote add upstream https://github.com/MindfulSoftwareLLC/flutterrific_opentelemetry.git

Install dependencies:
```
flutter pub get
```

Development Workflow

Create a new branch for your work:

git checkout -b feature/your-feature-name

Make your changes
Run tests to ensure everything works:
```
flutter test
```
Run the analyzer:
```
flutter analyze
```
Format your code:
```
dart format .
```

Commit your changes with a descriptive commit message:

git commit -m "Add feature: description of your changes"

Push your branch to your fork:

git push origin feature/your-feature-name

Create a pull request to the main repository

Pull Request Process

Update the README.md or other documentation with details of changes if appropriate
Update the CHANGELOG.md with a description of your changes
The PR should work with the latest version of Flutter and be compatible with all supported platforms (Android, iOS, Web)
The PR will be merged once it receives approval from project maintainers

Coding Standards

Code Style

This project follows the official Dart style guide and uses the standard Dart formatting tool (dart format).

Linting Rules

We use the recommended Flutter linting rules. Always run flutter analyze before submitting a PR to ensure your code follows these rules.

Testing

All new code should be covered by tests. We use the flutter_test package for writing and running tests.

All tests should be in the test directory
Test files should end with _test.dart
Run tests with flutter test
Widget tests should use flutter_test testing utilities
Unit tests for non-Flutter code should use the test package

Documentation

All public APIs must have dartdoc comments
Comments should explain "why" not just "what"
Example usage is encouraged for complex functionality
Flutter-specific documentation should include widget usage examples

Flutter-Specific Considerations

Platform Support

When contributing to this Flutter SDK:

Consider all supported platforms: Android, iOS, Web, Desktop
Test on multiple platforms when possible
Handle platform-specific limitations gracefully
Use conditional imports when necessary for platform-specific code

Follow Flutter's widget composition patterns
Use Flutter's lifecycle methods appropriately
Consider performance implications for widget rebuilds
Provide easy-to-use widget extensions when appropriate

Support multiple navigation patterns (Navigator 1.0, Navigator 2.0, third-party routers)
Make navigation integration optional and configurable
Document integration patterns for popular routing packages