# Contributing Guidelines

Thank you for your interest in contributing to EXIM ERP! This document provides guidelines and standards for contributing to this project.

## Getting Started

### Prerequisites

- PHP 8.3+
- Composer 2.0+
- Node.js 18+
- MySQL 8.0+
- Redis 7.0+

### Development Setup

1. Fork the repository
2. Clone your fork:
   ```bash
   git clone https://github.com/your-username/exim-erp.git
   cd exim-erp
   ```

3. Install dependencies:
   ```bash
   composer install
   npm install
   ```

4. Configure environment:
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```

5. Set up database:
   ```bash
   php artisan migrate
   php artisan db:seed
   ```

6. Start development server:
   ```bash
   php artisan serve
   ```

## Branch Naming

Use descriptive branch names with prefixes:

- `feature/` - New features
- `fix/` - Bug fixes
- `hotfix/` - Critical production fixes
- `refactor/` - Code refactoring
- `docs/` - Documentation updates
- `test/` - Test additions/updates

Examples:
```
feature/add-customer-export
fix/invoice-calculation-error
hotfix/security-patch
refactor/order-service
docs/api-documentation
test/order-repository
```

## Commit Messages

Follow the Conventional Commits specification:

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

<body>

<footer>
```

### Types

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

### Examples

```
feat(orders): add bulk export functionality

Added ability to export multiple orders to CSV format.
Includes filtering options for date range and status.

Closes #123
```

```
fix(invoices): correct tax calculation for international orders

Fixed issue where tax was not being calculated correctly
for orders with international shipping addresses.

Fixes #456
```

## Code Style

### PHP Standards

Follow PSR-12 coding standards:

```php
<?php

declare(strict_types=1);

namespace App\Services;

use App\Models\Order;
use App\Repositories\OrderRepositoryInterface;

class OrderService
{
    public function __construct(
        private OrderRepositoryInterface $repository
    ) {}

    public function createOrder(array $data): Order
    {
        // Implementation
    }
}
```

### Key Points

- Use strict types declaration
- Use constructor property promotion
- Use named arguments for clarity
- Keep methods focused and small
- Use meaningful variable names
- Add type hints for all parameters and return types

### JavaScript Standards

- Use ES6+ features
- Follow ESLint configuration
- Use meaningful variable names
- Add JSDoc comments for complex functions

### Blade Templates

- Use meaningful component names
- Keep templates clean and readable
- Use Blade components for reusable elements
- Avoid business logic in templates

## Testing Requirements

### Unit Tests

Write unit tests for:
- Services
- Repositories
- Helper functions
- Models

```php
<?php

namespace Tests\Unit;

use App\Services\OrderService;
use PHPUnit\Framework\TestCase;

class OrderServiceTest extends TestCase
{
    public function test_create_order_returns_order_instance(): void
    {
        // Test implementation
    }
}
```

### Feature Tests

Write feature tests for:
- API endpoints
- Controller actions
- Authentication flows

```php
<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;

class OrderApiTest extends TestCase
{
    use RefreshDatabase;

    public function test_can_create_order(): void
    {
        // Test implementation
    }
}
```

### Test Coverage

Maintain minimum test coverage:
- Unit tests: 80%
- Feature tests: 70%
- Overall: 75%

Run tests:
```bash
php artisan test
php artisan test --coverage
```

## Pull Request Process

### 1. Create Your Branch

```bash
git checkout -b feature/your-feature
```

### 2. Make Changes

- Write clean, documented code
- Add tests for new functionality
- Update documentation if needed

### 3. Run Tests

```bash
php artisan test
npm run test
```

### 4. Update Documentation

- Update README if adding new features
- Update API documentation for new endpoints
- Add inline comments for complex logic

### 5. Commit Changes

```bash
git add .
git commit -m "feat(module): add new feature"
```

### 6. Push to Fork

```bash
git push origin feature/your-feature
```

### 7. Create Pull Request

- Provide a clear title and description
- Reference any related issues
- Include screenshots for UI changes
- Ensure all tests pass

### 8. Code Review

- Address reviewer feedback
- Make requested changes
- Re-request review when ready

### 9. Merge

- Squash and merge for clean history
- Delete feature branch after merge

## Code Review Checklist

### General

- [ ] Code follows PSR-12 standards
- [ ] No security vulnerabilities
- [ ] No hardcoded values
- [ ] Proper error handling
- [ ] Logging for important events

### Functionality

- [ ] Feature works as expected
- [ ] Edge cases handled
- [ ] Performance considered
- [ ] Backward compatible

### Testing

- [ ] Unit tests added/updated
- [ ] Feature tests added/updated
- [ ] All tests passing
- [ ] Test coverage adequate

### Documentation

- [ ] Code comments added
- [ ] README updated (if needed)
- [ ] API docs updated (if needed)
- [ ] Changelog updated (if needed)

## Security Guidelines

### Never Commit

- `.env` files
- API keys or secrets
- Database credentials
- SSL certificates
- User passwords

### Report Security Issues

If you discover a security vulnerability:

1. **DO NOT** open a public issue
2. Email security@exim-erp.com with details
3. Include steps to reproduce
4. Allow time for a fix before disclosure

## Issue Reporting

### Bug Reports

Include:
- Steps to reproduce
- Expected behavior
- Actual behavior
- Environment details
- Screenshots (if applicable)

### Feature Requests

Include:
- Clear description
- Use case
- Proposed solution
- Alternatives considered

## Development Workflow

### Daily Development

1. Pull latest changes
2. Create feature branch
3. Make changes
4. Write tests
5. Run test suite
6. Update documentation
7. Create pull request

### Code Quality Tools

Run before committing:
```bash
# PHP CS Fixer
./vendor/bin/php-cs-fixer fix

# PHPStan
./vendor/bin/phpstan analyse

# ESLint
npm run lint
```

## Communication

### Channels

- **GitHub Issues**: Bug reports and feature requests
- **GitHub Discussions**: General questions and ideas
- **Pull Requests**: Code contributions

### Response Time

- Issues: 2-3 business days
- Pull Requests: 1-2 business days
- Security Reports: 24 hours

## Recognition

Contributors will be recognized in:
- README.md
- CHANGELOG.md
- Release notes

Thank you for contributing to EXIM ERP!
