<!-- Due to indented blocks for lists within admonition blocks --> <!-- markdownlint-disable MD046 -->

Development Standards

Git Workflow, Code Quality, and CI/CD Excellence

What's Covered: Git workflows, code quality gates, CI/CD pipelines, and style standards

---

Git Workflow Standards

GitHub Flow Implementation

We follow the GitHub Flow branching strategy for all repositories:

gitgraph
    commit id: "Initial"
    branch feature/epic-integration
    checkout feature/epic-integration
    commit id: "Add Epic APIs"
    commit id: "Update docs"
    checkout main
    merge feature/epic-integration
    commit id: "Deploy v1.2.0"

Branch Naming Conventions

Commit Message Standards

Follow Conventional Commits specification:

# Format: type(scope): description
feat(auth): add SAML authentication for Epic users
fix(api): resolve timeout issues in patient data sync
docs(readme): update installation instructions
refactor(database): optimize Epic EMR query performance
chore(vault): rotate database credentials

!!! example "Allowed commit types" Only these canonical Conventional Commits types are permitted by the org ruleset:

- `feat` — new features
- `fix` — bug fixes
- `docs` — documentation changes
- `style` — formatting/whitespace, no behavior change
- `refactor` — code improvements with no behavior change
- `perf` — performance improvements
- `test` — adding or updating tests
- `build` — build system or dependency changes
- `ci` — CI/CD pipeline changes
- `chore` — maintenance, including security rotations and dependency bumps
- `revert` — reverting a prior commit

Invented prefixes such as `security:`, `bug:`, `epic:`, `update:`, or `add:` are rejected. Security-flavored work uses `chore(security)` or `fix(security)`.

---

Code Quality Standards

Pre-Pull Request Checklist

Pull Request Requirements

Code Review Standards

What Reviewers Look For:

Review Process:

