docs(git-hooks): add conditional Husky activation system documentation

- Documents the conditional Husky activation system for git hooks - Explains how hooks are committed but not automatically activated - Provides user workflows for enabling/disabling hooks - Includes troubleshooting guide and best practices - Covers three activation methods: environment variable, local file, global config - Supports team standards without forcing compliance System: Git hooks with optional activation Location: doc/husky-conditional-activation.md
15 hours ago · 4829582584
1 changed files with 381 additions and 0 deletions
--- a/doc/husky-conditional-activation.md
+++ b/doc/husky-conditional-activation.md
@ -0,0 +1,381 @@
+# Husky Conditional Activation System
+
+**Author**: Matthew Raymer
+**Date**: 2025-08-21T09:40Z
+**Status**: 🎯 **ACTIVE** - Git hooks with optional activation
+
+## Overview
+
+This document describes the **conditional Husky activation system** implemented
+in the TimeSafari project. The system provides standardized git hooks that are
+committed to version control but only activate when explicitly enabled by
+individual developers.
+
+## Problem Statement
+
+Traditional Husky implementations face several challenges:
+
+1. **Automatic activation** on all systems can be disruptive
+2. **Different environments** may have different requirements
+3. **Team preferences** vary regarding git hook enforcement
+4. **CI/CD systems** may not need or want git hooks
+5. **New developers** may be surprised by unexpected hook behavior
+
+## Solution: Conditional Activation
+
+The conditional activation system solves these problems by:
+
+- **Committing hooks to git** for consistency and version control
+- **Making hooks optional** by default
+- **Providing multiple activation methods** for flexibility
+- **Ensuring hooks exit gracefully** when disabled
+- **Maintaining team standards** without forcing compliance
+
+## System Architecture
+
+### **Core Components**
+
+```
+.husky/
+├── _/husky.sh              # Conditional activation logic
+├── pre-commit              # Pre-commit hook (linting)
+├── commit-msg              # Commit message validation
+└── README.md               # User activation instructions
+```
+
+### **Activation Methods**
+
+#### **Method 1: Environment Variable (Session Only)**
+
+```bash
+export HUSKY_ENABLED=1
+```
+
+- **Scope**: Current terminal session only
+- **Use case**: Temporary activation for testing
+- **Reset**: `unset HUSKY_ENABLED`
+
+#### **Method 2: Local File (Persistent)**
+
+```bash
+touch .husky-enabled
+```
+
+- **Scope**: Current repository, persistent
+- **Use case**: Long-term activation for development
+- **Reset**: `rm .husky-enabled`
+
+#### **Method 3: Global Git Configuration**
+
+```bash
+git config --global husky.enabled true
+```
+
+- **Scope**: All repositories for current user
+- **Use case**: Developer preference across projects
+- **Reset**: `git config --global --unset husky.enabled`
+
+## Implementation Details
+
+### **Conditional Activation Logic**
+
+The core logic in `.husky/_/husky.sh`:
+
+```bash
+# Check if Husky is enabled for this user
+if [ "$HUSKY_ENABLED" != "1" ] && [ ! -f .husky-enabled ]; then
+  echo "Husky is not enabled. To enable:"
+  echo "  export HUSKY_ENABLED=1"
+  echo "  or create .husky-enabled file"
+  exit 0  # Graceful exit, not an error
+fi
+```
+
+### **Hook Behavior**
+
+When **disabled**:
+
+- Hooks display helpful activation instructions
+- Exit with code 0 (success, not error)
+- No git operations are blocked
+- No performance impact
+
+When **enabled**:
+
+- Hooks run normally with full functionality
+- Standard Husky behavior applies
+- Git operations may be blocked if hooks fail
+
+## Available Hooks
+
+### **Pre-commit Hook**
+
+**File**: `.husky/pre-commit`
+**Purpose**: Code quality enforcement before commits
+**Action**: Runs `npm run lint-fix`
+**When**: Before each commit
+**Failure**: Prevents commit if linting fails
+
+**Activation Check**:
+
+```bash
+if [ "$HUSKY_ENABLED" = "1" ] || [ -f .husky-enabled ]; then
+  echo "Running pre-commit hooks..."
+  npm run lint-fix
+else
+  echo "Husky pre-commit hook skipped (not enabled)"
+  exit 0
+fi
+```
+
+### **Commit-msg Hook**
+
+**File**: `.husky/commit-msg`
+**Purpose**: Commit message format validation
+**Action**: Runs `npx commitlint --edit "$1"`
+**When**: After commit message is written
+**Failure**: Prevents commit if message format is invalid
+
+**Activation Check**:
+
+```bash
+if [ "$HUSKY_ENABLED" = "1" ] || [ -f .husky-enabled ]; then
+  echo "Running commit-msg hooks..."
+  npx commitlint --edit "$1"
+else
+  echo "Husky commit-msg hook skipped (not enabled)"
+  exit 0
+fi
+```
+
+## User Workflows
+
+### **New Developer Setup**
+
+1. **Clone repository**
+
+   ```bash
+   git clone <repository-url>
+   cd <repository-name>
+   ```
+
+2. **Hooks are present but inactive**
+   - Pre-commit and commit-msg hooks exist
+   - No automatic activation
+   - Git operations work normally
+
+3. **Optional: Enable hooks**
+
+   ```bash
+   # For current session only
+   export HUSKY_ENABLED=1
+
+   # For persistent activation
+   touch .husky-enabled
+   ```
+
+### **Daily Development**
+
+#### **With Hooks Disabled**
+
+```bash
+git add .
+git commit -m "feat: add new feature"
+# Hooks are skipped, commit proceeds normally
+```
+
+#### **With Hooks Enabled**
+
+```bash
+git add .
+git commit -m "feat: add new feature"
+# Pre-commit hook runs linting
+# Commit-msg hook validates message format
+# Commit only proceeds if all hooks pass
+```
+
+### **Troubleshooting**
+
+#### **Hooks Not Running**
+
+```bash
+# Check if hooks are enabled
+echo $HUSKY_ENABLED
+ls -la .husky-enabled
+
+# Enable hooks
+export HUSKY_ENABLED=1
+# or
+touch .husky-enabled
+```
+
+#### **Hooks Running Unexpectedly**
+
+```bash
+# Disable hooks
+unset HUSKY_ENABLED
+rm -f .husky-enabled
+
+# Check global configuration
+git config --global --get husky.enabled
+```
+
+## Configuration Files
+
+### **`.gitignore` Entry**
+
+```gitignore
+# Husky activation file (user-specific)
+.husky-enabled
+```
+
+This ensures that:
+
+- Hooks are committed to git (team standard)
+- Activation files are not committed (user preference)
+- Each developer can control their own activation
+
+### **Package.json Dependencies**
+
+```json
+{
+  "devDependencies": {
+    "husky": "^9.0.11",
+    "@commitlint/cli": "^18.6.1",
+    "@commitlint/config-conventional": "^18.6.2"
+  }
+}
+```
+
+## Benefits
+
+### **For Development Teams**
+
+1. **Consistency**: All developers have the same hook configuration
+2. **Flexibility**: Individual developers can choose activation
+3. **Standards**: Team coding standards are enforced when enabled
+4. **Version Control**: Hook configuration is tracked and versioned
+5. **Onboarding**: New developers get standardized setup
+
+### **For Individual Developers**
+
+1. **Choice**: Control over when hooks are active
+2. **Performance**: No unnecessary hook execution when disabled
+3. **Learning**: Gradual adoption of git hook practices
+4. **Debugging**: Easy to disable hooks for troubleshooting
+5. **Environment**: Works across different development environments
+
+### **For CI/CD Systems**
+
+1. **No Interference**: Hooks don't run in automated environments
+2. **Consistency**: Same hook logic available if needed
+3. **Flexibility**: Can enable hooks in specific CI scenarios
+4. **Reliability**: No unexpected hook failures in automation
+
+## Best Practices
+
+### **Team Adoption**
+
+1. **Start with disabled hooks** for new team members
+2. **Encourage gradual adoption** of hook activation
+3. **Document hook benefits** and usage patterns
+4. **Provide training** on hook configuration
+5. **Support troubleshooting** when hooks cause issues
+
+### **Hook Development**
+
+1. **Keep hooks lightweight** and fast
+2. **Provide clear error messages** when hooks fail
+3. **Include helpful activation instructions** in disabled state
+4. **Test hooks in both enabled and disabled states**
+5. **Document hook requirements** and dependencies
+
+### **Configuration Management**
+
+1. **Commit hook files** to version control
+2. **Ignore activation files** in .gitignore
+3. **Document activation methods** clearly
+4. **Provide examples** for common use cases
+5. **Maintain backward compatibility** when updating hooks
+
+## Troubleshooting Guide
+
+### **Common Issues**
+
+#### **Hooks Running When Not Expected**
+
+```bash
+# Check all activation methods
+echo "Environment variable: $HUSKY_ENABLED"
+echo "Local file exists: $([ -f .husky-enabled ] && echo "yes" || echo "no")"
+echo "Global config: $(git config --global --get husky.enabled)"
+```
+
+#### **Hooks Not Running When Expected**
+
+```bash
+# Verify hook files exist and are executable
+ls -la .husky/
+chmod +x .husky/pre-commit
+chmod +x .husky/commit-msg
+```
+
+#### **Permission Denied Errors**
+
+```bash
+# Fix file permissions
+chmod +x .husky/_/husky.sh
+chmod +x .husky/pre-commit
+chmod +x .husky/commit-msg
+```
+
+### **Debug Mode**
+
+Enable debug output to troubleshoot hook issues:
+
+```bash
+export HUSKY_DEBUG=1
+export HUSKY_ENABLED=1
+git commit -m "test: debug commit"
+```
+
+## Future Enhancements
+
+### **Planned Improvements**
+
+1. **Hook Configuration File**: YAML/JSON configuration for hook behavior
+2. **Selective Hook Activation**: Enable/disable specific hooks individually
+3. **Hook Performance Metrics**: Track execution time and success rates
+4. **Integration with IDEs**: IDE-specific activation methods
+5. **Remote Configuration**: Team-wide hook settings via configuration
+
+### **Extension Points**
+
+1. **Custom Hook Scripts**: Easy addition of project-specific hooks
+2. **Hook Templates**: Reusable hook patterns for common tasks
+3. **Conditional Logic**: Complex activation rules based on context
+4. **Notification System**: Hook status reporting and alerts
+5. **Analytics**: Hook usage and effectiveness tracking
+
+## Conclusion
+
+The conditional Husky activation system provides an elegant solution to the
+challenges  of git hook management in team environments. By committing
+standardized hooks while making activation optional, it balances consistency
+with flexibility, enabling teams to maintain coding standards without forcing compliance.
+
+This approach supports gradual adoption, respects individual preferences, and
+provides a solid foundation for git hook practices that can evolve with team needs
+and project requirements.
+
+---
+
+**Related Documents**:
+
+- [Git Hooks Best Practices](./git-hooks-best-practices.md)
+- [Code Quality Standards](./code-quality-standards.md)
+- [Development Workflow](./development-workflow.md)
+
+**Maintainer**: Development Team
+**Review Schedule**: Quarterly
+**Next Review**: 2025-11-21