Krow-workspace/docs/03-contributing.md

Contributing to KROW Workforce Platform

Welcome to the KROW Workforce development team! This guide will help you get set up and understand our development practices.

---

🚀 Getting Started & Setup Checklist

Follow these steps to set up your development environment and gain access to all necessary resources.

1. Access Google Chat Space:

   • Ensure you have been invited to and joined our main Google Chat space for daily communication and quick questions.

2. GitHub Access & SSH Key:

   • Confirm you have read/write access to this GitHub repository.
   • Configure your SSH key for GitHub. Ensure your commits are verified (GPG signing is recommended).

3. Install & Configure Gemini CLI:

   • Install the Gemini CLI on your local machine.
   • Familiarize yourself with its usage for code assistance and documentation.

4. Install & Configure Enpass:

   • Install Enpass (our team's shared password manager).
   • Ensure you have access to the shared KROW vault for all project credentials (API keys, service accounts, etc.).

5. Install Required Development Tools:

   Before running the project, ensure you have the following installed:

   • Node.js (v20+): We recommend using nvm (Node Version Manager) to install and manage Node versions.
   • pnpm: Our preferred package manager for JavaScript projects. (npm install -g pnpm)
   • Flutter Version Management (FVM): We use FVM to manage Flutter SDK versions per project. Install it via Homebrew (brew install fvm) or Dart (dart pub global activate fvm).
   • Firebase CLI: Required for emulation and deployment. (npm install -g firebase-tools)
   • Google Cloud CLI (gcloud): Required for backend authentication and resource management.

   Recommended IDE:

   • Google Project IDX (Antigravity) or VS Code.
   • Essential Extensions:
     • Flutter & Dart
     • Firebase
     • Tailwind CSS IntelliSense
     • ESLint & Prettier

   Diagramming:

   • Use MermaidChart.com for creating and editing diagrams (Mermaid syntax).

6. Local Development Environment Setup:

   • Clone the monorepo: git clone git@github.com:Oloodi/krow-workforce.git
   • Navigate to the project root: cd krow-workforce
   • Install web frontend dependencies: make install

• Install Git Hooks:
  • Run make install-git-hooks to set up local safeguards that prevent direct pushes to protected branches (main and dev). This is a mandatory step.

7. Firebase Project Access Validation:

   • Confirm you have access to the dev Firebase/GCP project.
   • Verify you can run firebase login and gcloud auth login successfully.

8. Understand the Monorepo Structure:

   • Familiarize yourself with the project layout (apps/, backend/, internal/) as described in the main README.md.

---

💡 Development Guidelines

1. Branching Strategy:

   • We adopt a feature branch workflow. All code modifications must be done on a new branch.
   • The main and dev branches are protected.

2. Commit Messages:

   • Use clear and descriptive commit messages (standardized via Open Commit if available).

3. Code Standards:

   • Adhere to existing code style, formatting, and architectural patterns found in the codebase.
   • Run linters and formatters before committing.

4. Documentation:

   • Keep documentation up to date in the docs/ directory.

5. Diagrams:

   • All diagrams should be created using Mermaid syntax and stored in Markdown files.

---

🔗 Useful Links

• KROW Internal Launchpad: https://launchpad.krowwithus.com
• Project Onboarding (Start Here): docs/05-project-onboarding-master.md - Comprehensive guide covering architecture, domain logic, feature gap analysis, and development strategy
• Project Vision: docs/00-vision.md
• Backend Specification (Legacy Reference): docs/01-backend-api-specification.md - Historical API spec from Digital Ocean stack
• Codemagic Env Vars: docs/02-codemagic-env-vars.md