# Development Workflow Guide

This project uses a comprehensive development workflow that includes code formatting, linting, and git hooks to ensure code quality and consistent development practices.

## 🛠️ Tools & Technologies

- **PHP**: Laravel Pint (code formatting)
- **JavaScript**: ESLint + Prettier (linting & formatting)
- **Git Hooks**: Husky + custom scripts (branch protection & validation)
- **Commit Messages**: Commitlint (conventional commits)

## 📋 Quick Start

> **🚀 New to this project?** Start with the **[Setup Guide](SETUP.md)** for step-by-step installation instructions.

For experienced users:

1. **Install Dependencies**: `composer install && npm install`
2. **Setup Git Hooks**: `npx husky init`  
3. **Test Setup**: `npm run pint:check && npm run lint:check`

## 🎯 Branch Guidelines

### Recommended Branch Naming
For better organization, consider using this pattern:
```
type/description-with-hyphens
```

**Suggested types:**
- `feature/` - New features
- `fix/` - Bug fixes
- `hotfix/` - Critical production fixes
- `chore/` - Maintenance tasks
- `docs/` - Documentation updates
- `refactor/` - Code refactoring
- `test` - Test additions/modifications

**Examples:**
```bash
git checkout -b feature/user-authentication
git checkout -b fix/login-validation-bug
git checkout -b chore/update-dependencies
```

> **Note**: Branch naming is now optional - you can use any branch name you prefer.

## 📝 Commit Message Format

We use [Conventional Commits](https://www.conventionalcommits.org/) format:

```
type(scope): subject

body

footer
```

**Examples:**
```bash
git commit -m "feat(auth): add user login functionality"
git commit -m "fix(api): resolve user validation error"
git commit -m "docs: update installation instructions"
```

**Allowed types:**
- `feat` - New features
- `fix` - Bug fixes
- `docs` - Documentation changes
- `style` - Code style changes (formatting, etc)
- `refactor` - Code refactoring
- `perf` - Performance improvements
- `test` - Test changes
- `build` - Build system changes
- `chore` - Maintenance tasks
- `revert` - Revert previous changes

## 🔧 Available Scripts

### PHP (Laravel Pint)
```bash
# Format PHP code
npm run pint

# Check PHP code style (dry run)
npm run pint:check
```

### JavaScript/CSS
```bash
# Run ESLint and fix issues
npm run lint

# Check ESLint without fixing
npm run lint:check

# Format with Prettier
npm run format

# Check Prettier formatting
npm run format:check
```

## 🚀 Development Workflow

1. **Create Branch** (any name works):
   ```bash
   git checkout -b your-branch-name
   ```

2. **Make Changes**: Write your code

3. **Commit** (hooks will automatically run):
   ```bash
   git add .
   git commit -m "feat: add new feature"
   ```
   
   The pre-commit hook will:
   - Run Laravel Pint on **staged PHP files only**
   - Run ESLint on **staged JavaScript files only**
   - Run Prettier on **staged applicable files only**
   - Validate commit message format

4. **Push** (pre-push hook will show info):
   ```bash
   git push origin your-branch-name
   ```

5. **Optional**: Create Pull Request to merge into `develop` or `main`

## ⚡ Smart File Processing (lint-staged)

**Important**: The linting and formatting tools only run on **files you've changed and staged**, not all files in the project!

### 📁 Only Changed Files Get Processed

Thanks to **lint-staged**, the pre-commit hooks are smart and efficient:

- ✅ **Only staged files** are processed
- ✅ **Only modified files** get linted/formatted
- ❌ **NOT all files** in the project

### 📝 Example Scenarios

**Scenario 1: You modify 2 PHP files**
```bash
git add app/Models/User.php
git add app/Http/Controllers/AuthController.php
git commit -m "feat: update user model"

# Laravel Pint will ONLY run on:
# - app/Models/User.php
# - app/Http/Controllers/AuthController.php
```

**Scenario 2: Mixed file types**
```bash
git add resources/js/app.js
git add app/Models/Product.php
git commit -m "feat: add product features"

# During commit:
# - ESLint + Prettier runs on: resources/js/app.js
# - Laravel Pint runs on: app/Models/Product.php
# - Nothing else is touched
```

### ⚡ Performance Benefits

- **Quick commits** - only processes changed files
- **No waiting** - doesn't scan entire codebase
- **Focused fixes** - only fixes what you're working on
- **Faster development** - especially useful in large projects

### 🛠️ Manual Full Project Processing

If you want to run tools on **all files** (not just staged):

```bash
# Run Pint on entire project
npm run pint

# Run ESLint on all JS files
npm run lint

# Run Prettier on all applicable files
npm run format
```

## 🛡️ What Gets Checked

### Pre-commit Hooks
- ✅ PHP code formatting (Laravel Pint) - **staged files only**
- ✅ JavaScript linting (ESLint) - **staged files only**
- ✅ Code formatting (Prettier) - **staged files only**
- ✅ Commit message format

> **Note**: All linting and formatting only applies to files you've staged (`git add`), not the entire project.

### Pre-push Hooks
- ✅ Warning for force pushes
- ✅ Informational messages about push targets

## 🚫 Bypassing Hooks (Not Recommended)

In rare cases, you can bypass hooks with:
```bash
git commit --no-verify -m "emergency fix"
git push --no-verify
```

**⚠️ Warning**: This bypasses all local code quality checks.

## 🔧 Configuration Files

- `pint.json` - Laravel Pint (PHP) configuration
- `.eslintrc.js` - ESLint configuration
- `.prettierrc` - Prettier configuration
- `.editorconfig` - Editor configuration
- `commitlint.config.cjs` - Commit message rules
- `.husky/` - Git hooks
- `commands/` - Custom validation scripts

## 🆘 Troubleshooting

### Hook Not Running
```bash
# Reinstall hooks
rm -rf .husky
npx husky init
chmod +x .husky/pre-commit .husky/pre-push .husky/commit-msg
```

### Only Some Files Getting Processed
This is normal behavior! lint-staged only processes **staged files** (files you've added with `git add`). If you want to process all files:

```bash
# Process all files manually
npm run pint        # All PHP files
npm run lint        # All JS files  
npm run format      # All applicable files
```

### PHP Pint Issues
```bash
# Check what files will be affected
vendor/bin/pint --test

# Fix specific file
vendor/bin/pint app/Http/Controllers/UserController.php
```

### ESLint Issues
```bash
# Fix specific file
npx eslint resources/js/app.js --fix

# Check configuration
npx eslint --print-config resources/js/app.js
```

### Prettier Issues
```bash
# Format specific file
npx prettier --write resources/js/app.js

# Check formatting
npx prettier --check resources/js/app.js
```

## 📚 Resources

- [Conventional Commits](https://www.conventionalcommits.org/)
- [Laravel Pint Documentation](https://laravel.com/docs/pint)
- [ESLint Documentation](https://eslint.org/)
- [Prettier Documentation](https://prettier.io/)
- [Husky Documentation](https://typicode.github.io/husky/)

## 🤝 Contributing

1. Write meaningful commit messages
2. Ensure all hooks pass
3. Create detailed pull requests
4. Review and test thoroughly

---

**Happy Coding! 🎉**