> ## Documentation Index > Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Contributing to Invenicum > Learn how to contribute code, documentation, and improvements to the Invenicum project Welcome to the Invenicum contributor community! We're excited to have you here. Whether you're fixing bugs, adding features, improving documentation, or helping others, every contribution matters. ## Ways to Contribute There are many ways you can contribute to Invenicum: * **Code Contributions**: Fix bugs, add features, or improve performance * **Documentation**: Write guides, improve existing docs, or add examples * **Issue Reports**: Report bugs or suggest new features * **Code Reviews**: Review pull requests from other contributors * **Plugins & Templates**: Create extensions for the community marketplace * **Community Support**: Help others in discussions and issues ## Getting Started **1. Fork and Clone the Repository** Fork the [Invenicum repository](https://github.com/lopiv2/invenicum) and clone it locally: ```bash theme={null} git clone https://github.com/YOUR_USERNAME/invenicum.git cd invenicum ``` **2. Install Flutter and Dependencies** Invenicum is built with Flutter. You'll need: * **Flutter SDK** (latest stable version) * **Dart SDK** (comes with Flutter) * **Android Studio** or **Xcode** (for mobile development) * **Docker** (for running the backend locally) Install Flutter dependencies: ```bash theme={null} flutter pub get ``` **3. Set Up the Development Environment** Copy the environment configuration: ```bash theme={null} cp .env.example .env ``` Start the backend services using Docker Compose: ```bash theme={null} docker-compose up -d ``` Configure your Gemini API key in the `.env` file for AI features. **4. Run the Application** Start the Flutter app: ```bash theme={null} flutter run ``` For web development: ```bash theme={null} flutter run -d chrome ``` ## Development Workflow ### Branching Strategy We follow a simple branching model: * `main` - Production-ready code * `develop` - Integration branch for features * `feature/*` - New features (e.g., `feature/plugin-marketplace`) * `fix/*` - Bug fixes (e.g., `fix/loan-date-calculation`) * `docs/*` - Documentation updates ### Making Changes **1. Create a Feature Branch** Always create a new branch for your work: ```bash theme={null} git checkout -b feature/your-feature-name ``` **2. Make Your Changes** Write clean, well-documented code following our coding standards (see below). **3. Test Thoroughly** Run tests and verify your changes work as expected: ```bash theme={null} flutter test ``` **4. Commit Your Changes** Write clear, descriptive commit messages: ```bash theme={null} git add . git commit -m "feat: add loan reminder notifications" ``` See the Commit Message Guidelines below. **5. Push and Create a Pull Request** Push your branch and create a PR: ```bash theme={null} git push origin feature/your-feature-name ``` Go to GitHub and create a pull request against the `develop` branch. ## Coding Standards ### Dart/Flutter Conventions We follow the [official Dart style guide](https://dart.dev/guides/language/effective-dart/style) with some project-specific conventions: **File Structure** ``` lib/ ├── core/ # Core utilities, constants, themes ├── data/ # Models, services, repositories │ ├── models/ # Data models │ └── services/ # API and business logic services ├── providers/ # State management (Provider pattern) ├── screens/ # UI screens/pages └── widgets/ # Reusable UI components ``` **Naming Conventions** * **Classes**: `PascalCase` (e.g., `AssetTemplate`, `PluginService`) * **Files**: `snake_case` (e.g., `asset_template_model.dart`) * **Variables/Functions**: `camelCase` (e.g., `getUserName`, `isActive`) * **Constants**: `lowerCamelCase` (e.g., `defaultPageSize`) * **Private members**: Prefix with `_` (e.g., `_apiService`) **Code Style** ```dart theme={null} // Good: Clear service method with error handling Future> getUserLibrary() async { try { const url = '/templates/my-library'; final response = await _dio.get(url); if (response.statusCode == 200) { final List data = response.data; return data.map((json) => AssetTemplate.fromJson(json)).toList(); } return []; } on DioException catch (e) { throw _handleError(e); } } // Good: Well-documented model with clear properties class AssetTemplate { final String id; final String name; final String description; final List fields; AssetTemplate({ required this.id, required this.name, required this.description, required this.fields, }); } ``` ### Best Practices > **Use Meaningful Names** > > Choose names that clearly describe purpose: > > ```dart theme={null} > // Bad > var d = DateTime.now(); > var t = getT(); > > // Good > var createdAt = DateTime.now(); > var template = getTemplate(); > ``` > **Keep Functions Small** > > Functions should do one thing well. If a function is too long, break it into smaller functions. > > ```dart theme={null} > // Good: Single responsibility > Future installPlugin(Map pluginData) async { > await _dio.post('/plugins/install', data: pluginData); > } > ``` > **Handle Errors Gracefully** > > Always handle potential errors and provide meaningful feedback: > > ```dart theme={null} > try { > final template = await getTemplateById(id); > return template; > } on DioException catch (e) { > debugPrint('Error fetching template: ${e.message}'); > throw Exception('Unable to load template. Please try again.'); > } > ``` > **Document Complex Logic** > > Add comments for non-obvious code: > > ```dart theme={null} > // Calculate if the plugin is owned by the current user by comparing > // GitHub usernames (case-insensitive) > final bool calculatedIsMine = > currentUserGithub != null && > pluginAuthor.toLowerCase() == currentUserGithub.toLowerCase(); > ``` ## Testing Guidelines ### Writing Tests We use Flutter's built-in testing framework. Every new feature should include tests. **Unit Tests** (for services, models, utilities): ```dart theme={null} test('AssetTemplate.fromJson should parse JSON correctly', () { final json = { 'id': '123', 'name': 'Books Template', 'description': 'Template for book collections', 'category': 'Literature', 'fields': [], }; final template = AssetTemplate.fromJson(json); expect(template.id, '123'); expect(template.name, 'Books Template'); expect(template.category, 'Literature'); }); ``` **Widget Tests** (for UI components): ```dart theme={null} testWidgets('PluginCard displays plugin information', (tester) async { await tester.pumpWidget( MaterialApp( home: PluginCard( plugin: mockPlugin, ), ), ); expect(find.text('Test Plugin'), findsOneWidget); expect(find.text('v1.0.0'), findsOneWidget); }); ``` ### Running Tests ```bash theme={null} # Run all tests flutter test # Run specific test file flutter test test/services/plugin_service_test.dart # Run with coverage flutter test --coverage ``` ## Commit Message Guidelines We follow [Conventional Commits](https://www.conventionalcommits.org/): ``` ():