Contributing¶

Guidelines for contributing to the Catalog project.

Getting Started¶

Prerequisites¶

Ensure you have installed:

Flutter SDK (latest stable)
Dart SDK (included with Flutter)
IDE: VS Code or Android Studio with Flutter plugins
Git

Setup¶

Clone the repository:
```
git clone <repository-url>
cd Catalog
```
Install dependencies:
```
flutter pub get
```
Run the application:
```
flutter run
```

Development Workflow¶

Branch Strategy¶

master: Development branch, deploys to dev environment
qa: Quality assurance, deploys to QA environment
staging: Pre-production verification
prod: Production releases

Creating Features¶

Create a feature branch from master:

git checkout -b feature/your-feature-name

Make your changes
Write/update tests
Commit with descriptive messages
Push and create a pull request

Commit Messages¶

Follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Formatting changes
refactor: Code restructuring
test: Test additions/changes
chore: Maintenance tasks

Code Standards¶

Dart Style¶

Follow the official Dart Style Guide:

Use lowerCamelCase for variables and functions
Use UpperCamelCase for classes and types
Use lowercase_with_underscores for file names
Maximum line length: 80 characters

Linting¶

The project uses analysis_options.yaml for linting:

flutter analyze

Fix all warnings and errors before submitting.

Formatting¶

Format code using:

dart format .

Testing¶

Running Tests¶

# All tests
flutter test

# Specific test file
flutter test test/specific_test.dart

# With coverage
flutter test --coverage

Test Structure¶

Unit Tests: Test individual functions and classes
Widget Tests: Test UI components
Integration Tests: Test complete features

Writing Tests¶

Place tests in the test/ directory
Mirror the lib/ structure
Name test files with _test.dart suffix

Pull Requests¶

Requirements¶

Before submitting a PR:

[ ] All tests pass
[ ] No linting errors
[ ] Documentation updated (if applicable)
[ ] Commit messages follow conventions
[ ] Branch is up to date with target

Review Process¶

Create PR with descriptive title and body
Request review from team members
Address feedback
Squash and merge when approved

Documentation¶

Code Documentation¶

Document public APIs with /// doc comments
Include examples for complex functions
Keep documentation current with code changes

Project Documentation¶

Documentation lives in docs/source/:

Update relevant docs when changing features
Add new docs for new features
Build and preview locally:
```
cd docs
make html
```

Getting Help¶

Review existing documentation
Check issue tracker for known issues
Ask in team communication channels
Contact project maintainers