2. Standards: Single Source of Truth ‐ HAL Interfaces and Testing Suites - rdkcentral/ut-core GitHub Wiki

Introduction

This document details our transition to a centralized, transparent approach for managing HAL interfaces and testing suites. This change aims to enhance development, boost collaboration, and resolve past issues with fragmented repositories and outdated practices.

Challenges of the Previous System

Our previous development landscape faced several challenges:

  • Fragmented repositories: Interfaces and testing suites were scattered across different locations, making access and collaboration difficult.
  • Outdated version control: Manual syncing and inconsistent branching led to discrepancies and errors.
  • Limited accessibility: Vendors and third parties lacked proper access to essential resources.
  • Multiple code locations: Internal, collaboration, and final code locations caused confusion and maintenance overhead.
  • Rewritten commit histories: Login credential changes forced commit history rewrites, obscuring development history.

Introducing the Single Source of Truth Approach

To address the challenges of scattered documentation and inconsistent information, we're adopting a single source of truth model.

This means:

  • Centralised repository: All interfaces, testing suites, and documentation will be housed in a central repository, either publicly or privately on rdkcentral.
  • High-Quality Documentation: We are committed to providing comprehensive, up-to-date documentation, including:
    • Conceptual documentation: Explaining the architecture, design principles, and key concepts.
    • API Documentation with Doxygen: Detailed API references generated with Doxygen, ensuring accuracy and consistency.
    • Tutorials and Examples: Practical guides and examples to help developers get started quickly.
  • Transparent access: Vendors and third parties will have clear, consistent access to all resources, including all documentation.
  • Semantic versioning: We'll use semantic versioning to ensure compatibility between old and new interfaces and keep documentation aligned with each version.
  • Fixed version usage: Components will use fixed interface versions for stability, referencing the corresponding documentation version.
  • Upgraded interfaces and testing suites: We'll upgrade the interfaces and the testing suites in the open, with documentation updated simultaneously.

Benefits of the New System

This new system provides numerous benefits:

  • Simplified development process: Clear visibility and access to resources, including easy-to-find documentation, streamline workflows.
  • Enhanced collaboration: Shared knowledge and resources, along with a common understanding fostered by consistent documentation, improve collaboration.
  • Reduced errors and inconsistencies: A single reference point for code and documentation minimises discrepancies and errors.
  • Improved efficiency and time savings: Streamlined workflows and readily available documentation increase efficiency and save time.
  • Increased transparency and trust: Open access to information, including all documentation for all parties, fosters trust and transparency.
  • Improved developer experience: High-quality documentation makes it easier for developers to understand, use, and integrate with our platform.
  • Reduced support costs: Clear and comprehensive documentation reduces the need for support requests.

Conclusion

This transition to a single source of truth is a significant advancement in HAL interface development. We're dedicated to continuous improvement and welcome participation and feedback from all stakeholders. Through open communication and collaboration, we can ensure the success of this initiative and provide an enhanced development experience for everyone.