1. Automated Checks: CI/CD pipeline validation
2. Peer Review: at least one team member approval (verify the target repo's branch protection — counts vary across repos in the org; the megadoc repo requires 1)
3. Security Review: For sensitive changes
4. Architecture Review: For significant design changes

---

CI/CD Pipeline Standards

GitHub Actions Security

Authentication Best Practices:

# Good: OIDC with Vault. Pin to the current major; verify the URL,
# auth mount, and role against your team's Vault namespace.
- name: Get secrets from Vault
  uses: hashicorp/vault-action@v3
  with:
    url: https://vault.uhg.com
    method: jwt
    role: epic-azure-deployment
    secrets: |
      secret/epic/azure subscription_id | AZURE_SUBSCRIPTION_ID
      secret/epic/azure client_id | AZURE_CLIENT_ID

# Never: Secrets in repository
- name: Deploy
  run: echo "password123" | deploy-script
```

Branch Protection Rules

Deployment Validation Pipeline

!!! example "Required Pipeline Stages" 1. Security Scanning - No critical vulnerabilities 2. Code Quality - Linting and static analysis 3. Automated Testing - Unit, integration, and E2E tests 4. Infrastructure Validation - Terraform plan review 5. Policy Compliance - Organizational policy checks 6. Performance Testing - Load and stress testing 7. Smoke Testing - Basic functionality verification

Pipeline Example:

name: Epic Azure Deployment Pipeline

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
      - name: Run TruffleHog secret scanner
        uses: trufflesecurity/trufflehog@main

  code-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run linting
        run: |
          pylint src/
          terraform fmt -check
      - name: Run static analysis
        run: |
          bandit -r src/
          checkov -d terraform/

  test:
    runs-on: ubuntu-latest
    needs: [security-scan, code-quality]
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: |
          python -m pytest tests/ --cov=src --cov-report=xml
          terraform validate

  deploy:
    runs-on: ubuntu-latest
    needs: [test]
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to Azure
        run: |
          terraform plan
          terraform apply -auto-approve

---

Code Style & Standards

File Organization Standards

Repository Structure:

epic-infrastructure/
├── .github/                 # GitHub workflows and templates
│   ├── workflows/          # CI/CD pipelines
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── ISSUE_TEMPLATE/
├── docs/                   # Documentation
│   ├── README.md
│   ├── architecture/
│   └── runbooks/
├── src/                    # Source code
│   ├── main/
│   ├── test/
│   └── resources/
├── terraform/              # Infrastructure as Code
│   ├── modules/
│   ├── environments/
│   └── policies/
├── ansible/                # Configuration management
│   ├── playbooks/
│   ├── roles/
│   └── inventory/
├── scripts/                # Utility scripts
├── tests/                  # Test suites
├── .pre-commit-config.yaml # Pre-commit hooks
├── requirements.txt        # Dependencies
└── pyproject.toml         # Project configuration

Naming Conventions

**Variables and Functions:**
- **Terraform:** `snake_case` for variables and resources
- **Ansible:** `snake_case` for variables and tasks
- **Python:** `snake_case` for functions and variables
- **JavaScript:** `camelCase` for functions and variables

**Azure Resources:**
- **Format:** `{environment}-{application}-{component}-{instance}`
- **Example:** `prod-epic-app-001`, `dev-epic-db-01`

Documentation Requirements

!!! example "README Standards" Every repository must include:

```markdown
# Project Title
Brief description of the project and its purpose.

## Prerequisites
- List required tools and versions
- Access requirements
- Dependencies

## Installation
Step-by-step installation instructions

## Usage
Common use cases and examples

## Configuration
Environment variables and configuration options

## Testing
How to run tests locally

## Contributing
Link to contributing guidelines

## Support
How to get help and contact information
```

Code Comments Standards:

# Python example
def deploy_epic_application(environment: str, version: str) -> bool:
    """
    Deploy Epic application to specified environment.

    Args:
        environment: Target environment (dev, staging, prod)
        version: Application version to deploy

    Returns:
        True if deployment successful, False otherwise

    Raises:
        DeploymentError: If deployment fails
    """
    # Validate environment parameter
    if environment not in ['dev', 'staging', 'prod']:
        raise ValueError(f"Invalid environment: {environment}")

    # Deploy application using Azure CLI
    return azure_deploy(environment, version)

# Terraform example. Use the OS-specific resource
# (azurerm_linux_virtual_machine / azurerm_windows_virtual_machine);
# the legacy azurerm_virtual_machine is deprecated.
resource "azurerm_linux_virtual_machine" "epic_app" {
  # VM configured for Epic application workload
  # Size selected based on Epic performance requirements
  name                = "${var.environment}-epic-app-${var.instance_id}"
  location            = var.location
  resource_group_name = var.resource_group_name
  size                = var.epic_vm_size # Standard_D8s_v3 recommended

  # Network configuration for Epic application subnet
  network_interface_ids = [azurerm_network_interface.epic_app.id]

  admin_username = var.admin_username

  # OS disk configuration with platform-managed encryption
  os_disk {
    name                 = "${var.environment}-epic-app-osdisk-${var.instance_id}"
    caching              = "ReadWrite"
    storage_account_type = "Premium_LRS"
  }

  source_image_reference {
    publisher = var.image_publisher
    offer     = var.image_offer
    sku       = var.image_sku
    version   = var.image_version
  }

  # Tags for cost allocation and resource management
  tags = merge(var.common_tags, {
    Environment = var.environment
    Application = "Epic"
    Component   = "ApplicationServer"
    Owner       = var.team_name
  })
}

---

Release Management

Release Planning

**Hotfix Releases:**
- [ ] Critical issue resolved
- [ ] Minimal scope of changes
- [ ] Emergency approval obtained
- [ ] Production validation plan ready

Version Management

Semantic Versioning (SemVer):

• MAJOR: Breaking changes that require coordination
• MINOR: New features that are backwards compatible
• PATCH: Bug fixes and security patches

Examples:

• v2.1.0 → v2.1.1 (bug fix)
• v2.1.1 → v2.2.0 (new feature)
• v2.2.0 → v3.0.0 (breaking change)

Deployment Strategies

**Canary Deployment:**
- Gradual rollout to subset of users
- Risk mitigation through monitoring
- Automatic rollback on issues

**Feature Flags:**
- Runtime feature toggling
- A/B testing capabilities
- Gradual feature enablement

---

Quality Assurance

Testing Strategy

!!! example "Testing Pyramid" Unit Tests (70%): - Fast, isolated, comprehensive - Test individual functions/methods - Mock external dependencies

**Integration Tests (20%):**
- Test component interactions
- Database and API integrations
- End-to-end workflows

**E2E Tests (10%):**
- Full system validation
- User journey testing
- Performance validation

Performance Standards

**Infrastructure:**
- **Deployment Time:** <30 minutes end-to-end
- **Recovery Time:** <15 minutes for rollback
- **Availability:** 99.95% uptime SLA

Monitoring and Alerting

Development Metrics:

• Build Success Rate: >98%
• Test Pass Rate: 100% for deployments
• Code Coverage: >80% for new code
• Security Scan Pass Rate: 100%

Operational Metrics:

• Deployment Frequency: Daily deployments capability
• Lead Time: <4 hours from commit to production
• Mean Time to Recovery: <30 minutes
• Change Failure Rate: <5%

---

Continuous Improvement

Code Quality Metrics

**Dynamic Analysis:**
- Runtime performance monitoring
- Memory leak detection
- Security penetration testing
- Load testing validation

Team Practices

Regular Reviews:

• Weekly Code Quality Review: Metrics and trends analysis
• Monthly Process Retrospective: Workflow improvements
• Quarterly Architecture Review: Technical debt and design evolution

Knowledge Sharing:

• Tech Talks: Share learnings and best practices
• Pair Programming: Knowledge transfer and quality improvement
• Code Walkthroughs: Complex feature explanations
• Documentation Days: Focus on improving team documentation

---

Getting Help with Development

!!! question "Development Questions" - Git Workflow Issues: Check GitHub Workflow Guide - Code Review Questions: Ask in #epic-azure-engineering - CI/CD Pipeline Problems: Create GitHub issue with logs - Style Guide Clarifications: Refer to language-specific guidelines

!!! question "Tool-Specific Help" - GitHub Actions: Official Documentation - Pre-commit Hooks: Pre-commit Framework - Conventional Commits: Specification - Semantic Versioning: SemVer Guide

---

Development Standards | Epic on Azure Team Guidelines

These standards evolve with our practices and technology stack. Contribute improvements through pull requests and team discussions.

Last updated: September 2025