Skip to content

DEBUG_LIBRARY_SETUP_GUIDE.md

Latest commit

 

History

History
294 lines (214 loc) · 7.74 KB

DEBUG_LIBRARY_SETUP_GUIDE.md

File metadata and controls

294 lines (214 loc) · 7.74 KB

Debug Library Independent Repository Setup Guide

This guide explains how to extract your debug library into an independent repository that can be managed separately but works seamlessly with your main project using git submodules.

🎯 Benefits of Independent Debug Library

  1. Reusability: Use the debug library across multiple projects
  2. Version Control: Independent versioning and releases
  3. Team Collaboration: Separate team can maintain debug tools
  4. Clean Architecture: Keep main project focused on business logic
  5. Easy Updates: Pull latest debug features without affecting main codebase

🚀 Quick Setup

Step 1: Run the Setup Script

# Make sure you're in your main project directory
./setup-debug-library.sh

Important: Before running, update the GitHub username in the script:

# Edit the script and change this line:
GITHUB_USERNAME="your-actual-github-username"

Step 2: Create GitHub Repository

  1. Go to GitHub and create a new repository named agritech-debug-tracker
  2. Don't initialize with README (the script creates one)
  3. Copy the repository URL

Step 3: Connect to GitHub

# Navigate to the debug library directory
cd ../agritech-debug-tracker

# Add GitHub remote
git remote add origin https://github.com/YOUR-USERNAME/agritech-debug-tracker.git

# Push to GitHub
git push -u origin main

Step 4: Update Submodule URL

# Go back to main project
cd /path/to/AgriTechBlog

# Update submodule to use GitHub URL
git submodule set-url lib/debug-tracker https://github.com/YOUR-USERNAME/agritech-debug-tracker.git

📦 Using the Debug Library

In Your Main Project

After setup, update your imports from:

// Old imports
import DebugTracker from './lib/debug-tracker';
import DebugFlowVisualizer from './components/debug-flow-visualizer';

To:

// New imports using the independent library
import { 
  DebugTracker, 
  DebugFlowVisualizer,
  initializeDebugSystem 
} from '@agritech/debug-tracker';

Initialize Debug System

// In your main App.tsx or main.tsx
import { initializeDebugSystem } from '@agritech/debug-tracker';

// Initialize once at app startup
if (process.env.NODE_ENV === 'development') {
  const debugTracker = initializeDebugSystem();
}

Add Debug Visualizer

import { DebugFlowVisualizer } from '@agritech/debug-tracker';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();
  const isAdminPage = ['/admin', '/create-post', '/edit-post'].some(path => 
    location.pathname.includes(path)
  );
  
  return (
    <div>
      {/* Your app content */}
      
      {/* Debug visualizer - only on admin pages in development */}
      {process.env.NODE_ENV === 'development' && isAdminPage && (
        <DebugFlowVisualizer />
      )}
    </div>
  );
}

🔄 Managing Updates

Updating the Debug Library

When you want to add features to the debug library:

# 1. Go to debug library directory
cd lib/debug-tracker

# 2. Make your changes
# Edit files in src/

# 3. Build the library
npm run build

# 4. Commit and push changes
git add .
git commit -m "feat: add new debugging feature"
git push origin main

# 5. Update version in package.json if needed
npm version patch  # or minor/major
git push --tags

Pulling Updates in Main Project

When the debug library has updates:

# 1. Update the submodule
git submodule update --remote lib/debug-tracker

# 2. Reinstall the local dependency
npm install ./lib/debug-tracker

# 3. Commit the submodule update
git add lib/debug-tracker
git commit -m "chore: update debug library to latest version"

🏗️ Development Workflow

Working on Debug Library Features

# Clone both repositories for development
git clone https://github.com/YOUR-USERNAME/AgriTechBlog.git
git clone https://github.com/YOUR-USERNAME/agritech-debug-tracker.git

# Link them for development
cd AgriTechBlog
npm link ../agritech-debug-tracker

# Now changes in debug library are immediately available

Testing Debug Library Changes

# In debug library directory
npm run dev  # Watch mode

# In main project directory (separate terminal)
npm run dev  # Your main app with live debug library updates

📝 Smart Deployment with Enhanced Commit Messages

The enhanced deployment script now generates intelligent commit messages based on your changes:

Examples of Generated Commit Messages

  • feat(api): enhance API endpoints and server functionality - production ready
  • fix: resolve application issues and bugs - staging deployment
  • refactor(ui): improve user interface and components across multiple modules
  • chore(config): update project configuration
  • docs: update documentation

Using Custom Commit Messages

# Use generated smart commit message
npm run deploy

# Use custom commit message
npm run deploy production "feat: implement advanced search functionality"

Commit Message Analysis

The script analyzes:

  • File types: Frontend, backend, config, documentation
  • Change patterns: New features, bug fixes, UI changes, API updates
  • Scale of changes: Number of files, insertions, deletions
  • Deployment context: Production vs staging vs preview

🛠️ Advanced Configuration

Custom Debug Library Location

If you want to place the debug library elsewhere:

# Edit setup-debug-library.sh
DEBUG_LIB_DIR="/custom/path/agritech-debug-tracker"

Multiple Projects Using Same Debug Library

# In another project
git submodule add https://github.com/YOUR-USERNAME/agritech-debug-tracker.git lib/debug-tracker
npm install ./lib/debug-tracker

Publishing to NPM (Optional)

# In debug library directory
npm login
npm publish

# Then use in any project
npm install @agritech/debug-tracker

🚨 Troubleshooting

Submodule Issues

# Reset submodule
git submodule deinit lib/debug-tracker
git rm lib/debug-tracker
git submodule add https://github.com/YOUR-USERNAME/agritech-debug-tracker.git lib/debug-tracker

# Clone with submodules
git clone --recursive https://github.com/YOUR-USERNAME/AgriTechBlog.git

Import Issues

If imports fail after setup:

  1. Ensure the debug library is built: cd lib/debug-tracker && npm run build
  2. Reinstall: npm install ./lib/debug-tracker
  3. Check import paths match the exported names

Build Issues

# In debug library directory
rm -rf node_modules dist
npm install
npm run build

📋 Deployment Checklist

  • Enhanced deployment script installed
  • Debug library extracted to independent repository
  • GitHub repository created and connected
  • Submodule configured in main project
  • Imports updated in main project
  • Debug system initialization added
  • Debug visualizer restricted to admin pages
  • Both repositories tested and working
  • Team members have access to debug library repository

🎉 Benefits Achieved

✅ Professional Commit Messages: Automatic intelligent commit message generation
✅ Independent Debug Library: Reusable across projects
✅ Clean Architecture: Separation of concerns
✅ Easy Updates: Pull debug improvements independently
✅ Team Collaboration: Dedicated repository for debug tools
✅ Version Control: Independent versioning for debug features

Your debug library is now a professional, independent tool that can evolve separately from your main project while integrating seamlessly!