Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
162 lines (108 loc) · 6.26 KB

CONTRIBUTING.md

File metadata and controls

162 lines (108 loc) · 6.26 KB
Raw

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.

Branch Naming

Use the format git-username/type/short-description for branch names.

  • git-username should match your Git username or GitHub handle.
  • type should be a conventional change type according to conventional commits such as feat, fix, docs, test, or chore.
  • short-description should be lowercase, hyphen-separated, and describe the change.

For example: octocat/feat/add-http-timeout.

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.

If a PR should notify a linked issue after release, use a GitHub closing keyword in the PR description, such as Fixes #123, Closes #123, or Resolves #123. Release notification automation only comments on issues GitHub recognizes as closed by the released PR; mentioning an issue without a closing keyword is not enough.

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.

AI Use

You are welcome to use whatever tools you prefer for making a contribution. However, any changes you propose have to be reviewed and tested by you, a human, first, before you submit a pull request with them for the Sentry team to review. If we feel like that did not happen, we will close the PR outright. For example, we will not review visibly AI-generated PRs from an agent instructed to look for and "fix" open issues in the repo. This aligns with our SDK principle: every line has an owner.