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 and clone it locally:

   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:

   flutter pub get
   
3. Set Up the Development Environment

   Copy the environment configuration:

   cp .env.example .env
   

   Start the backend services using Docker Compose:

   docker-compose up -d
   

   Configure your Gemini API key in the .env file for AI features.

4. Run the Application

   Start the Flutter app:

   flutter run
   

   For web development:

   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:

   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:

   flutter test
   
4. Commit Your Changes

   Write clear, descriptive commit messages:

   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:

   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 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

// Good: Clear service method with error handling
Future<List<AssetTemplate>> getUserLibrary() async {
  try {
    const url = '/templates/my-library';
    final response = await _dio.get(url);
    
    if (response.statusCode == 200) {
      final List<dynamic> 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<CustomFieldDefinition> 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:

// 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.

// Good: Single responsibility
Future<void> installPlugin(Map<String, dynamic> pluginData) async {
  await _dio.post('/plugins/install', data: pluginData);
}

Handle Errors Gracefully

Always handle potential errors and provide meaningful feedback:

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:

// 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):

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):

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

# 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:

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

<body>

<footer>

Types:

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

Examples:

feat(plugins): add plugin update notification system
fix(loans): correct overdue date calculation
docs(api): update authentication endpoint documentation
refactor(templates): simplify template publishing workflow

Pull Request Process

1. Prepare Your PR

   • Ensure your branch is up to date with develop
   • All tests pass
   • Code follows style guidelines
   • Commits are clean and well-structured
2. Write a Clear Description

   Your PR should include:

   • What: Clear summary of changes
   • Why: Problem being solved or feature being added
   • How: Technical approach (if complex)
   • Testing: How you tested the changes
   • Screenshots: For UI changes
3. Link Related Issues

   Reference any related issues:

   Closes #123
   Related to #456
   
4. Request Review

   Tag relevant maintainers or team members for review.

5. Address Feedback

   • Respond to all comments
   • Make requested changes
   • Push updates to the same branch
6. Merge

   Once approved, a maintainer will merge your PR.

Code Review Guidelines

For Authors

• Be open to feedback and constructive criticism
• Respond to comments promptly
• Ask questions if feedback is unclear
• Don’t take criticism personally - it’s about the code, not you

For Reviewers

• Be respectful and constructive
• Explain the “why” behind suggestions
• Approve when changes meet standards
• Focus on:
  • Correctness and functionality
  • Code quality and maintainability
  • Performance implications
  • Security concerns
  • Test coverage

Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment:

• Be respectful: Treat everyone with respect and kindness
• Be collaborative: Work together toward the best solutions
• Be patient: Help newcomers and be understanding
• Be constructive: Provide helpful feedback
• Be professional: Keep discussions focused and productive

Getting Help

• Documentation: Check the docs first
• Discussions: Use GitHub Discussions for questions
• Issues: Search existing issues before creating new ones
• Discord/Slack: Join our community channels (if available)

Next Steps

Ready to contribute?

Plugin Development

Create custom plugins to extend Invenicum’s functionality

Template Creation

Build asset templates for specialized collections

Recognition

All contributors are recognized in our:

• GitHub contributors list
• Release notes (for significant contributions)
• Community showcase

Thank you for contributing to Invenicum!