diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 000000000..8b645fe97 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,55 @@ +--- +name: Bug Report +about: Report a bug to help us improve +title: '[BUG] ' +labels: bug +assignees: '' +--- + +## Bug Description + + + +## Steps to Reproduce + +1. +2. +3. +4. + +## Expected Behavior + + + +## Actual Behavior + + + +## Screenshots + + + +## Environment + +- **OS**: [e.g., macOS 14.0, Windows 11, Ubuntu 22.04] +- **Flutter Version**: [e.g., 3.19.0] +- **Dart Version**: [e.g., 3.3.0] +- **Package Version**: [e.g., 1.0.0] +- **Platform**: [e.g., Web, iOS, Android, macOS, Windows, Linux] + +## Logs + + + +``` +Paste logs here +``` + +## Additional Context + + + +## Possible Solution + + + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 000000000..19855db97 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,47 @@ +--- +name: Feature Request +about: Suggest an idea for this project +title: '[FEATURE] ' +labels: enhancement +assignees: '' +--- + +## Feature Description + + + +## Problem Statement + + + + +## Proposed Solution + + + +## Alternatives Considered + + + +## Use Cases + + + +1. +2. +3. + +## Additional Context + + + +## Implementation Notes + + + +## Would you be willing to contribute this feature? + +- [ ] Yes, I'd like to work on this +- [ ] I could help with testing/review +- [ ] No, just suggesting + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..a5f33f477 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,60 @@ +## Summary + + + +## Related Issues + + + +## Changes Made + + +- +- +- + +## Type of Change + + +- [ ] ๐Ÿ› Bug fix (non-breaking change that fixes an issue) +- [ ] โœจ New feature (non-breaking change that adds functionality) +- [ ] ๐Ÿ’ฅ Breaking change (fix or feature that would cause existing functionality to change) +- [ ] ๐Ÿ“š Documentation update +- [ ] ๐Ÿ”ง Refactoring (no functional changes) +- [ ] ๐Ÿงช Test updates +- [ ] ๐Ÿ—๏ธ Build/CI changes + +## Testing + + + +### Test Checklist +- [ ] Unit tests pass (`flutter test`) +- [ ] Integration tests pass (if applicable) +- [ ] Manual testing completed +- [ ] Analyzer passes (`flutter analyze`) +- [ ] Code formatted (`dart format .`) + +### Testing Instructions + + +1. +2. +3. + +## Screenshots (if applicable) + + + +## Additional Notes + + + +--- + +### Reviewer Checklist +- [ ] Code follows project conventions +- [ ] Changes are well-documented +- [ ] Tests adequately cover the changes +- [ ] No unnecessary changes included + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..1f265a3f0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,357 @@ +# Contributing to Komodo DeFi SDK (Community Edition) + +Thank you for your interest in contributing to the Komodo DeFi SDK Community Edition! This guide will help you get started with contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Branching Strategy](#branching-strategy) +- [Branch Naming Conventions](#branch-naming-conventions) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Process](#pull-request-process) +- [Code Style](#code-style) +- [Testing](#testing) +- [Documentation](#documentation) + +## Code of Conduct + +By participating in this project, you agree to maintain a respectful and inclusive environment for everyone. Please be kind and constructive in all interactions. + +## Getting Started + +1. **Fork the repository** to your GitHub account +2. **Clone your fork** locally: + ```bash + git clone https://github.com/YOUR_USERNAME/komodo-defi-sdk-ce.git + cd komodo-defi-sdk-ce + ``` +3. **Add the upstream remote**: + ```bash + git remote add upstream https://github.com/CharlVS/komodo-defi-sdk-ce.git + ``` +4. **Keep your fork updated**: + ```bash + git fetch upstream + git checkout dev + git merge upstream/dev + ``` + +## Development Setup + +### Prerequisites + +- Flutter SDK (latest stable) +- Dart SDK (latest stable) +- Melos (for monorepo management) +- Git + +### Setup Steps + +1. Install dependencies: + ```bash + flutter pub get + ``` + +2. Bootstrap the monorepo (if using Melos): + ```bash + melos bootstrap + ``` + +3. Run tests to ensure everything is working: + ```bash + flutter test + ``` + +4. Run the analyzer: + ```bash + flutter analyze + ``` + +## Branching Strategy + +This project follows a **Gitflow-inspired** branching model: + +``` +main (stable releases) + โ”‚ + โ””โ”€โ”€ dev (integration branch) + โ”‚ + โ”œโ”€โ”€ feat/feature-name + โ”œโ”€โ”€ fix/bug-description + โ”œโ”€โ”€ refactor/component-name + โ””โ”€โ”€ ... (other feature branches) +``` + +### Main Branches + +| Branch | Purpose | Protection Level | +|--------|---------|------------------| +| `main` | Production-ready releases | ๐Ÿ”’ **Strictly protected** - Requires PR with approval | +| `dev` | Integration branch for features | ๐Ÿ”’ **Protected** - Requires PR with approval | + +### Branch Flow + +1. **Feature Development**: Create feature branches from `dev` +2. **Integration**: Merge feature branches into `dev` via PR +3. **Releases**: Merge `dev` into `main` for releases +4. **Hotfixes**: Create `hotfix/*` branches from `main`, merge to both `main` and `dev` + +## Branch Naming Conventions + +Use descriptive, lowercase branch names with the appropriate prefix: + +| Prefix | Purpose | Example | +|--------|---------|---------| +| `feat/` | New features or enhancements | `feat/wallet-connect-integration` | +| `add/` | Adding new functionality | `add/staking-support` | +| `fix/` | Bug fixes | `fix/balance-display-error` | +| `bugfix/` | Bug fixes (alternative) | `bugfix/activation-race-condition` | +| `hotfix/` | Urgent production fixes | `hotfix/critical-auth-issue` | +| `refactor/` | Code restructuring (no behavior change) | `refactor/withdrawal-manager` | +| `chore/` | Maintenance, dependencies, tooling | `chore/update-flutter-sdk` | +| `build/` | Build system or CI changes | `build/fix-android-signing` | +| `perf/` | Performance improvements | `perf/reduce-api-calls` | +| `test/` | Adding or updating tests | `test/withdrawal-integration` | +| `docs/` | Documentation updates | `docs/api-reference` | + +### Naming Rules + +- Use **lowercase** letters only +- Use **hyphens** (`-`) to separate words +- Keep names **concise but descriptive** +- Include **ticket/issue number** when applicable: `fix/123-balance-error` + +**Good Examples:** +- `feat/hardware-wallet-support` +- `fix/ios-crash-on-startup` +- `refactor/activation-coordinator` + +**Bad Examples:** +- `Feature_NewWallet` (wrong format) +- `fix` (too vague) +- `johns-branch` (not descriptive) + +## Commit Message Guidelines + +We follow [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +(): + +[optional body] + +[optional footer(s)] +``` + +### Types + +| Type | Description | +|------|-------------| +| `feat` | New feature | +| `fix` | Bug fix | +| `docs` | Documentation changes | +| `style` | Code style (formatting, semicolons, etc.) | +| `refactor` | Code refactoring | +| `perf` | Performance improvement | +| `test` | Adding or updating tests | +| `build` | Build system changes | +| `ci` | CI configuration changes | +| `chore` | Maintenance tasks | +| `revert` | Reverting a previous commit | + +### Examples + +```bash +feat(activation): add support for SIA coin activation + +fix(withdrawals): prevent duplicate transaction signing + +docs(readme): update installation instructions + +refactor(balance-manager): extract caching logic to separate class + +chore(deps): update flutter_bloc to v8.1.0 +``` + +### Rules + +- Use **imperative mood** ("add" not "added") +- Keep subject line under **72 characters** +- Don't end subject with a period +- Separate subject from body with blank line +- Use body to explain **what** and **why**, not how + +## Pull Request Process + +### Before Submitting + +1. โœ… Ensure your branch is up to date with `dev` +2. โœ… Run all tests: `flutter test` +3. โœ… Run the analyzer: `flutter analyze` +4. โœ… Format your code: `dart format .` +5. โœ… Update documentation if needed +6. โœ… Add/update tests for your changes + +### PR Guidelines + +1. **Target Branch**: All PRs should target `dev` (except hotfixes) +2. **Title**: Use conventional commit format +3. **Description**: Include: + - Summary of changes + - Related issue numbers (e.g., "Closes #123") + - Testing instructions + - Screenshots (for UI changes) +4. **Size**: Keep PRs focused and reasonably sized +5. **Draft**: Use draft PRs for work-in-progress + +### PR Template + +```markdown +## Summary +Brief description of changes + +## Related Issues +Closes #XXX + +## Changes Made +- Change 1 +- Change 2 + +## Testing +- [ ] Unit tests pass +- [ ] Integration tests pass +- [ ] Manual testing completed + +## Screenshots (if applicable) +``` + +### Review Process + +1. At least **1 approval** required for `dev` +2. All **status checks must pass** +3. **Resolve all comments** before merging +4. **Squash and merge** preferred for clean history + +## Code Style + +### Dart/Flutter Guidelines + +- Follow the [Dart Style Guide](https://dart.dev/guides/language/effective-dart/style) +- Use `dart format` for consistent formatting +- Maximum line length: **80 characters** +- Use **trailing commas** for better diffs + +### BLoC Architecture + +This project uses the BLoC pattern. Follow these conventions: + +```dart +// Naming conventions +class FeatureBloc extends Bloc {} +class FeatureLoading extends FeatureState {} +class FeatureLoaded extends FeatureState {} +class FeatureError extends FeatureState {} + +// Events +abstract class FeatureEvent {} +class LoadFeature extends FeatureEvent {} +class RefreshFeature extends FeatureEvent {} +``` + +### File Organization + +``` +lib/ +โ”œโ”€โ”€ src/ +โ”‚ โ”œโ”€โ”€ feature_name/ +โ”‚ โ”‚ โ”œโ”€โ”€ bloc/ +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ feature_bloc.dart +โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ feature_event.dart +โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ feature_state.dart +โ”‚ โ”‚ โ”œโ”€โ”€ models/ +โ”‚ โ”‚ โ”œโ”€โ”€ widgets/ +โ”‚ โ”‚ โ””โ”€โ”€ feature_page.dart +โ”‚ โ””โ”€โ”€ ... +โ””โ”€โ”€ feature_name.dart # barrel export +``` + +## Testing + +### Test Requirements + +- **Unit tests** for all business logic +- **Widget tests** for UI components +- **Integration tests** for critical flows + +### Running Tests + +```bash +# Run all tests +flutter test + +# Run tests with coverage +flutter test --coverage + +# Run specific test file +flutter test test/path/to/test_file.dart +``` + +### Test Naming + +```dart +void main() { + group('FeatureBloc', () { + test('emits [Loading, Loaded] when data is fetched successfully', () { + // ... + }); + + test('emits [Loading, Error] when fetch fails', () { + // ... + }); + }); +} +``` + +## Documentation + +- Update **README.md** for user-facing changes +- Add **dartdoc comments** for public APIs +- Update **CHANGELOG.md** for significant changes +- Include **inline comments** for complex logic + +### Dartdoc Example + +```dart +/// Manages coin activation across the SDK. +/// +/// This coordinator ensures only one activation task runs per [AssetId] +/// and provides shared results to all callers. +/// +/// Example: +/// ```dart +/// final coordinator = SharedActivationCoordinator(); +/// await coordinator.activate(assetId); +/// ``` +class SharedActivationCoordinator { + /// Activates the specified asset. + /// + /// Returns a [Future] that completes when activation succeeds. + /// Throws [ActivationException] if activation fails. + Future activate(AssetId assetId) async { + // ... + } +} +``` + +--- + +## Questions? + +If you have questions about contributing, feel free to: +- Open an issue with the `question` label +- Start a discussion in the Discussions tab + +Thank you for contributing! ๐ŸŽ‰ +