# Contributing to Face Detection TADI SDK

Thank you for your interest in contributing to the Face Detection TADI SDK! This document provides guidelines and instructions for contributing.

## Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

## How Can I Contribute?

### Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

- **Clear title**: Summarize the issue in the title
- **Description**: Detailed description of the bug
- **Steps to reproduce**: Step-by-step instructions
- **Expected behavior**: What you expected to happen
- **Actual behavior**: What actually happened
- **Environment**:
  - Flutter version (`flutter --version`)
  - Dart version
  - Plugin version
  - Platform (Android/iOS)
  - Device/Simulator info
- **Code samples**: Minimal reproducible example
- **Screenshots**: If applicable

### Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

- Use a clear and descriptive title
- Provide a detailed description of the proposed feature
- Explain why this enhancement would be useful
- Include code examples if applicable

### Pull Requests

1. **Fork the repository** and create your branch from `maven`
2. **Make your changes**:
   - Write clear, readable code
   - Follow the existing code style
   - Add tests for new functionality
   - Update documentation as needed
3. **Test your changes**:
   ```bash
   # Run tests
   flutter test

   # Run analysis
   dart analyze

   # Check formatting
   dart format --set-exit-if-changed .
   ```
4. **Commit your changes**:
   - Use clear, descriptive commit messages
   - Follow conventional commits format (see below)
5. **Push to your fork** and submit a pull request

## Development Setup

### Prerequisites

- Flutter SDK 3.3.0 or higher
- Dart SDK 3.10.3 or higher
- Android Studio / Xcode for platform-specific development
- Git

### Getting Started

```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/facedetect_tadi_sdk.git
cd facedetect_tadi_sdk

# Install dependencies
flutter pub get

# Run tests
flutter test

# Run example app
cd example
flutter run
```

### Project Structure

```
facedetect_tadi_sdk/
├── lib/
│   ├── models/                  # Data models
│   ├── facedetect_tadi_sdk.dart # Main SDK class
│   └── ...                      # Platform interfaces
├── android/                     # Android implementation
│   ├── src/main/kotlin/         # Kotlin source
│   └── maven-repo/              # Bundled native SDK
├── ios/                         # iOS implementation
│   ├── Classes/                 # Swift source
│   └── Frameworks/              # TGFISBIN framework
├── test/                        # Unit tests
├── example/                     # Example application
└── ...
```

## Coding Standards

### Dart Code Style

Follow the [official Dart style guide](https://dart.dev/guides/language/effective-dart/style):

```dart
// ✅ Good
class FaceDetectionConfig {
  final String accessToken;
  final bool useNative;

  const FaceDetectionConfig({
    required this.accessToken,
    this.useNative = true,
  });
}

// ❌ Bad
class face_detection_config {
  String AccessToken;
  bool use_native;
}
```

### Documentation

- Add dartdoc comments for all public APIs
- Use `///` for documentation comments
- Include code examples in documentation

```dart
/// Starts the face detection process.
///
/// Opens a native SDK screen for face detection and identity verification.
/// Returns [FaceDetectionResult] if successful, null if cancelled or failed.
///
/// Example:
/// ```dart
/// final result = await sdk.startFaceDetection(config);
/// if (result != null) {
///   print('Verified: ${result.firstName}');
/// }
/// ```
Future<FaceDetectionResult?> startFaceDetection(SdkConfig config);
```

### Testing

- Write tests for all new functionality
- Maintain test coverage above 60%
- Use descriptive test names

```dart
test('creates config with required parameters', () {
  final config = SdkConfig(accessToken: 'test_token');

  expect(config.accessToken, 'test_token');
  expect(config.useNative, true);
});
```

## Commit Message Guidelines

We use [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <subject>

<body>

<footer>
```

### Types

- **feat**: New feature
- **fix**: Bug fix
- **docs**: Documentation changes
- **style**: Code style changes (formatting, etc.)
- **refactor**: Code refactoring
- **test**: Adding or updating tests
- **chore**: Maintenance tasks

### Examples

```
feat(android): add camera shape configuration

Add support for circle and oval camera overlay shapes in Android implementation.

Closes #123
```

```
fix(ios): prevent crash when logo decoding fails

Handle Base64 decoding errors gracefully instead of force unwrapping.

Fixes #456
```

```
docs(readme): update installation instructions

Remove hardcoded credentials and clarify bundled SDK usage.
```

## Testing Guidelines

### Unit Tests

```bash
# Run all tests
flutter test

# Run specific test file
flutter test test/models/sdk_config_test.dart

# Run with coverage
flutter test --coverage
```

### Integration Tests

```bash
# Run integration tests
cd example
flutter test integration_test/
```

### Platform Tests

- **Android**: Test on real devices and emulators (API 24+)
- **iOS**: Test on real devices and simulators (iOS 13.0+)

## Pull Request Process

1. **Update documentation** for any user-facing changes
2. **Add/update tests** to cover your changes
3. **Ensure CI passes** (all tests, analysis, formatting)
4. **Update CHANGELOG.md** with your changes
5. **Request review** from maintainers
6. **Address feedback** from code review
7. **Squash commits** if requested

### PR Title Format

Use conventional commit format:

```
feat(android): add support for custom camera shapes
fix(ios): resolve memory leak in activity result handler
docs: update security best practices
```

## Code Review Process

All submissions require review. We use GitHub pull requests for this purpose:

- Maintainers will review your code
- Address any requested changes
- Once approved, maintainers will merge your PR

## Release Process

Maintainers handle releases:

1. Update version in `pubspec.yaml`
2. Update `CHANGELOG.md`
3. Create git tag
4. Publish to pub.dev
5. Create GitHub release

## Questions?

- **General questions**: Create a GitHub discussion
- **Bug reports**: Create a GitHub issue
- **Security issues**: See [SECURITY.md](SECURITY.md)
- **Email**: support@tadi.uz

## License

By contributing, you agree that your contributions will be licensed under the MIT License.

---

Thank you for contributing! 🎉
