@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/docs/team-standards/cross-platform-team-guide.md

@@ -0,0 +1,736 @@
+# Cross-Platform Team Development Standards
+
+## Overview
+
+This guide establishes standards and best practices for mixed Windows/Mac development teams working
+on Dynamics 365 projects. It ensures consistent workflows, compatible tooling, and seamless
+collaboration across different platforms.
+
+## Table of Contents
+
+1. [Team Composition Guidelines](#team-composition-guidelines)
+2. [Platform-Agnostic Standards](#platform-agnostic-standards)
+3. [Development Environment Setup](#development-environment-setup)
+4. [Git and Version Control](#git-and-version-control)
+5. [Code Standards and Reviews](#code-standards-and-reviews)
+6. [Communication and Collaboration](#communication-and-collaboration)
+7. [CI/CD and Deployment](#cicd-and-deployment)
+8. [Troubleshooting Cross-Platform Issues](#troubleshooting-cross-platform-issues)
+9. [Team Onboarding Process](#team-onboarding-process)
+10. [Best Practices and Guidelines](#best-practices-and-guidelines)
+
+## Team Composition Guidelines
+
+### 🎯 Recommended Team Structure
+
+For optimal cross-platform collaboration, we recommend:
+
+- **Mixed Platform Distribution**: 60/40 or 70/30 split (not 100% single platform)
+- **Platform Champions**: At least one expert per platform who can help others
+- **Shared Responsibilities**: All team members should understand both platforms
+- **Documentation Leaders**: Dedicated maintainers for platform-specific docs
+
+### 👥 Role-Platform Mapping
+
+| Role                   | Windows Preference      | Mac Preference        | Platform Agnostic        |
+| ---------------------- | ----------------------- | --------------------- | ------------------------ |
+| **DevOps Engineer**    | ✅ PowerShell expertise | ⭐ Bash/Docker skills | ✅ Both valuable         |
+| **Backend Developer**  | ✅ .NET/Azure focus     | ⭐ Node.js/Linux      | ✅ JavaScript/TypeScript |
+| **Frontend Developer** | ⭐ VS Code/Chrome       | ✅ Design tools       | ✅ React/Web standards   |
+| **QA Engineer**        | ✅ Windows testing      | ⭐ Mobile testing     | ✅ Web testing           |
+| **Technical Lead**     | ✅ Enterprise systems   | ⭐ Open source        | ✅ Architecture focus    |
+
+## Platform-Agnostic Standards
+
+### 🔧 Core Technology Stack
+
+All team members use the same core technologies:
+
+```json
+{
+  "runtime": "Node.js 18+",
+  "language": "TypeScript 5+",
+  "framework": "React 18+",
+  "styling": "Fluent UI v8",
+  "testing": "Jest + Testing Library",
+  "linting": "ESLint + Prettier",
+  "bundling": "Webpack 5+",
+  "version_control": "Git 2.40+"
+}
+```
+
+### 📁 Project Structure Standards
+
+```
+project-root/
+├── src/                     # Cross-platform source code
+├── config/                  # Shared JSON configurations
+├── deployment/
+│   ├── scripts/
+│   │   ├── *.sh            # Bash scripts (Mac/Linux)
+│   │   └── *.ps1           # PowerShell scripts (Windows)
+│   ├── QUICKSTART-MAC.md   # Mac-specific setup
+│   └── QUICKSTART-WINDOWS.md # Windows-specific setup
+├── docs/                   # Platform-agnostic documentation
+└── .vscode/               # Shared VS Code configuration
+```
+
+### 🔐 Configuration Management
+
+#### Shared Configuration Files
+
+All configuration uses JSON format (cross-platform compatible):
+
+```json
+// config/environments/dev.json
+{
+  "name": "Development",
+  "dynamics365": {
+    "orgUrl": "https://dev.crm.dynamics.com",
+    "webApiUrl": "https://dev.api.crm.dynamics.com/api/data/v9.2"
+  },
+  "authentication": {
+    "clientId": "${D365_CLIENT_ID}",
+    "clientSecret": "${D365_CLIENT_SECRET}"
+  }
+}
+```
+
+#### Platform-Specific Variables
+
+Use environment variables for platform differences:
+
+```bash
+# Mac/Linux (.env.local)
+D365_CLIENT_ID=your-client-id
+D365_CLIENT_SECRET=your-client-secret
+NODE_ENV=development
+PATH_SEPARATOR=/
+```
+
+```powershell
+# Windows (.env.local)
+D365_CLIENT_ID=your-client-id
+D365_CLIENT_SECRET=your-client-secret
+NODE_ENV=development
+PATH_SEPARATOR=\
+```
+
+## Development Environment Setup
+
+### 🚀 Quick Start by Platform
+
+#### Windows Developers
+
+```powershell
+# 1. Run team onboarding script
+.\deployment\scripts\team-onboarding.ps1
+
+# 2. Follow Windows-specific guide
+start deployment\QUICKSTART-WINDOWS.md
+
+# 3. Validate setup
+.\deployment\scripts\validate-setup.ps1
+
+# 4. First deployment test
+.\deployment\scripts\deploy.ps1 -Environment dev -DryRun
+```
+
+#### Mac Developers
+
+```bash
+# 1. Run team onboarding script
+./deployment/scripts/team-onboarding.sh
+
+# 2. Follow Mac-specific guide
+open deployment/QUICKSTART-MAC.md
+
+# 3. Validate setup
+./deployment/scripts/validate-setup.sh
+
+# 4. First deployment test
+./deployment/scripts/deploy.sh dev --dry-run
+```
+
+### 🛠️ Common Tool Requirements
+
+All team members must have:
+
+| Tool            | Windows Installation   | Mac Installation                         | Purpose             |
+| --------------- | ---------------------- | ---------------------------------------- | ------------------- |
+| **Node.js 18+** | `choco install nodejs` | `brew install node`                      | Runtime environment |
+| **Git**         | `choco install git`    | `brew install git`                       | Version control     |
+| **VS Code**     | `choco install vscode` | `brew install --cask visual-studio-code` | IDE                 |
+| **jq**          | `choco install jq`     | `brew install jq`                        | JSON processing     |
+
+### 🔧 Platform-Specific Tools
+
+#### Windows-Only Tools
+
+```powershell
+# PowerShell modules for Dynamics 365
+Install-Module Microsoft.PowerApps.Administration.PowerShell
+Install-Module Microsoft.PowerApps.PowerShell
+
+# Windows Subsystem for Linux (optional)
+wsl --install
+
+# Chocolatey package manager
+Set-ExecutionPolicy Bypass -Scope Process -Force
+iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))
+```
+
+#### Mac-Only Tools
+
+```bash
+# Homebrew package manager
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Xcode Command Line Tools
+xcode-select --install
+
+# Docker Desktop for Mac
+brew install --cask docker
+```
+
+## Git and Version Control
+
+### 🌿 Branch Strategy
+
+All team members follow the same Git workflow:
+
+```bash
+# Main branches (same for all platforms)
+main           # Production-ready code
+develop        # Integration branch
+feature/*      # Feature development
+hotfix/*       # Production fixes
+release/*      # Release preparation
+```
+
+### 📝 Commit Standards
+
+#### Commit Message Format
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+**Examples:**
+
+```bash
+feat(auth): add Azure AD authentication
+fix(deploy): resolve PowerShell execution policy issue
+docs(readme): update cross-platform setup instructions
+style(format): apply prettier formatting
+```
+
+#### Cross-Platform Commit Hooks
+
+```bash
+# .husky/pre-commit (works on both platforms)
+#!/bin/sh
+npm run lint
+npm run typecheck
+npm run test:staged
+```
+
+### 🔄 Pull Request Process
+
+#### Required Checks
+
+All PRs must pass:
+
+- ✅ **Cross-platform validation** (Windows + Linux CI)
+- ✅ **Code review** (minimum 2 approvals)
+- ✅ **Automated tests** (unit + integration)
+- ✅ **Deployment simulation** (dry-run on both platforms)
+
+#### Review Guidelines
+
+1. **Platform Compatibility**: Reviewer checks both Windows and Mac workflows
+2. **Script Validation**: If modifying deployment scripts, test both .ps1 and .sh
+3. **Documentation Updates**: Update platform-specific docs when needed
+4. **Configuration Changes**: Verify JSON configs work across platforms
+
+## Code Standards and Reviews
+
+### 📋 Code Style Standards
+
+#### TypeScript/JavaScript
+
+```json
+// .eslintrc.json (shared across platforms)
+{
+  "extends": ["@typescript-eslint/recommended", "prettier"],
+  "rules": {
+    "no-console": "error",
+    "prefer-const": "error",
+    "@typescript-eslint/no-unused-vars": "error"
+  }
+}
+```
+
+#### File Path Handling
+
+```typescript
+// ❌ Platform-specific (Windows-only)
+const filePath = 'src\\components\\MyComponent.tsx';
+
+// ✅ Cross-platform compatible
+import path from 'path';
+const filePath = path.join('src', 'components', 'MyComponent.tsx');
+```
+
+#### Environment Variables
+
+```typescript
+// ❌ Platform-specific
+const isDev = process.env.NODE_ENV === 'development';
+const separator = process.platform === 'win32' ? '\\' : '/';
+
+// ✅ Cross-platform
+const isDev = process.env.NODE_ENV === 'development';
+const separator = path.sep; // Use Node.js path module
+```
+
+### 🔍 Review Checklist
+
+#### General Code Review
+
+- [ ] Code follows TypeScript strict mode
+- [ ] No hardcoded file paths (use path.join)
+- [ ] Environment variables used for configuration
+- [ ] Error handling includes platform context
+- [ ] Logging uses centralized logger
+- [ ] Comments explain platform-specific logic
+
+#### Platform-Specific Review
+
+- [ ] Windows: PowerShell scripts have proper error handling
+- [ ] Mac: Bash scripts have proper permissions (chmod +x)
+- [ ] Both: JSON configurations are valid
+- [ ] Both: Build artifacts are identical
+- [ ] Both: Deployment results are consistent
+
+## Communication and Collaboration
+
+### 💬 Communication Standards
+
+#### Daily Standups
+
+**Format:** Video call with shared screen
+
+**Platform Considerations:**
+
+- Windows team members share PowerShell deployment results
+- Mac team members share Terminal/Bash deployment results
+- All share VS Code debugging and development experience
+- Focus on blockers that might be platform-specific
+
+#### Platform-Specific Channels
+
+**Slack/Teams Structure:**
+
+```
+#dynamics-general        # All team communication
+#dynamics-windows        # Windows-specific issues
+#dynamics-mac            # Mac-specific issues
+#dynamics-deployment     # Cross-platform deployment
+#dynamics-troubleshooting # Platform issues help
+```
+
+### 📚 Knowledge Sharing
+
+#### Weekly Platform Updates
+
+**Every Friday 3:00 PM:**
+
+- Windows team shares PowerShell tips and tricks
+- Mac team shares Terminal/Bash improvements
+- Both teams demo new tools and workflows
+- Cross-platform troubleshooting session
+
+#### Documentation Responsibilities
+
+| Team Member      | Responsibility                                  |
+| ---------------- | ----------------------------------------------- |
+| **Windows Lead** | Maintain QUICKSTART-WINDOWS.md and .ps1 scripts |
+| **Mac Lead**     | Maintain QUICKSTART-MAC.md and .sh scripts      |
+| **DevOps Lead**  | Ensure CI/CD works on both platforms            |
+| **All Members**  | Update cross-platform compatibility notes       |
+
+### 🎯 Pair Programming Guidelines
+
+#### Cross-Platform Pairing
+
+**Best Practices:**
+
+- Use VS Code Live Share for real-time collaboration
+- Share terminal sessions for deployment testing
+- Test deployments on both platforms during pairing
+- Document any platform-specific discoveries
+
+**Pairing Rotation:**
+
+- Windows ↔ Mac pairing every sprint
+- Senior ↔ Junior cross-platform mentoring
+- DevOps ↔ Developer deployment knowledge sharing
+
+## CI/CD and Deployment
+
+### 🚀 Pipeline Strategy
+
+Our CI/CD supports both platforms with optimized stage distribution:
+
+```yaml
+# Pipeline Strategy
+Build: Linux (fastest performance)
+Dev Deploy: Linux + Bash (Mac developer experience)
+Test Deploy: Windows + PowerShell (Windows validation)
+Prod Deploy: Flexible choice (team preference)
+```
+
+### 🔧 Deployment Commands
+
+#### Command Equivalents
+
+| Task             | Windows PowerShell                                        | Mac Bash                           | Result     |
+| ---------------- | --------------------------------------------------------- | ---------------------------------- | ---------- |
+| **Deploy Dev**   | `.\deploy.ps1 -Environment dev`                           | `./deploy.sh dev`                  | Identical  |
+| **Health Check** | `.\health-check.ps1 -Environment prod`                    | `./health-check.sh prod`           | Same data  |
+| **Rollback**     | `.\rollback.ps1 -Environment prod -BackupFile backup.zip` | `./rollback.sh prod backup.tar.gz` | Same state |
+
+#### Local Development
+
+```bash
+# All platforms use same npm commands
+npm run build:dev       # Development build
+npm run build:prod      # Production build
+npm run lint            # Code linting
+npm run typecheck       # TypeScript validation
+npm run test            # Unit tests
+npm run deploy:dev      # Deploy to development
+```
+
+### 🏗️ Build Consistency
+
+#### Shared Build Configuration
+
+```json
+// package.json (platform-agnostic scripts)
+{
+  "scripts": {
+    "build:dev": "webpack --mode development",
+    "build:prod": "webpack --mode production",
+    "deploy:dev": "node scripts/deploy.js dev",
+    "deploy:test": "node scripts/deploy.js test",
+    "deploy:prod": "node scripts/deploy.js prod"
+  }
+}
+```
+
+#### Platform-Specific Scripts
+
+```javascript
+// scripts/deploy.js (detects platform and runs appropriate script)
+const os = require('os');
+const { exec } = require('child_process');
+
+const platform = os.platform();
+const environment = process.argv[2];
+
+const command =
+  platform === 'win32'
+    ? `.\\deployment\\scripts\\deploy.ps1 -Environment ${environment}`
+    : `./deployment/scripts/deploy.sh ${environment}`;
+
+exec(command, (error, stdout, stderr) => {
+  if (error) {
+    console.error(`Deployment failed: ${error}`);
+    process.exit(1);
+  }
+  console.log(stdout);
+});
+```
+
+## Troubleshooting Cross-Platform Issues
+
+### 🔧 Common Platform Issues
+
+#### File Path Problems
+
+**Issue:** Windows backslashes vs Unix forward slashes
+
+**Solution:**
+
+```typescript
+// Use Node.js path module
+import path from 'path';
+
+// ❌ Wrong
+const configPath = 'config\\environments\\dev.json';
+
+// ✅ Correct
+const configPath = path.join('config', 'environments', 'dev.json');
+```
+
+#### Script Execution Issues
+
+**Windows PowerShell:**
+
+```powershell
+# Issue: Execution policy prevents script running
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Issue: Module not found
+Install-Module Microsoft.PowerApps.PowerShell -Force -AllowClobber
+```
+
+**Mac/Linux Bash:**
+
+```bash
+# Issue: Script not executable
+chmod +x deployment/scripts/*.sh
+
+# Issue: Missing dependencies
+brew install jq curl node npm
+```
+
+#### Environment Variables
+
+**Windows:**
+
+```powershell
+# Set for session
+$env:D365_CLIENT_ID = "your-client-id"
+
+# Set permanently
+[Environment]::SetEnvironmentVariable("D365_CLIENT_ID", "your-client-id", "User")
+```
+
+**Mac/Linux:**
+
+```bash
+# Set for session
+export D365_CLIENT_ID="your-client-id"
+
+# Set permanently
+echo 'export D365_CLIENT_ID="your-client-id"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### 🚨 Escalation Process
+
+#### Level 1: Self-Help
+
+1. Check platform-specific quick start guide
+2. Review troubleshooting section in deployment README
+3. Search team Slack channels for similar issues
+4. Try the other platform's approach (if applicable)
+
+#### Level 2: Team Support
+
+1. Post in platform-specific Slack channel
+2. Tag platform champion for assistance
+3. Share complete error logs and environment info
+4. Schedule pairing session if needed
+
+#### Level 3: Architecture Review
+
+1. Escalate to technical lead
+2. Review if issue indicates larger architectural problem
+3. Consider if platform-agnostic solution is needed
+4. Update team standards if pattern emerges
+
+### 📋 Debugging Checklist
+
+#### When Things Don't Work
+
+**Information to Gather:**
+
+- [ ] Operating system and version
+- [ ] Node.js and npm versions
+- [ ] PowerShell version (Windows) or Shell version (Mac)
+- [ ] Complete error message and stack trace
+- [ ] Command that was executed
+- [ ] Environment variables and configuration
+- [ ] Recent changes to codebase
+
+**Steps to Take:**
+
+1. **Reproduce on other platform** - Does it work on Windows/Mac?
+2. **Check recent changes** - What changed since it last worked?
+3. **Validate environment** - Run validation script
+4. **Compare configurations** - Are configs identical?
+5. **Test in isolation** - Remove variables one by one
+
+## Team Onboarding Process
+
+### 🎯 New Team Member Checklist
+
+#### Week 1: Platform Setup
+
+**Day 1: Environment Setup**
+
+- [ ] Clone project repository
+- [ ] Run platform-specific onboarding script
+- [ ] Complete environment validation
+- [ ] Set up development tools (VS Code, Git, etc.)
+- [ ] Join communication channels
+
+**Day 2: Cross-Platform Awareness**
+
+- [ ] Read both platform quick start guides
+- [ ] Understand deployment command equivalents
+- [ ] Review CI/CD pipeline documentation
+- [ ] Learn about platform-specific troubleshooting
+
+**Day 3: Development Environment**
+
+- [ ] Set up local development environment
+- [ ] Run first successful build
+- [ ] Deploy to development environment
+- [ ] Test health check commands
+
+**Day 4: Code Standards and Git**
+
+- [ ] Review coding standards document
+- [ ] Set up Git hooks and commit templates
+- [ ] Practice pull request workflow
+- [ ] Complete first code review
+
+**Day 5: Team Integration**
+
+- [ ] Pair with team member from other platform
+- [ ] Attend cross-platform knowledge sharing session
+- [ ] Complete onboarding feedback survey
+- [ ] Contribute to team documentation
+
+#### Week 2: Project Deep Dive
+
+**Focus Areas:**
+
+- Client business requirements and context
+- Technical architecture and patterns
+- Integration points and external systems
+- Testing strategies and quality processes
+- Deployment procedures and troubleshooting
+
+### 🤝 Buddy System
+
+Each new team member is paired with:
+
+1. **Platform Buddy** - Same platform expert for immediate help
+2. **Cross-Platform Buddy** - Other platform expert for broader perspective
+3. **Project Buddy** - Experienced team member for business context
+
+### 📚 Training Resources
+
+#### Required Reading
+
+- [ ] Cross-Platform Team Development Standards (this document)
+- [ ] Platform-specific quick start guide
+- [ ] Project architecture overview
+- [ ] Client requirements and business context
+- [ ] Deployment and CI/CD documentation
+
+#### Optional Learning
+
+- [ ] Other platform's quick start guide
+- [ ] Advanced debugging techniques
+- [ ] Performance optimization strategies
+- [ ] Security and compliance requirements
+- [ ] Dynamics 365 platform deep dive
+
+## Best Practices and Guidelines
+
+### ✅ Do's
+
+#### Development Practices
+
+- **Use path.join()** for all file path operations
+- **Test on both platforms** before submitting PR
+- **Document platform differences** when they occur
+- **Share learning** with the team regularly
+- **Validate deployments** on both platforms in CI/CD
+
+#### Collaboration Practices
+
+- **Rotate pairing partners** across platforms weekly
+- **Include both platforms** in architectural discussions
+- **Share terminal sessions** during troubleshooting
+- **Maintain platform-specific documentation** as first-class citizens
+- **Celebrate platform diversity** as a team strength
+
+#### Documentation Practices
+
+- **Keep both guides updated** when making changes
+- **Include command equivalents** in all procedural docs
+- **Document platform-specific gotchas** immediately
+- **Create searchable knowledge base** for common issues
+- **Video record complex setup procedures** for both platforms
+
+### ❌ Don'ts
+
+#### Development Anti-Patterns
+
+- **Don't hardcode file paths** with platform-specific separators
+- **Don't assume single platform** in scripts or documentation
+- **Don't ignore CI failures** on other platforms
+- **Don't commit platform-specific** temporary files
+- **Don't skip cross-platform validation** for "simple" changes
+
+#### Collaboration Anti-Patterns
+
+- **Don't create platform silos** or exclusive teams
+- **Don't dismiss other platform approaches** without understanding
+- **Don't let one platform dominate** architectural decisions
+- **Don't ignore knowledge sharing** opportunities
+- **Don't assume platform expertise** translates to superiority
+
+### 🎯 Success Metrics
+
+#### Team Performance Indicators
+
+- **Cross-platform deployment success rate** > 95%
+- **Platform-specific build failures** < 5%
+- **Knowledge sharing sessions attendance** > 80%
+- **Cross-platform code reviews** > 50%
+- **Platform champion availability** < 4 hour response time
+
+#### Quality Indicators
+
+- **Identical deployment results** across platforms
+- **Consistent development experience** regardless of platform
+- **Comprehensive platform documentation** maintained
+- **Zero platform bias** in architectural decisions
+- **High team satisfaction** with cross-platform workflow
+
+### 🔄 Continuous Improvement
+
+#### Monthly Reviews
+
+- **Platform-specific challenges** encountered and resolved
+- **Documentation gaps** identified and addressed
+- **Tool improvements** and workflow optimizations
+- **Team satisfaction** and collaboration effectiveness
+- **Knowledge sharing** quality and frequency
+
+#### Quarterly Assessments
+
+- **Architecture decisions** impact on cross-platform compatibility
+- **CI/CD pipeline** effectiveness and optimization opportunities
+- **Team skills development** in cross-platform competencies
+- **Client satisfaction** with delivery consistency
+- **Technology stack evolution** and platform implications
+
+---
+
+This cross-platform team development guide ensures that Windows and Mac developers can work together
+effectively while leveraging the strengths of each platform. Regular updates and team feedback help
+maintain and improve these standards over time.