Contributing to Invenicum

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

Fork and Clone the Repository

Fork the Invenicum repository and clone it locally:

git clone https://github.com/YOUR_USERNAME/invenicum.git
cd invenicum

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

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.

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

Create a Feature Branch

Always create a new branch for your work:

git checkout -b feature/your-feature-name

Make Your Changes

Write clean, well-documented code following our coding standards (see below).

Test Thoroughly

Run tests and verify your changes work as expected:

flutter test

Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "feat: add loan reminder notifications"

See the Commit Message Guidelines below.

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

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

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

Link Related Issues

Reference any related issues:

Closes #123
Related to #456

Request Review

Tag relevant maintainers or team members for review.

Address Feedback

Respond to all comments
Make requested changes
Push updates to the same branch

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!

Architecture

Contributing

Contributing to Invenicum

Ways to Contribute

Getting Started

Development Workflow

Branching Strategy

Making Changes

Coding Standards

Dart/Flutter Conventions

Best Practices

Testing Guidelines

Writing Tests

Running Tests

Commit Message Guidelines

Pull Request Process

Code Review Guidelines

For Authors

For Reviewers

Community Guidelines

Code of Conduct

Getting Help

Next Steps

Plugin Development

Template Creation

Recognition

Build docs developers (and LLMs) love

Architecture

Contributing

​Ways to Contribute

​Getting Started

​Development Workflow

​Branching Strategy

​Making Changes

​Coding Standards

​Dart/Flutter Conventions

​Best Practices

​Testing Guidelines

​Writing Tests

​Running Tests

​Commit Message Guidelines

​Pull Request Process

​Code Review Guidelines

​For Authors

​For Reviewers

​Community Guidelines

​Code of Conduct

​Getting Help

​Next Steps

Plugin Development

Template Creation

​Recognition

Build docs developers (and LLMs) love

Ways to Contribute

Getting Started

Development Workflow

Branching Strategy

Making Changes

Coding Standards

Dart/Flutter Conventions

Best Practices

Testing Guidelines

Writing Tests

Running Tests

Commit Message Guidelines

Pull Request Process

Code Review Guidelines

For Authors

For Reviewers

Community Guidelines

Code of Conduct

Getting Help

Next Steps

Recognition