Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
142 lines (96 loc) · 4.91 KB

CONTRIBUTING.md

File metadata and controls

142 lines (96 loc) · 4.91 KB

Contributing to Sentry Dart & Flutter

Thank you for your interest in contributing to Sentry's Dart and Flutter SDKs! This guide will help you get started.

Prerequisites

Required Tools

  • Dart SDK >=3.5.0 - Required for all packages
  • Flutter SDK >=3.24.0 - Required for sentry-flutter and Flutter integrations
  • fvm - For Flutter/Dart version management
  • melos - For managing the monorepo

Environment Setup

1. Install fvm and melos

dart pub global activate fvm
dart pub global activate melos

2. Install the Flutter SDK via fvm

fvm use stable

This reads .fvmrc and installs the pinned Flutter version. It also creates a .fvm/flutter_sdk symlink that melos uses to resolve dart/flutter commands (via sdkPath in melos.yaml).

3. Bootstrap the project

melos bootstrap

This resolves all package dependencies and configures git hooks for pre-commit checks.

Project Structure

Core SDKs

Integration Packages

Located under packages/, we maintain integrations for popular Dart/Flutter libraries:

  • sentry_dio - HTTP client integration for dio
  • sentry_logging - Integration for the logging package
  • sentry_sqflite - Integration for sqflite database
  • sentry_drift - Integration for drift database
  • sentry_hive - Integration for hive database
  • sentry_isar - Integration for isar database
  • sentry_file - Integration for File I/O operations
  • sentry_link - Integration for GraphQL via gql_link
  • sentry_firebase_remote_config - Integration for firebase_remote_config

Platform Support

The Flutter SDK supports the following platforms:

  • iOS
  • macOS
  • Android
  • Web
  • Linux
  • Windows

We test the example app on Windows, macOS, and Linux to ensure cross-platform compatibility. CI runs against Flutter stable and beta channels.

Native SDK Dependencies

The Flutter SDK embeds platform-specific native SDKs:

Pre-commit Hooks

After melos bootstrap, git is configured to use .githooks/ for hooks. The pre-commit hook automatically:

  1. Auto-formats staged .dart files and re-stages them
  2. Runs dart analyze on changed Dart-only packages
  3. Runs flutter analyze on changed Flutter packages

Only packages with staged changes are analyzed — no need to wait for the full monorepo.

Changelog

Changelogs are generated automatically during the release process using craft. The policy is defined in .github/release.yml.

PR titles must follow Conventional Commits format (e.g., feat(scope): Add feature, fix: Handle null) since craft uses them to categorize entries and determine the semver bump. No manual changelog entries are needed. A changelog preview is posted on each PR so you can verify how the entry will look before merging.

If a PR should be excluded from the changelog, apply the skip-changelog label.

Custom Changelog Entries from PR Descriptions

By default, the changelog entry for a PR is generated from its title. However, PR authors can override this by adding a "Changelog Entry" section to the PR description. This allows for more detailed, user-facing changelog entries without cluttering the PR title.

Add a markdown heading (level 2 or 3) titled "Changelog Entry" to your PR description, followed by the desired changelog text:

### Description

Add `foo` function, and add unit tests to thoroughly check all edge cases.

### Motivation & Context

Closes #123

### Changelog Entry

Add a new function called `foo` which prints "Hello, world!"

The text under "Changelog Entry" will be used verbatim in the changelog instead of the PR title. If no such section is present, the PR title is used as usual.

Code Style

We follow Effective Dart conventions.