diff --git a/.gitignore b/.gitignore index c6bba59..a5a548a 100644 --- a/.gitignore +++ b/.gitignore @@ -121,6 +121,7 @@ dist # Stores VSCode versions used for testing VSCode extensions .vscode-test +.vscode # yarn v2 .yarn/cache diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index ef4ad09..0000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "workbench.colorCustomizations": { - "activityBar.activeBackground": "#9c8af5", - "activityBar.background": "#9c8af5", - "activityBar.foreground": "#15202b", - "activityBar.inactiveForeground": "#15202b99", - "activityBarBadge.background": "#b02a0f", - "activityBarBadge.foreground": "#e7e7e7", - "commandCenter.border": "#e7e7e799", - "sash.hoverBorder": "#9c8af5", - "statusBar.background": "#745bf1", - "statusBar.foreground": "#e7e7e7", - "statusBarItem.hoverBackground": "#9c8af5", - "statusBarItem.remoteBackground": "#745bf1", - "statusBarItem.remoteForeground": "#e7e7e7", - "titleBar.activeBackground": "#745bf1", - "titleBar.activeForeground": "#e7e7e7", - "titleBar.inactiveBackground": "#745bf199", - "titleBar.inactiveForeground": "#e7e7e799" - }, - "peacock.color": "#745bf1" -} \ No newline at end of file diff --git a/templates/architecture/service-architecture.md b/templates/architecture/service-architecture.md index 7713c76..7267fd4 100644 --- a/templates/architecture/service-architecture.md +++ b/templates/architecture/service-architecture.md @@ -1,28 +1,26 @@ -# ๐Ÿ“Š System Overview +# ๐Ÿ—๏ธ Service Architecture -This document provides you with an overview of the services (applications), vendors and other assets that make up the our platform and how they interact. +This document provides an overview of the services, vendors, and assets that make up the {{ app }} platform and how they interact. -## Services +## ๐ŸŽฏ Core Services -There are four primary services that make up our platform. -| Service | Description | Endpoint | -|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|------------------------| -| ๐Ÿ”Œ **API** | The {{company}} **API** is the main API for our Platform. It is responsible for all of the business logic and data storage for the Platform. | `https://api.acme.io` | -| ๐ŸŒ **Web** | The {{company}} **Web** consists of a React-based application that is a SPA. | `https://app.acme.io` | -| โš™ **Server** | The {{company}} **Server** is a Fastify based API that serves the **Web** to the client. | `https://app.acme.io` | -| ๐Ÿ”— **Third-Party Service** | The {{company}} **Third-Party Service** is a proxy API for {{reason}}. It is responsible for {{reason}}. | `https://app.acme.io` | +| Service | Description | Endpoint | Owner | +|---------|-------------|----------|-------| +| ๐Ÿ”Œ **API** | The {{ app }} **API** is the main API for our Platform. It is responsible for all of the business logic and data storage for the Platform. | `{{ api-endpoint }}` | {{ api-owner }} | +| ๐ŸŒ **Web** | The {{ app }} **Web** consists of a React-based application that is a SPA. | `{{ web-endpoint }}` | {{ web-owner }} | +| โš™๏ธ **Server** | The {{ app }} **Server** is a Fastify based API that serves the **Web** to the client. | `{{ server-endpoint }}` | {{ server-owner }} | +| ๐Ÿ”— **Third-Party Service** | The {{ app }} **Third-Party Service** is a proxy API for {{ third-party-reason }}. | `{{ third-party-endpoint }}` | {{ third-party-owner }} | -## System Diagram +## ๐Ÿ”„ System Flow ```mermaid %%{init: { @@ -39,10 +37,10 @@ There are four primary services that make up our platform. flowchart TD %% Title - title["Acme Inc. Service Architecture"] + title["{{ company-name }} Service Architecture"] style title fill:none,stroke:none,color:#333,font-weight:bold - %% Core Services - using round shapes with parentheses + %% Core Services web("๐ŸŒ Web Client") style web fill:#7b1fa2,color:white,stroke:#5d1777,stroke-width:2px @@ -55,31 +53,31 @@ flowchart TD third-party("๐Ÿ™ Third-Party Proxy") style third-party fill:#00897b,color:white,stroke:#005b4f,stroke-width:2px - %% AWS Services - database[("๐Ÿ˜ MicrosoftSQL")] + %% Database Services + database[("๐Ÿ˜ {{ database-name }}")] style database fill:#0064a5,color:white,stroke:#004c7f,stroke-width:2px bucket("๐Ÿชฃ Storage Bucket") style bucket fill:#0064a5,color:white,stroke:#004c7f,stroke-width:2px %% Vendor Services - Okta("๐Ÿ” Okta.com") - style Okta fill:#f57c00,color:white,stroke:#bc5100,stroke-width:2px + auth("๐Ÿ” {{ auth-provider }}") + style auth fill:#f57c00,color:white,stroke:#bc5100,stroke-width:2px - thirdpartyapi("๐Ÿ”Œ thirdparty.com") + thirdpartyapi("๐Ÿ”Œ {{ third-party-api }}") style thirdpartyapi fill:#f57c00,color:white,stroke:#bc5100,stroke-width:2px - %% Connections with descriptive labels + %% Connections web -- "Serves UI" --> server web <-- "API Requests" --> api web <-- "CDN Assets" --> api api <-- "Static Assets" --> bucket - api <-- "Auth" --> Okta - web <-- "Login" --> Okta + api <-- "Auth" --> auth + web <-- "Login" --> auth third-party <-- "Proxy Requests" --> thirdpartyapi api -- "Database Queries" --> database - %% Subgraph containers + %% Network Groups subgraph vpc ["๐Ÿ›œ VPC Network"] direction TB api -- "Internal API Calls" --> third-party @@ -88,20 +86,53 @@ flowchart TD end style vpc fill:#e3f2fd,color:#0d47a1,stroke:#0d47a1,stroke-width:3px,stroke-dasharray:5 - subgraph gcp ["๐Ÿ’ฝ AWS Managed Services"] + subgraph cloud ["๐Ÿ’ฝ {{ cloud-provider }} Managed Services"] direction TB database bucket end - style gcp fill:#e1f5fe,color:#01579b,stroke:#01579b,stroke-width:3px,stroke-dasharray:5 + style cloud fill:#e1f5fe,color:#01579b,stroke:#01579b,stroke-width:3px,stroke-dasharray:5 subgraph vendors ["๐Ÿช External Vendors"] direction TB thirdpartyapi - Okta + auth end style vendors fill:#fff3e0,color:#e65100,stroke:#e65100,stroke-width:3px,stroke-dasharray:5 %% Global link styling linkStyle default stroke-width:2px,stroke:#666 ``` + +## ๐Ÿ”’ Security + +### Authentication +- {{ auth-provider }} for user authentication +- {{ auth-flow-description }} + +### Authorization +- {{ authorization-model }} +- {{ role-descriptions }} + +## ๐Ÿ“Š Monitoring & Observability + +### Metrics +- {{ metric-1 }} +- {{ metric-2 }} +- {{ metric-3 }} + +### Logging +- {{ logging-tool }} +- {{ log-retention-policy }} + +## ๐Ÿ” Related Documents + +- [Infrastructure Overview](./infrastructure.md) +- [Security Standards](./security.md) +- [Deployment Process](./deployment.md) + +## ๐Ÿ“š Additional Resources + +- [{{ app }} Architecture Decisions](../architecture/decisions.md) +- [Service Dependencies](./dependencies.md) +- [Performance Guidelines](./performance.md) diff --git a/templates/project/contribution-guidelines.md b/templates/project/contribution-guidelines.md index b84d810..604defb 100644 --- a/templates/project/contribution-guidelines.md +++ b/templates/project/contribution-guidelines.md @@ -1,6 +1,6 @@ -# ๐Ÿš€ **Deployment Guide** -## **Environments** +# ๐Ÿš€ Deployment Guide -| Environment | Description | URL | -|------------|--------------------------------------------------|-------------------------| -| **Staging** | Pre-production testing environment. | staging.example.com | -| **Production** | Live environment. | production.example.com | -| **Sandbox** | Rarely used, but available for experimentation. | sandbox.example.com | +This guide outlines the deployment process for {{ app }} across different environments. +## ๐ŸŽฏ Environments -## **Deployment Steps (GitHub Actions)** +| Environment | Description | URL | Access | +|------------|-------------|-----|---------| +| **Development** | Local development environment | {{ dev-url }} | {{ dev-access }} | +| **Staging** | Pre-production testing environment | {{ staging-url }} | {{ staging-access }} | +| **Production** | Live environment | {{ prod-url }} | {{ prod-access }} | +| **Sandbox** | Testing and experimentation | {{ sandbox-url }} | {{ sandbox-access }} | -1. Push changes to the repository to trigger **GitHub Actions**. +## ๐Ÿ”„ Deployment Process -2. The workflow runs tests, builds, and packages the application. - -3. If tests pass, the deployment is pushed to **staging**. - -4. After verification, an **approval step** is required for **production deployment**. - -5. **Tag the release** before deploying to production. +### Automated Deployment ({{ ci-tool }}) ```mermaid graph LR; - A[๐Ÿ“Œ Code Commit] -->|๐Ÿš€ GitHub Actions Triggered| B[๐Ÿ› ๏ธ Run Tests]; + A[๐Ÿ“Œ Code Commit] -->|๐Ÿš€ {{ ci-tool }} Triggered| B[๐Ÿ› ๏ธ Run Tests]; B -->|๐Ÿ“ฆ Build & Package| C[๐Ÿš€ Deploy to Staging]; C -->|โœ… Verification| D[๐Ÿท๏ธ Tag Release & Approve Deployment]; D -->|๐Ÿš€ Deploy to Production| E[๐ŸŽ‰ Success]; D -->|โŒ Failure| F[๐Ÿ”„ Rollback]; ``` -## ๐Ÿ”„ **Rollback Plan** +### Deployment Steps + +1. **Code Changes** + ```bash + # Create feature branch + git checkout -b feature/{{ feature-name }} + + # Make changes and commit + git add . + git commit -m "{{ commit-message }}" + + # Push changes + git push origin feature/{{ feature-name }} + ``` + +2. **CI/CD Pipeline** + - Automated tests run + - Build process executes + - Staging deployment triggered + +3. **Staging Verification** + - Run integration tests + - Perform manual testing + - Verify monitoring metrics -* Identify the issue and confirm rollback necessity. +4. **Production Deployment** + - Create release tag + - Get approval from {{ approver-role }} + - Deploy to production -* Use **GitHub Actions rollback workflow** to revert to the previous stable release. +## ๐Ÿ›ก๏ธ Rollback Process + +### Automated Rollback ```mermaid graph LR; @@ -51,3 +74,72 @@ graph LR; C -->|๐Ÿ”ฌ Run Tests| D[โœ… Validate Rollback]; D -->|๐Ÿ“ Post-Mortem| E[๐Ÿ“„ Document & Improve]; ``` + +### Rollback Steps + +1. **Issue Detection** + - Monitor {{ monitoring-tool }} + - Review error logs + - Assess impact + +2. **Rollback Execution** + ```bash + # Trigger rollback workflow + {{ rollback-command }} + + # Verify rollback + {{ verification-command }} + ``` + +3. **Post-Rollback Actions** + - Document incident + - Update runbooks + - Schedule post-mortem + +## ๐Ÿ” Pre-Deployment Checklist + +### Code Quality +- [ ] All tests passing +- [ ] Code review completed +- [ ] Documentation updated +- [ ] Dependencies up to date + +### Infrastructure +- [ ] Resource quotas checked +- [ ] Backup verified +- [ ] Monitoring configured +- [ ] Alerts tested + +### Security +- [ ] Security scan passed +- [ ] Secrets rotated +- [ ] Access reviewed +- [ ] Compliance checked + +## ๐Ÿ› ๏ธ Troubleshooting + +### Common Issues + +| Issue | Solution | +|-------|----------| +| {{ issue-1 }} | {{ solution-1 }} | +| {{ issue-2 }} | {{ solution-2 }} | +| {{ issue-3 }} | {{ solution-3 }} | + +### Getting Help + +- **On-Call Engineer**: {{ oncall-contact }} +- **Slack Channel**: `#{{ team-name }}-deployments` +- **Documentation**: [Deployment Handbook](../handbook/deployment.md) + +## ๐Ÿ” Related Documents + +- [Infrastructure Overview](../architecture/infrastructure.md) +- [Monitoring Setup](../monitoring/setup.md) +- [Security Standards](../security/standards.md) + +## ๐Ÿ“š Additional Resources + +- [{{ ci-tool }} Documentation]({{ ci-docs-url }}) +- [Infrastructure as Code](../iac/README.md) +- [Release Management](../release/README.md) diff --git a/templates/project/how-to-guide.md b/templates/project/how-to-guide.md index 9fb946e..27ed530 100644 --- a/templates/project/how-to-guide.md +++ b/templates/project/how-to-guide.md @@ -1,43 +1,114 @@ -# ๐Ÿ“– How-To Guide: [Your Topic Here] +# ๐Ÿ“– How-To Guide: {{ guide-title }} -## ๐Ÿ“Œ Overview -This guide explains how to **[achieve a specific task]** using **[technology/tool]**. Follow the steps below to complete the process. +This guide explains how to {{ task-description }} using {{ technology-tool }}. ---- +## ๐ŸŽฏ Overview -## ๐Ÿ›  Prerequisites -Before you begin, ensure you have the following: -- โœ… **[Requirement 1]** โ€“ e.g., Installed software, access credentials -- โœ… **[Requirement 2]** โ€“ e.g., Configuration settings, dependencies -- โœ… **[Requirement 3]** โ€“ e.g., Permissions, environment setup +{{ overview-description }} ---- +## ๐Ÿ“‹ Prerequisites + +### Required Software +| Software | Version | Installation Guide | +|----------|---------|-------------------| +| {{ software-1 }} | {{ version-1 }} | [Installation Guide]({{ guide-1-url }}) | +| {{ software-2 }} | {{ version-2 }} | [Installation Guide]({{ guide-2-url }}) | + +### Required Access +- {{ access-requirement-1 }} +- {{ access-requirement-2 }} +- {{ access-requirement-3 }} + +### Required Configuration +- {{ config-1 }} +- {{ config-2 }} +- {{ config-3 }} ## ๐Ÿš€ Step-by-Step Instructions -### **1๏ธโƒฃ Step 1: [Brief Description]** -๐Ÿ”น **What this step does:** -_Explain why this step is important._ +### 1. {{ step-1-title }} + +**Purpose:** {{ step-1-purpose }} + +```bash +# {{ step-1-command-description }} +{{ step-1-command }} +``` + +**Expected Output:** +```bash +{{ step-1-expected-output }} +``` + +### 2. {{ step-2-title }} -```sh -# Example command or code snippet -command --option value +**Purpose:** {{ step-2-purpose }} + +```bash +# {{ step-2-command-description }} +{{ step-2-command }} ``` -### **2๏ธโƒฃ Step 2: [Brief Description]** -๐Ÿ”น **What this step does:** -_Explain why this step is important._ +**Expected Output:** +```bash +{{ step-2-expected-output }} +``` -```sh -# Example command or code snippet -command --option value +### 3. {{ step-3-title }} + +**Purpose:** {{ step-3-purpose }} + +```bash +# {{ step-3-command-description }} +{{ step-3-command }} ``` + +**Expected Output:** +```bash +{{ step-3-expected-output }} +``` + +## ๐ŸŽ‰ Verification + +To verify the process was successful: + +1. {{ verification-step-1 }} +2. {{ verification-step-2 }} +3. {{ verification-step-3 }} + +## ๐Ÿ› ๏ธ Troubleshooting + +### Common Issues + +| Issue | Solution | +|-------|----------| +| {{ issue-1 }} | {{ solution-1 }} | +| {{ issue-2 }} | {{ solution-2 }} | +| {{ issue-3 }} | {{ solution-3 }} | + +### Getting Help + +- **Slack Channel**: `#{{ team-name }}-help` +- **Documentation**: [Related Guide](../guides/{{ related-guide }}.md) +- **Support Contact**: {{ support-contact }} + +## ๐Ÿ” Related Documents + +- [{{ related-doc-1 }}](../docs/{{ related-doc-1 }}.md) +- [{{ related-doc-2 }}](../docs/{{ related-doc-2 }}.md) +- [{{ related-doc-3 }}](../docs/{{ related-doc-3 }}.md) + +## ๐Ÿ“š Additional Resources + +- [{{ resource-1 }}]({{ resource-1-url }}) +- [{{ resource-2 }}]({{ resource-2-url }}) +- [{{ resource-3 }}]({{ resource-3-url }}) diff --git a/templates/project/setup-local-environment.md b/templates/project/setup-local-environment.md index b545e8f..e348c5b 100644 --- a/templates/project/setup-local-environment.md +++ b/templates/project/setup-local-environment.md @@ -1,71 +1,136 @@ -# โš™๏ธ Requirements +# โš™๏ธ Local Development Setup -*Update the requirements and provide links to instructions (on how to meet/install the requirements) as needed.* +This guide will help you set up your local development environment for {{ app }}. -* ๐Ÿณ [*docker@v27+*](https://docs.docker.com/desktop/install/mac-install/) *(installed via Docker Desktop)* -* ๐ŸŸข [*node@v20+*](https://nodejs.org/en/download) +## ๐ŸŽฏ Prerequisites -# ๐Ÿš€ Getting Started +### Required Software +| Software | Version | Installation Guide | +|----------|---------|-------------------| +| ๐Ÿณ Docker | v27+ | [Docker Desktop Installation]({{ docker-install-guide }}) | +| ๐ŸŸข Node.js | v20+ | [Node.js Download]({{ nodejs-download-url }}) | +| {{ other-requirement-1 }} | {{ version-1 }} | [Installation Guide]({{ guide-1-url }}) | +| {{ other-requirement-2 }} | {{ version-2 }} | [Installation Guide]({{ guide-2-url }}) | -*Add a brief description of the steps to get started, and update or remove the example steps below.* +### System Requirements +- {{ system-requirement-1 }} +- {{ system-requirement-2 }} +- {{ system-requirement-3 }} -## ๐Ÿ”น Step 1: *Clone the repository* +## ๐Ÿš€ Setup Steps -*Clone the repository to your local machine.* +### 1. Clone Repository -```shell -git clone https://github.com/acme/backend.git +```bash +git clone {{ repository-url }} +cd {{ repository-name }} ``` -## ๐Ÿ”น Step 2: *Install dependencies* +### 2. Environment Setup -*Install the project dependencies.* +1. Copy the example environment file: + ```bash + cp .env.example .env + ``` -```shell +2. Update the environment variables: + ```bash + # Required variables + DATABASE_URL={{ database-url }} + API_KEY={{ api-key }} + # Add other required variables + ``` + +### 3. Install Dependencies + +```bash +# Install project dependencies npm install -``` -## ๐Ÿ”น Step 3: *Run Database Migrations* +# Install global dependencies (if needed) +npm install -g {{ global-dependency-1 }} +npm install -g {{ global-dependency-2 }} +``` -*Run the database migrations, if needed.* +### 4. Database Setup -```shell +```bash +# Run database migrations npm run db:migrate -``` -## ๐Ÿ”น Step 4: *Start the server* +# Seed the database (if needed) +npm run db:seed +``` -*Start the server.* +### 5. Start Services -```shell +```bash +# Start all required services docker-compose up -d + +# Verify services are running +docker-compose ps ``` -# ๐ŸŽ‰ Done +## ๐ŸŽ‰ Verify Installation + +1. Start the development server: + ```bash + npm run dev + ``` + +2. Access the application: + - Frontend: {{ frontend-url }} + - API: {{ api-url }} + - Admin Panel: {{ admin-url }} + +## ๐Ÿงช Run Tests + +```bash +# Run unit tests +npm run test:unit + +# Run integration tests +npm run test:integration + +# Run all tests +npm test +``` -You are all set and can now run the project locally! +## ๐Ÿ› ๏ธ Troubleshooting -*You can now view the running app at:* `http://localhost:3000` +### Common Issues -# ๐Ÿ› ๏ธ Troubleshooting +| Issue | Solution | +|-------|----------| +| **Unable to connect to the server** | - Check your internet connection
- Verify the server is running
- Check Docker containers status | +| **Database connection errors** | - Verify database credentials in `.env`
- Ensure database service is running
- Check database port availability | +| {{ issue-1 }} | {{ solution-1 }} | +| {{ issue-2 }} | {{ solution-2 }} | -*Add any troubleshooting steps here, you can either use bullet list or sections with headers.* +### Getting Help -* `Unable to connect to the server` *: Check your internet connection and make sure the server is running.* *If you are using Docker, make sure the containers are running.* +- **Slack Channel**: `#{{ team-name }}-dev-help` +- **Documentation**: [Development Guide](../guides/development.md) +- **Support Contact**: {{ support-contact }} -* `Can't reach database server at localhost:5432` *: Make sure the database server is running and the connection details are correct.* *If you are using Docker, make sure the containers are running.* +## ๐Ÿ” Related Documents -# ๐Ÿ“š Resources +- [Architecture Overview](../architecture/overview.md) +- [Development Guidelines](../standards/development.md) +- [Testing Standards](../standards/testing.md) -*Add any related resources here.* +## ๐Ÿ“š Additional Resources -* [*Link to a related resource*](https://example.com) +- [{{ app }} Documentation]({{ docs-url }}) +- [API Reference]({{ api-docs-url }}) +- [Contributing Guide](../contributing.md) diff --git a/templates/standards/code-style.md b/templates/standards/code-style.md index 6b9ed27..86a5488 100644 --- a/templates/standards/code-style.md +++ b/templates/standards/code-style.md @@ -1,23 +1,25 @@ -# ๐Ÿ‘จโ€๐Ÿ’ป Code Standards +# ๐Ÿ‘จโ€๐Ÿ’ป Code Style Standards -As an engineering organization focused on operational excellence, we understand that the code itself many times is the best documentation and keeping a standardized format for things like file naming, function declarations, and more, is important for the end-reader of code. This includes when trying to review code, decipher code you didn't write or pulling in samples. We live by one rule with our code styles: +This document outlines the code style standards for {{ team-name }} to ensure consistent, readable, and maintainable code across our organization. -> You cannot tell who wrote the code, only that someone on the {{team-name}} did. +## ๐ŸŽฏ Core Principle -## Coding Standards +> You cannot tell who wrote the code, only that someone on the {{ team-name }} did. -### Naming Conventions +## ๐Ÿ“ Naming Conventions -**Variables & Functions:** `camelCase` +### Variables & Functions + +Use `camelCase` for variables and functions: ```typescript const userName = 'JohnDoe'; @@ -26,7 +28,9 @@ function getUserData() { } ``` -**Classes & Components:** `PascalCase` +### Classes & Components + +Use `PascalCase` for classes and components: ```typescript class UserProfile { @@ -40,41 +44,61 @@ function App() { } ``` -**Constants:** `UPPER_CASE` +### Constants + +Use `UPPER_CASE` for constants: ```typescript const API_KEY = '12345-ABCDE'; const MAX_USERS = 100; ``` -**File Names:** `kebab-case` +### File Names + +Use `kebab-case` for file names: ```typescript user-profile.js dashboard-view.tsx ``` -### Comments +## ๐Ÿ’ฌ Comments & Documentation -* **Use JSDoc** for documenting functions and APIs. +### Function Documentation -* **Header Comments** for large files only. +Use JSDoc for documenting functions and APIs: -* **Section & Subsection Comments** for organizing large logic blocks. +```typescript +/** + * Retrieves user data from the API + * @param {string} userId - The unique identifier of the user + * @returns {Promise} The user's data + * @throws {Error} If the user is not found + */ +async function getUserData(userId) { + // implementation +} +``` -* **Avoid redundant comments** โ€“ describe intent, not obvious functionality. +### File Organization -### Linting & Formatting +- Use header comments for large files only +- Use section comments for organizing large logic blocks +- Avoid redundant comments โ€“ describe intent, not obvious functionality -* **Linting:** [ESLint](https://eslint.org/). +## ๐Ÿ› ๏ธ Linting & Formatting -* **Formatting:** [Prettier](https://prettier.io/), standard config. +### Tools -* **No additional warnings in PRs** โ€“ aim for zero lint errors. +- **Linting**: {{ linting-tool }} +- **Formatting**: {{ formatting-tool }} +- **Type Checking**: {{ type-checking-tool }} -### Prettier Config +### Configuration -```plaintext +#### Prettier Config + +```json { "printWidth": 80, "tabWidth": 2, @@ -85,7 +109,7 @@ dashboard-view.tsx } ``` -### Prettier Ignore +#### Prettier Ignore ```plaintext # Basics @@ -103,3 +127,24 @@ build/ **/__fixtures__/ **/fixtures/ ``` + +## ๐Ÿ” Code Review Standards + +### Linting Requirements + +- No linting errors in PRs +- All new code must pass type checking +- Follow existing patterns in the codebase + +### Documentation Requirements + +- Update relevant documentation +- Add JSDoc comments for new functions +- Update README if needed + +## ๐Ÿ“š Additional Resources + +- [{{ team-name }} Engineering Handbook](../handbook.md) +- [Architecture Standards](./architecture.md) +- [Testing Standards](./testing.md) +- [Git Workflow](./git-workflow.md) diff --git a/templates/standards/documentation.md b/templates/standards/documentation.md index 801daf0..35ed881 100644 --- a/templates/standards/documentation.md +++ b/templates/standards/documentation.md @@ -1,6 +1,6 @@ -# ๐Ÿšจ Incident Management +# ๐Ÿšจ Incident Management Standards -A structured incident management process is crucial to: +This document outlines the incident management process for {{ team-name }} to ensure consistent and effective incident response. -* ๐Ÿš€ **Minimize Downtime** +## ๐ŸŽฏ Key Objectives -* ๐ŸŽ‰ **Improve Customer Satisfaction** +- ๐Ÿš€ **Minimize Downtime**: Quick and efficient incident resolution +- ๐ŸŽ‰ **Improve Customer Satisfaction**: Clear communication and rapid response +- ๐Ÿš **Maintain Business Continuity**: Robust incident handling procedures -* ๐Ÿš **Maintain Business Continuity** - -It also enhances team collaboration, ensures compliance, builds stakeholder trust, and strengthens system reliability. - -## Incident Management Process +## ๐Ÿ”„ Process Flow ```mermaid graph LR; @@ -65,28 +63,59 @@ graph LR; end; ``` -## Tools +## ๐Ÿ› ๏ธ Tools & Technologies + +| Tool | Description | Usage | +|------|-------------|-------| +| {{ incident-tool }} | {{ incident-tool-description }} | {{ incident-tool-usage }} | +| {{ monitoring-tool }} | {{ monitoring-tool-description }} | {{ monitoring-tool-usage }} | +| {{ logging-tool }} | {{ logging-tool-description }} | {{ logging-tool-usage }} | + +## โš ๏ธ Alert Management + +### Alert Severity Levels + +| Level | Description | Response Time | Escalation Path | +|-------|-------------|---------------|-----------------| +| P1 | Critical - Service Down | < 15 minutes | {{ p1-escalation }} | +| P2 | Major - Service Degraded | < 30 minutes | {{ p2-escalation }} | +| P3 | Minor - Non-Critical | < 2 hours | {{ p3-escalation }} | +| P4 | Low - Informational | < 4 hours | {{ p4-escalation }} | + +### Active Alerts + +| Alert | Description | Runbook | Owner | +|-------|-------------|---------|-------| +| {{ alert-name }} | {{ alert-description }} | [View Runbook]({{ runbook-link }}) | {{ alert-owner }} | + +> [!TIP] +> For teams using a single alerting system (e.g., DataDog), consider embedding runbooks directly in the alert configuration rather than maintaining this table. + +## ๐Ÿ“ Post-Mortem Process + +1. **Incident Summary** + - Timeline of events + - Impact assessment + - Root cause analysis -We use the following tools and technologies to support our incident management process. +2. **Action Items** + - Immediate fixes + - Long-term improvements + - Documentation updates -| Tool | Description | -|-------------|-----------------------------------------------------------------------------| -| Incident.io | Describe in 2-3 sentences what the platform is and what you use it for. | -| Checkly | Describe in 2-3 sentences what the platform is and what you use it for. | -| DataDog | Describe in 2-3 sentences what the platform is and what you use it for. | -| | | +3. **Documentation** + - Update runbooks + - Add new runbooks for gaps + - Share learnings with team -## Alerts +## ๐Ÿ” Related Standards -Below is a table of our alerts and the corresponding runbooks. +- [On-Call Guidelines](./on-call.md) +- [Runbook Standards](./runbooks.md) +- [Communication Guidelines](./communication.md) -> \[!TIP] -> -> If you are only using a single system for defining alerts, it may be overkill to build this table. We would recommend you embed the runbooks directly in that system, next to the alert. For example, if you use DataDog, embed the URL for the runbook next to the alert in DataDog. +## ๐Ÿ“š Additional Resources -| Alert | Description | Runbook | -|--------------------|----------------------------------------------|--------------------| -| Example Alert #1 | Describe the alert in 1 to 2 sentences | Link to Runbook | -| Example Alert #1 | Describe the alert in 1 to 2 sentences | Link to Runbook | -| Example Alert #1 | Describe the alert in 1 to 2 sentences | Link to Runbook | -| | | | +- [{{ team-name }} Incident Playbook](../playbooks/incident.md) +- [Architecture Overview](../architecture/overview.md) +- [Service Dependencies](../architecture/dependencies.md) diff --git a/templates/standards/software-development.md b/templates/standards/software-development.md index 8a3579d..474bd4e 100644 --- a/templates/standards/software-development.md +++ b/templates/standards/software-development.md @@ -1,15 +1,15 @@ -# โš™๏ธ Software Development +# โš™๏ธ Software Development Standards -Below is our software development process. +This document outlines the software development process for {{ team-name }}. ```mermaid graph LR; @@ -46,11 +46,24 @@ graph LR; end; ``` -## Phases -| Phase | Description | Definition of Done | -|-------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ๐Ÿ“‹ Requirements | During this stage, we review the PRD as an engineering team and get all of our questions answered before we start development. | All engineers **MUST** sign off on the PRD by approving the pull request. | -| ๐ŸŽจ Technical Discovery | Before starting development, we complete an RFC to scope out the work for the PRD. | - All engineers **MUST** sign off on the approach outlined in the RFC by approving the pull request.
- The Engineering Team **MUST** be able to tell the Product Team how long the feature will take.
- The Engineering Team and Product Team **MUST** agree to any increase or decrease in scope that came from the RFC learnings.
- All changes to requirements that come from the RFC learnings **MUST** be updated in the PRD. | -| ๐Ÿ’ป Write & Review Code | We write the code for the features we agreed upon in the PRD and open a Pull Request to get the other engineersโ€™ feedback. All testing at this stage is done via a preview environment. | - The engineering team **MUST** write the code for the feature, following all **Code Style Standards**.
- The engineering team **MUST** sign off on the Pull Request and follow all **Code Review Standards**.
- The engineering team **MUST** document the feature(s), following all **Documentation Standards**. | -| ๐Ÿงช User Acceptance Testing ("UAT") | The product manager who wrote the PRD tests the feature to ensure the engineering team completed all of the requirements. | - The Engineering Team **MUST** deploy the feature to staging, so the Product Manager can complete UAT.
- The Product Manager **MUST** sign off that the feature is ready to deploy to production. | -| ๐Ÿš€ Launch Feature | The engineering team deploys the feature to production, does a quick smoke test, and the product manager announces the feature to our users. | - The Engineering Team **MUST** deploy the feature to production, complete a quick smoke test, and **MUST** let the Product Team know when this is complete.
- The Product Team **MUST** announce this feature to the users. | +## ๐Ÿ“‹ Development Phases + +| Phase | Description | Definition of Done | +|-------|-------------|-------------------| +| **Requirements** | During this stage, we review the PRD as an engineering team and get all of our questions answered before we start development. | All engineers **MUST** sign off on the PRD by approving the pull request. | +| **Technical Discovery** | Before starting development, we complete an RFC to scope out the work for the PRD. | - All engineers **MUST** sign off on the approach outlined in the RFC by approving the pull request.
- The Engineering Team **MUST** be able to tell the Product Team how long the feature will take.
- The Engineering Team and Product Team **MUST** agree to any increase or decrease in scope that came from the RFC learnings.
- All changes to requirements that come from the RFC learnings **MUST** be updated in the PRD. | +| **Write & Review Code** | We write the code for the features we agreed upon in the PRD and open a Pull Request to get the other engineers' feedback. All testing at this stage is done via a preview environment. | - The engineering team **MUST** write the code for the feature, following all **Code Style Standards**.
- The engineering team **MUST** sign off on the Pull Request and follow all **Code Review Standards**.
- The engineering team **MUST** document the feature(s), following all **Documentation Standards**. | +| **User Acceptance Testing (UAT)** | The product manager who wrote the PRD tests the feature to ensure the engineering team completed all of the requirements. | - The Engineering Team **MUST** deploy the feature to staging, so the Product Manager can complete UAT.
- The Product Manager **MUST** sign off that the feature is ready to deploy to production. | +| **Launch Feature** | The engineering team deploys the feature to production, does a quick smoke test, and the product manager announces the feature to our users. | - The Engineering Team **MUST** deploy the feature to production, complete a quick smoke test, and **MUST** let the Product Team know when this is complete.
- The Product Team **MUST** announce this feature to the users. | + +## ๐Ÿ” Related Standards + +- [Code Style Standards](./code-style.md) +- [Documentation Standards](./documentation.md) +- [Code Review Standards](./code-review.md) + +## ๐Ÿ“š Additional Resources + +- [{{ team-name }} Engineering Handbook](../handbook.md) +- [Architecture Decision Records](../architecture/decisions.md) +- [Project Templates](../project/templates.md) diff --git a/templates/team/product-overview.md b/templates/team/product-overview.md index 9581000..292cdad 100644 --- a/templates/team/product-overview.md +++ b/templates/team/product-overview.md @@ -1,6 +1,6 @@ -# Team Overview -## ๐Ÿ‘ฅ Roles & Responsibilities -| **Role** | **Name** | **Timezone** | **Responsibilities** | **Ask About...** | -|----------------------|-------------|-------------|-----------------------------|-------------------------------------------| -| **Tech Lead** | [Name] | UTCโˆ’8 | Architecture, code reviews | Big technical decisions ๐Ÿ” | -| **Backend Devs** | [Name(s)] | UTCโˆ’8 | API development, database | Backend bugs ๐Ÿž | -| **Frontend Devs** | [Name(s)] | UTCโˆ’8 | UI/UX, React/Vue/etc. | Frontend issues ๐ŸŽจ | -| **DevOps** | [Name] | UTCโˆ’6 | CI/CD, infrastructure | Deployments & servers ๐Ÿš€ | -| **QA** | [Name] | UTCโˆ’6 | Testing, bug tracking | Broken features ๐Ÿ›  | +# ๐Ÿ‘ฅ {{ team-name }} Team Overview -*** +This document provides an overview of the {{ team-name }} team structure, roles, and communication channels. -## Additional Teams We Interface With +## ๐ŸŽฏ Team Structure -### **Design Team** +| Role | Name | Timezone | Responsibilities | Ask About... | +|------|------|----------|------------------|--------------| +| **Tech Lead** | {{ tech-lead-name }} | {{ timezone }} | Architecture, code reviews | Big technical decisions ๐Ÿ” | +| **Backend Devs** | {{ backend-devs }} | {{ timezone }} | API development, database | Backend bugs ๐Ÿž | +| **Frontend Devs** | {{ frontend-devs }} | {{ timezone }} | UI/UX, React/Vue/etc. | Frontend issues ๐ŸŽจ | +| **DevOps** | {{ devops-name }} | {{ timezone }} | CI/CD, infrastructure | Deployments & servers ๐Ÿš€ | +| **QA** | {{ qa-name }} | {{ timezone }} | Testing, bug tracking | Broken features ๐Ÿ›  | -* **How to Communicate**: Slack `#design-team` +## ๐Ÿค Cross-Team Collaboration -* **For Quick Help**: Tag \[Design Lead's Name] +### ๐ŸŽจ Design Team -### **Product Team** +- **Communication Channel**: Slack `#{{ team-name }}-design` +- **Primary Contact**: {{ design-lead-name }} +- **Key Responsibilities**: UI/UX design, user research, design system -* **How to Communicate**: Slack `#product-team` +### ๐Ÿ“Š Product Team -* **For Priority/Scope**: Ping \[PMโ€™s Name] +- **Communication Channel**: Slack `#{{ team-name }}-product` +- **Primary Contact**: {{ product-manager-name }} +- **Key Responsibilities**: Product roadmap, feature prioritization, user stories -*** +## ๐Ÿ’ก Support & Questions -## ๐Ÿ’ก Who to Bug with Questions? +### Getting Help -* **Unsure who to ask?** โ†’ Check Slack `#team-support` +- **General Questions**: Slack `#{{ team-name }}-support` +- **Urgent Issues**: Ping {{ tech-lead-name }} (but bring coffee โ˜•) +- **On-Call Support**: {{ oncall-schedule-link }} -* **Need something urgent?** โ†’ Ping \[Tech Leadโ€™s Name] (but bring coffee โ˜•) +### ๐Ÿ“š Resources + +- [Team Handbook](../handbook.md) +- [Architecture Overview](../architecture/overview.md) +- [Development Guidelines](../standards/development.md)