# 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

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd Catalog
   ```

2. Install dependencies:
   ```bash
   flutter pub get
   ```

3. Run the application:
   ```bash
   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

1. Create a feature branch from `master`:
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. Make your changes
3. Write/update tests
4. Commit with descriptive messages
5. 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](https://dart.dev/guides/language/effective-dart/style):

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

```bash
flutter analyze
```

Fix all warnings and errors before submitting.

### Formatting

Format code using:

```bash
dart format .
```

## Testing

### Running Tests

```bash
# 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

1. Create PR with descriptive title and body
2. Request review from team members
3. Address feedback
4. 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:
  ```bash
  cd docs
  make html
  ```

## Getting Help

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