Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
458 lines (342 loc) · 16.8 KB

CONTRIBUTING.md

File metadata and controls

458 lines (342 loc) · 16.8 KB

DORA Core Model: Development Guidelines

This document provides guidelines for contributors based on the DORA (DevOps Research and Assessment) Core Model, focusing specifically on the aspects that affect development practices.

Table of Contents

Technical Capabilities

Version Control

Guidelines:

  • Feature Branching: Use short-lived feature branches named according to the format [language]-[feature]
  • Commit Messages: Follow the Conventional Commits standard: 
    feat: add lamp on/off toggle endpoint to TypeScript REST API
fix: resolve MongoDB connection issue in Go implementation
docs: update API documentation for Python GraphQL interface
test: add integration tests for Kotlin gRPC service
refactor: improve Java repository pattern implementation
  • Pull Requests: Create focused PRs that implement a single feature or fix
  • Code Review: All code must be reviewed by at least one other contributor

Implementation in this project:

Each language implementation should follow the same Git workflow:

  1. Create a branch for your specific implementation task
  2. Commit frequently with clear, conventional commit messages
  3. Push your branch daily to enable early feedback
  4. Create a PR when the implementation meets acceptance criteria

Continuous Integration

Guidelines:

  • Automated Testing: All PRs must pass automated tests before merging
  • Linting: Code style must be verified automatically using language-appropriate linters
  • Static Analysis: Implement static code analysis to catch potential issues early
  • CI Pipeline: Each implementation should have a CI pipeline that runs:
    • Unit tests
    • Integration tests
    • Linting and static analysis
    • Code coverage reports

Implementation in this project:

  • Configure GitHub Actions workflows for each language implementation
  • Standardize CI pipeline steps across all languages where possible
  • Generate code quality and test coverage badges for each implementation
  • Establish quality gates that block merging if standards aren't met

Local Pre-commit Hooks

To catch formatting and lint issues before push/PR, this repository uses a local pre-commit setup aligned with CI quality checks.

One-time setup:

pre-commit install

Run manually for all files:

pre-commit run --all-files

Behavior:

  • Hooks are triggered only for staged files in affected language/database paths; some toolchains run project-wide checks once triggered.
  • Hooks apply auto-fixes when possible.
  • If files are auto-fixed, they are re-staged and the commit is blocked once so you can review and re-run commit.
  • If lint/static-analysis issues remain, commit is blocked with actionable output.

Important:

  • Local pre-commit hooks are fast-fail guardrails, not a replacement for CI.
  • CI workflows remain the source of truth for merge gating.

Troubleshooting:

  • Ensure language toolchains are installed for touched paths (npm, poetry, go, mvn, dotnet, gradle, sqlfluff).
  • If a hook fails after auto-fix, inspect staged changes and run commit again.
  • Use pre-commit run --all-files to reproduce full local checks.

Test Automation

Guidelines:

  • Test Pyramid: Follow the test pyramid approach:
    • Many unit tests
    • Some integration tests
    • Few end-to-end tests
  • Test Coverage: Maintain minimum 80% code coverage for all implementations
  • Test Quality: Focus on behavior-based testing rather than implementation details
  • Testing Standards: Include tests for:
    • Happy paths
    • Error cases
    • Edge cases
    • Performance requirements

Implementation in this project:

For each language implementation:

  1. Write unit tests for all business logic and service layers
  2. Create integration tests for each API interface
  3. Implement database integration tests
  4. Generate standardized coverage reports
  5. Include performance tests where appropriate

Trunk-Based Development

Guidelines:

  • Small Increments: Work in small, incremental changes
  • Frequent Integration: Integrate changes to the main branch at least daily
  • Feature Flags: Use feature flags for partially completed work (if necessary)
  • Branch Lifetime: Keep feature branches short-lived (1-2 days max)

Implementation in this project:

  1. Break down language implementations into small, focused tasks
  2. Integrate code into main frequently, even if features aren't complete
  3. Use incremental approach to implementing each API interface
  4. Prioritize working code over complete features

Code Maintainability

Guidelines:

  • Clean Code: Follow language-specific clean code practices
  • Code Complexity: Keep cyclomatic complexity low (aim for < 10)
  • Design Patterns: Use appropriate design patterns consistently
  • Technical Debt: Address technical debt as part of regular work
  • Refactoring: Continuously refactor to improve code quality

Implementation in this project:

  1. Establish code style guides for each language
  2. Configure automated tools to check for code quality
  3. Follow SOLID principles across all implementations
  4. Implement consistent architectural patterns across languages
  5. Document architectural decisions

