Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
113 lines (81 loc) · 4.25 KB

CONTRIBUTING.md

File metadata and controls

113 lines (81 loc) · 4.25 KB
Raw

Contributing to FlutterProbe

Thank you for your interest in contributing to FlutterProbe! This guide explains how to get involved.

Reporting Bugs

Open an issue on GitHub Issues with:

  • A clear, descriptive title
  • Steps to reproduce the problem
  • Expected vs actual behavior
  • FlutterProbe version (probe --version), OS, Flutter version
  • Relevant .probe file snippets or error output

Pull Request Flow

  1. Fork the repository on GitHub
  2. Branch from main — use a descriptive name (e.g., fix/token-timeout, feat/swipe-direction)
  3. Develop your changes following the code style guidelines below
  4. Test your changes (see Testing section)
  5. Submit a PR against main with a clear description of what and why

Keep PRs focused on a single concern. If you have multiple unrelated changes, submit separate PRs.

Code Style

  • Go: Run gofmt (or goimports) on all .go files before committing. Follow standard Go conventions.
  • Dart: Run dart format . in the probe_agent/ directory. Follow Effective Dart guidelines.
  • ProbeScript: Use consistent 2-space indentation in .probe files.

DCO Sign-Off

All commits must include a Developer Certificate of Origin sign-off line:

Signed-off-by: Your Name <your@email.com>

Add this automatically with:

git commit -s -m "Your commit message"

This certifies that you wrote or have the right to submit the code under the project's license.

Testing

Before submitting a PR, run the full test suite:

make test                    # Go unit tests
cd probe_agent && flutter test  # Dart agent tests

For converter changes:

make test-convert            # Converter unit tests
make test-convert-integration  # Golden files + lint + dry-run

Ensure all tests pass and no regressions are introduced.

ProbeScript Language Changes

If your change affects the ProbeScript language (new syntax, modified parsing):

  1. Update the parser in internal/parser/
  2. Add or update parser tests covering the new syntax
  3. Add .probe test files in tests/ demonstrating the new feature
  4. Update golden files if converter output changes (make update-golden)
  5. Run make lint to verify all .probe files still parse correctly

API Stability & Deprecation Policy

flutter_probe_agent's public Dart API (anything exported from package:flutter_probe_agent/flutter_probe_agent.dart) is used directly by downstream apps' test code, so removing or changing it breaks real projects without warning if done carelessly. This happened once already: a minor version bump reduced the public API surface down to just ProbeAgent and isProbeEnabled, silently deleting a plugin-registration API (ProbePlugin/ProbePluginRegistry) that at least one downstream project had a load-bearing test-automation feature built on top of, with no deprecation cycle and no CHANGELOG migration note beyond "reduced public API."

To prevent a repeat, any removal or breaking change to the public API must follow this sequence:

  1. Deprecate first. Mark the old API @Deprecated('...') with a message naming the replacement, for at least one minor version before removal.
  2. Document the migration. The CHANGELOG entry for the deprecation must name the replacement pattern explicitly — not just "deprecated X" or "reduced public API."
  3. Remove in a later minor version, with its own CHANGELOG entry referencing the original deprecation.

If a use case the current public API supports (e.g. extending/customizing agent behavior from the app side) is intentionally being dropped rather than replaced, say so explicitly in the CHANGELOG and in the PR description — don't let it read as an oversight.

ProbePlugin/ProbePluginRegistry specifically: whether that capability should be reintroduced (under a deprecation-safe path this time) or the removal should stand as a permanent, intentional scope decision is a product call for the maintainer, not something this policy resolves on its own — it's tracked as an open question in IMPROVEMENT_TASKS.md (PT-08) pending that decision.

Questions?

If you are unsure about anything, open an issue to discuss before starting work. We are happy to help guide contributions.