# 🧰 Best Practices Guide

[![Status](https://img.shields.io/badge/Status-Complete-brightgreen?style=for-the-badge)](.) [![Updated](https://img.shields.io/badge/Updated-2024-blue?style=for-the-badge)](.)

> **Quick intro**: Your complete guide to development best practices, from code style to PR reviews

## 🗺️ Quick Navigation

- [Overview](#overview)
- [Code Style & Linting](#-code-style--linting)
- [Commit Conventions](#-commit-conventions)
- [Branch Naming](#-branch-naming)
- [PR Review Process](#-pr-review-process)
- [Merge Strategies](#-merge-strategies)
- [Quick Reference](#-quick-reference)
- [Related Pages](#-related-pages)

---

## Overview

This guide covers the essential development practices that keep our codebase clean, consistent, and maintainable. These practices are enforced through automated tools and workflows to ensure quality and consistency across all contributions.

<details>
<summary><b>🎯 Why These Practices Matter</b></summary>

- **Consistency**: Uniform code style across the entire project
- **Quality**: Automated checks catch issues before they reach production
- **Collaboration**: Clear conventions make code review and collaboration easier
- **Maintainability**: Well-structured commits and branches make debugging and releases smoother

</details>

---

## 🎨 Code Style & Linting

We use [Biome](https://biomejs.dev/) for code formatting, linting, and import sorting to maintain consistent code style.

### Configuration

<details>
<summary><b>📋 Biome Setup (Click to expand)</b></summary>

Our project uses the **"ultracite"** preset configuration:

```json
{
  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
  "extends": ["ultracite"],
  "javascript": {
    "globals": ["Liveblocks"]
  }
}
```

**Key Features:**
- 🎨 **Formatting**: Consistent indentation, spacing, and structure
- 🔍 **Linting**: Catch potential issues and enforce best practices  
- 📦 **Import Sorting**: Automatically organize imports
- ⚡ **Performance**: Fast execution with native speed

</details>

### Quick Commands

```bash
# Format all files
pnpm format

# Check for linting issues
pnpm lint

# Check specific file
pnpm biome check src/components/Button.tsx
```

### Best Practices

<table>
<tr>
<td width="50%">

#### ✅ **DO**
- Run `pnpm lint` before committing
- Use consistent naming conventions
- Add TypeScript types for all functions
- Use meaningful variable names
- Keep functions small and focused

</td>
<td width="50%">

#### ❌ **DON'T**
- Ignore linting errors
- Use `any` type without justification
- Create overly complex functions
- Use magic numbers without constants
- Skip type annotations

</td>
</tr>
</table>

---

## 📝 Commit Conventions

We follow [Conventional Commits](https://conventionalcommits.org/) specification for clear, semantic commit messages.

> **Note**: Conventional commit format is enforced for PR titles through automated validation. Individual commit messages are encouraged to follow this format but are not automatically enforced.

### Commit Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Commit Types

<details open>
<summary><b>🏷️ Standard Types</b></summary>

| Type | Description | Example |
|:-----|:------------|:--------|
| `feat` | New feature | `feat(auth): add OAuth login support` |
| `fix` | Bug fix | `fix(api): resolve user validation error` |
| `docs` | Documentation | `docs(readme): update installation guide` |
| `style` | Code style/formatting | `style(components): apply biome formatting` |
| `refactor` | Code refactoring | `refactor(utils): simplify date formatting` |
| `test` | Tests | `test(auth): add login integration tests` |
| `chore` | Maintenance | `chore(deps): update dependencies` |
| `ci` | CI/CD changes | `ci(actions): add security workflow` |
| `perf` | Performance | `perf(queries): optimize database calls` |
| `build` | Build system | `build(webpack): update configuration` |

</details>

### Examples

<details>
<summary><b>💡 Good Commit Examples</b></summary>

```bash
# Feature with scope
feat(dashboard): add user analytics charts

# Breaking change
feat(api)!: change response format for /users endpoint

BREAKING CHANGE: The /users endpoint now returns an object instead of array

# Bug fix with issue reference
fix(auth): resolve token expiration handling

Closes #123

# Multiple changes
feat(ui): add dark mode toggle

- Add toggle component to settings page
- Implement theme context
- Update all components for theme support
```

</details>

### Commit Best Practices

- **Be descriptive**: Explain what and why, not just what
- **Use imperative mood**: "add feature" not "added feature"
- **Reference issues**: Use `Closes #123` or `Fixes #123`
- **Keep first line under 72 characters**
- **Add body for complex changes**

---

## 🌿 Branch Naming

All branches must follow our enforced naming conventions for automated processing.

### Naming Patterns

<details open>
<summary><b>📐 Required Patterns</b></summary>

| Pattern | Purpose | Examples |
|---------|---------|----------|
| `feat/*` | New features | `feat/user-dashboard`, `feat/oauth-integration` |
| `fix/*` | Bug fixes | `fix/login-validation`, `fix/memory-leak` |
| `hotfix/*` | Production fixes | `hotfix/security-patch`, `hotfix/critical-bug` |
| `release/v*.*.*` | Release preparation | `release/v1.2.0`, `release/v2.0.0-beta` |
| `docs/*` | Documentation | `docs/api-guide`, `docs/contributing` |
| `test/*` | Testing | `test/e2e-suite`, `test/unit-coverage` |
| `refactor/*` | Code refactoring | `refactor/auth-module`, `refactor/api-structure` |
| `chore/*` | Maintenance | `chore/deps-update`, `chore/cleanup` |

</details>

### Branch Lifecycle

```mermaid
flowchart LR
    A[Create Branch] --> B[Develop]
    B --> C[Create PR]
    C --> D[Code Review]
    D --> E[Merge]
    E --> F[Delete Branch]
    
    classDef feature fill:#4ECDC4,stroke:#333,stroke-width:2px
    classDef process fill:#95E1D3,stroke:#333,stroke-width:2px
    
    class A,B feature
    class C,D,E,F process
```

### Branch Best Practices

- **Keep branches focused**: One feature or fix per branch
- **Use descriptive names**: `feat/user-authentication` vs `feat/auth`
- **Keep branches short-lived**: Merge within 1-2 weeks
- **Delete after merge**: Clean up merged branches
- **Sync regularly**: Rebase with base branch frequently

---

## 👥 PR Review Process

Our review process ensures code quality and knowledge sharing across the team.

### PR Requirements

<details open>
<summary><b>📋 PR Checklist</b></summary>

Before creating a PR, ensure:

- [ ] **Branch naming** follows conventions
- [ ] **Commit messages** use conventional format
- [ ] **Code** passes all linting and type checks
- [ ] **Tests** are written and passing
- [ ] **Documentation** is updated if needed
- [ ] **PR size** is reasonable (< 1000 lines soft limit)
- [ ] **Description** clearly explains changes

</details>

### Review Guidelines

<table>
<tr>
<td width="50%">

#### 🔍 **As a Reviewer**
- Review within 24-48 hours
- Focus on logic, not just style
- Ask questions for clarification  
- Suggest improvements constructively
- Approve when ready for merge

</td>
<td width="50%">

#### 👤 **As an Author**
- Respond to feedback promptly
- Explain complex decisions
- Make requested changes
- Keep PR updated with base branch
- Resolve conversations when addressed

</td>
</tr>
</table>

### Protection Rules

Different branches have different review requirements:

| Branch | Required Reviews | Additional Requirements |
|:------:|:---------------:|:----------------------|
| **develop** | 1 | CI must pass, up-to-date |
| **staging** | 1 | CI must pass, up-to-date |
| **main** | 2 | CI must pass, up-to-date, semantic title |

---

## 🔄 Merge Strategies

We use different merge strategies depending on the situation and branch type.

### Strategy Guide

<details open>
<summary><b>📊 When to Use Each Strategy</b></summary>

| Strategy | When to Use | Benefits | Drawbacks |
|:---------|:------------|:---------|:----------|
| **Squash and Merge** | Feature branches to develop | Clean history, single commit | Loses detailed commit history |
| **Merge Commit** | Release branches | Preserves branch history | Creates merge commits |
| **Rebase and Merge** | Small, clean branches | Linear history | Can be complex for large changes |

</details>

### Default Strategies

```mermaid
flowchart TD
    A[PR Ready] --> B{Branch Type?}
    
    B -->|Feature Branch| C[Squash and Merge]
    B -->|Release Branch| D[Merge Commit]
    B -->|Hotfix Branch| E[Merge Commit]
    
    C --> F[Clean Single Commit]
    D --> G[Preserve Branch History]
    E --> G
    
    classDef feature fill:#4ECDC4,stroke:#333,stroke-width:2px
    classDef release fill:#95E1D3,stroke:#333,stroke-width:2px
    classDef hotfix fill:#F38181,stroke:#333,stroke-width:2px
    
    class C,F feature
    class D,G release
    class E hotfix
```

### Merge Best Practices

- **Squash feature branches**: Keep develop history clean
- **Preserve release history**: Use merge commits for releases
- **Update merge message**: Make it descriptive and conventional
- **Delete merged branches**: Clean up after successful merge
- **Sync downstream**: Ensure all branches stay updated

---

## ⚡ Quick Reference

<div align="center">

### 🚀 Common Commands

</div>

<details>
<summary><b>📝 Commit & Branch Commands</b></summary>

```bash
# Create and switch to new feature branch
git checkout -b feat/awesome-feature develop

# Make conventional commit
git commit -m "feat(component): add user avatar display"

# Push and set upstream
git push -u origin feat/awesome-feature

# Update branch with latest develop
git fetch origin
git rebase origin/develop

# Interactive rebase to clean up commits
git rebase -i HEAD~3
```

</details>

<details>
<summary><b>🔍 Code Quality Commands</b></summary>

```bash
# Run full quality check
pnpm lint && pnpm typecheck && pnpm test

# Format code
pnpm format

# Fix linting issues
pnpm lint:fix

# Check specific file
pnpm biome check src/components/Button.tsx

# Run all tests
pnpm test
```

</details>

### 📊 Quality Metrics

| Metric | Target | Current | Status |
|:-------|:------:|:-------:|:------:|
| **Test Coverage** | >80% | 85% | ✅ |
| **Type Coverage** | >95% | 98% | ✅ |
| **Lint Score** | 0 errors | 0 | ✅ |
| **Build Time** | <2 min | 1.5 min | ✅ |

---

## 📚 Related Pages

<div align="center">

**📖 For more detailed information, see these related wiki pages:**

</div>

<table>
<tr>
<td>

### 🌳 Git Workflow
- [Branch Overview](02-Branch-Overview.md)
- [Branch Types](03-Branch-Types.md)
- [Workflow Diagram](04-Workflow-Diagram.md)
- [Branch Protection Rules](05-Branch-Protection-Rules.md)

</td>
<td>

### 🤖 Automation
- [Pipeline Overview](06-Pipeline-Overview.md)
- [Workflow Triggers](07-Workflow-Triggers-Matrix.md)
- [Automation Features](12-Automation-Features.md)
- [Workflow Architecture](13-Workflow-Architecture.md)

</td>
<td>

### 🔒 Security & Quality
- [Security Framework](09-Security-Framework.md)
- [Dependency Management](08-Automated-Dependency-Management.md)
- [Workflow Details](11-Workflow-Details.md)

</td>
</tr>
</table>

---

<div align="center">

### 💡 **Pro Tip**

> Use the GitHub CLI for faster workflow: `gh pr create --title "feat: add feature" --body "Description"`

**[⬆ Back to Top](#-quick-navigation)**

</div>