Deployment Automation

Guidelines:

  • Environment Configuration: All environment configuration should be in code
  • Infrastructure as Code: Define development infrastructure in code
  • Containerization: Use containers for consistent environments
  • Dependency Management: Automate dependency updates

Implementation in this project:

  1. Use Docker for all database and service dependencies
  2. Maintain Docker Compose configurations for local development
  3. Include clear deployment instructions for each implementation
  4. Automate dependency updates with tools like Dependabot

Cultural Capabilities

Team Experimentation

Guidelines:

  • Learning Culture: Encourage learning and experimentation
  • Innovation Time: Allocate time for exploring novel approaches
  • Knowledge Sharing: Share learnings across language implementations
  • Cross-pollination: Borrow successful patterns across languages

Implementation in this project:

  1. Document insights and learnings from each language implementation
  2. Hold regular knowledge-sharing sessions
  3. Experiment with different approaches within language constraints
  4. Maintain a "lessons learned" document for each implementation

Documentation

Guidelines:

  • Documentation as Code: Maintain documentation alongside code
  • Comprehensive READMEs: Each implementation should have detailed READMEs
  • API Documentation: Keep API documentation up-to-date
  • Architecture Documentation: Document architectural decisions
  • Onboarding Guides: Make it easy for new contributors to get started

Implementation in this project:

  1. Create a standardized README template for all implementations
  2. Maintain up-to-date API documentation for all interfaces
  3. Document language-specific considerations and patterns
  4. Create diagrams for architecture and data flow
  5. Include example usage for each API interface

Working in Small Batches

Guidelines:

  • Small User Stories: Break work into small, deliverable chunks
  • MVP Approach: Implement minimum viable solutions first, then enhance
  • Iterative Development: Build features iteratively
  • Regular Feedback: Seek feedback frequently

Implementation in this project:

  1. Implement basic CRUD functionality first in each language
  2. Add one API interface at a time (REST → GraphQL → gRPC)
  3. Implement one database adapter first, then add others
  4. Break implementation tasks into small GitHub issues
  5. Seek early feedback on architectural approaches

Psychological Safety

Guidelines:

  • Blameless Culture: Focus on learning, not blaming
  • Open Communication: Encourage discussion of challenges
  • Constructive Feedback: Provide specific, actionable code review feedback
  • Recognition: Acknowledge good work and innovative solutions
  • Inclusive Environment: Welcome contributions from all skill levels

Implementation in this project:

  1. Establish code review guidelines focused on learning
  2. Encourage sharing of challenges and roadblocks
  3. Recognize contributions in project documentation
  4. Maintain a helpful, constructive tone in all communications
  5. Provide mentorship for less experienced contributors

Data Modeling and Analytics

Data Architecture

Guidelines:

  • Scalable Design: Design data models with future growth in mind
  • Dimensional Modeling: Use dimensional modeling concepts even in operational databases
  • Source of Truth: Define clear sources of truth for all data elements
  • Data Lineage: Track the origin and transformations of data
  • Access Patterns: Design for expected query patterns and analytics use cases

Implementation in this project:

  1. Define a consistent ID generation strategy across all implementations
  2. Implement timestamp fields for all entities (created_at, updated_at)
  3. Track data provenance for all operations
  4. Document data flow between system components
  5. Design for future extension with minimal schema changes

Schema Design

Guidelines:

  • Forward Compatibility: Design schemas to accommodate future changes
  • Naming Conventions: Use consistent, descriptive naming conventions
  • Field Types: Choose appropriate data types that preserve information
  • Indexing Strategy: Define indexes based on query patterns and analytics needs
  • Denormalization: Strategically denormalize where it benefits analytics

Implementation in this project:

  1. Use UUID/GUID for all primary keys
  2. Implement consistent timestamp formats with timezone information
  3. Include soft delete capabilities (is_deleted flag, deleted_at timestamp)
  4. Design consistent JSON structures for any semi-structured data
  5. Document indexing strategy for each database technology

Data Integration Patterns

Guidelines:

  • Change Data Capture: Design for easy extraction of changed records
  • ETL Friendliness: Make database designs amenable to ETL/ELT processes
  • API Data Consistency: Ensure consistent data representation across API interfaces
  • Bulk Operations: Support efficient bulk operations for data migrations
  • Idempotency: Design operations to be safely repeatable

