GitHub Workflow & Code Refactoring

This manual defines the collaborative standards for version control, code submission, and technical debt management within the PlugZero ecosystem.

🏗️ 1. Repository Structure & Git Management

PlugZero uses a decoupled repository architecture. You must manage two distinct codebases simultaneously.

The Decoupled Repositories

1. Backend (plugzero_api): Django REST Framework + Celery + Scikit-Learn.
   • Remote: https://github.com/plugzero/plugzero-api.git
2. Frontend (plugzero-analytics): Next.js 16 + Tailwind CSS.
   • Remote: https://github.com/plugzero/plugzero-analytics.git

Standardizing Remotes

Ensure your local origin points to the organization repo, not a personal fork, to ensure CI/CD synchronization:

git remote set-url origin git@github.com:plugzero/plugzero-analytics.git

🔄 2. The Contribution Cycle (SOP)

A. The Pull Protocol

Before starting any new feature or refactor, always sync your local environment with the latest production state:

git checkout main
git pull origin main --rebase

B. Branching Strategy

• main: Production-ready code. Never commit directly to main.
• feat/[name]: New features or logic additions.
• fix/[issue]: Bug fixes.
• refactor/[target]: Improving code structure without changing outward behavior.

C. Commit Standards (Semantic Commits)

• feat: Adding a new analysis engine or UI component.
• fix: Resolving an API crash or CSS misalignment.
• docs: Updating manuals (like these).
• refactor: Optimizing existing data models or cleaning up tech debt.

🛠️ 3. Code Refactoring & Tech Debt

Transitioning from Mocks to Production

Many early-stage services may contain stubbed logic (pass statements or mock return values).

Refactoring Checklist:

1. Verification: Locate any MOCK_API_KEY or hardcoded response logic (e.g., in ai_engine.py).
2. Implementation: Replace mocks with production-ready services using environment variables.
3. Stability: Ensure refactored code maintains backward compatibility with saved AnalysisResult JSON objects in the database.

Linting Compliance

Refactored code MUST pass the following automated checks:

• Frontend: npm run lint (ESLint 9 compliance).
• Backend: Standard PEP8 styles.

🚦 4. Pull Request (PR) Pre-flight Checklist

Before pushing code for review, verify:

• Cross-Stack Check: If you changed a backend model, did you update the frontend zod schema or API call?
• Dependency Check: Are all new packages listed in package.json or requirements.txt?
• Data Integrity: Will your change require a database migration? Is the migration file included?
• Manual Sync: Check if your change invalidates any logic in the other technical manuals.