Implementation in this project:

  1. Implement a logical timestamp or version number for each record
  2. Design database triggers or change streams for change tracking
  3. Ensure consistent data serialization formats across all interfaces
  4. Include bulk import/export endpoints in the API
  5. Document data integration patterns for each implementation

Event Tracking

Guidelines:

  • Event-Based Logging: Log business events, not just technical operations
  • Event Schema: Define consistent event schemas across implementations
  • Audit Trail: Maintain comprehensive audit trails for all operations
  • Event Sourcing: Consider event sourcing patterns for critical operations
  • Correlation IDs: Track related operations with correlation identifiers

Implementation in this project:

  1. Define a standard event schema (actor, action, entity, timestamp, context)
  2. Log all lamp state changes as business events
  3. Include correlation IDs in all operations that span multiple requests
  4. Design for future event replay capabilities
  5. Implement consistent logging patterns across all languages

Analytics Readiness

Guidelines:

  • Metrics Definition: Define key business metrics in code
  • Aggregation Design: Design data structures that facilitate aggregation
  • Time-Based Analysis: Support time-series analysis with proper timestamp handling
  • Data Export: Provide mechanisms to export data for external analysis
  • Analytics Metadata: Include metadata that supports analytics contexts

Implementation in this project:

  1. Track key metrics for lamp operations (creation rate, toggle frequency)
  2. Implement time-partitioned storage where appropriate
  3. Design query interfaces that support common analytics patterns
  4. Include data export functionality in all implementations
  5. Document recommended analytics approaches for each database technology

Observability

  1. Logging

    • Use structured logging
    • Include correlation IDs
    • Log all business events
    • Add proper log levels
    • Include contextual information

  2. Error Monitoring

    • Implement error boundaries
    • Track error rates and types
    • Set up error alerting
    • Include error context and stack traces
    • Monitor error trends
    • Implement retry mechanisms
    • Define error severity levels
    • Document error handling procedures

  3. Application Monitoring

    • Track key business metrics
    • Monitor system health
    • Implement custom dashboards
    • Set up alerting thresholds
    • Track performance metrics
    • Monitor resource usage
    • Implement distributed tracing
    • Track user behavior analytics

Inversion of Control

  1. Dependency Injection

    • Use constructor injection by default
    • Avoid service locator pattern
    • Configure DI container at composition root
    • Document dependencies clearly
    • Use interfaces for abstractions

  2. Interface Design

    • Define clear contracts
    • Use dependency inversion principle
    • Keep interfaces focused and cohesive
    • Document interface behaviors
    • Version interfaces appropriately

  3. Testing Considerations

    • Design for testability
    • Use mocks and stubs effectively
    • Test with different implementations
    • Document testing patterns
    • Validate interface contracts

  4. Configuration Management

    • Externalize configuration
    • Use environment variables
    • Implement feature flags
    • Support different environments
    • Document configuration options

Error Handling

  1. Error Types

    • Define domain-specific errors
    • Use error hierarchies
    • Include error codes
    • Provide error messages
    • Document error scenarios

  2. Error Recovery

    • Implement graceful degradation
    • Define recovery strategies
    • Handle transient failures
    • Document recovery procedures
    • Test error scenarios

  3. Error Reporting

    • Capture error context
    • Track error frequency
    • Monitor error patterns
    • Alert on critical errors
    • Analyze error impact

  4. User Experience

    • Provide clear error messages
    • Implement fallback behavior
    • Guide users through recovery
    • Log user-facing errors
    • Track error resolution

DORA Metrics to Track

While implementing these guidelines, track the following DORA metrics to measure their effectiveness:

  1. Deployment Frequency: How often code is successfully merged to main
  2. Lead Time for Changes: Time from code commit to successful PR merge
  3. Change Failure Rate: Percentage of PRs that fail CI or need rework
  4. Mean Time to Recovery: Time to fix failed builds or tests

Additionally, track these data quality metrics:

  1. Schema Consistency: Consistency of data structures across implementations
  2. Data Completeness: Percentage of records with all required fields
  3. Query Performance: Response time for standard analytical queries
  4. Integration Success Rate: Success rate of data extraction processes

Conclusion

By following these guidelines based on the DORA Core Model and data modeling best practices, we can ensure that all language implementations in the project maintain consistent quality, follow best practices, and provide an excellent foundation for comparing different approaches.

These guidelines also ensure that the data models and operations are designed with future data warehouse integration and analytics in mind, making the system not just operationally sound but also analytically valuable.

Contributors should refer to this document when implementing features, reviewing code, and providing feedback to ensure alignment with project goals and industry best practices.