Skip to content

2.3. Standards: Performing Changes to an interface

Jump to bottom
Ulrond edited this page Nov 12, 2024 · 3 revisions

Scope

This document outlines the procedures for making changes to the interface.

Please also refer to the 2. Standards: Single Source of Truth - HAL Interfaces and Testing Suites document.

Executive Summary

Modifying the interface is a controlled process requiring collaboration, approval, and meticulous documentation. All changes must be proposed and tracked through GitHub issues, reviewed by the component owner and architecture team, and validated with updated testing suites. This ensures alignment with architectural standards, maintains interface consistency, and preserves backward compatibility.

Introduction

Modifications to the interface should generally be avoided unless approved by the design and architecture teams. Pre-approved design changes are required before starting work, with final authorization granted upon completion.

Architecture Discussions

  • Create an issue ticket in github on the goals & requirements that need to be met with clear requirements
  • Discuss any proposed code changes with the architecture team to ensure alignment with current and future needs.
  • Document in the issue ticket,
  • Maintain interface consistency across all components, as design decisions impact the entire interface, not just individual parts.

Change Process

Any interface modification involves the following steps, managed through GitHub:

  1. Define and Discuss:

    • Raise an issue ticket in GitHub to outline the goals and proposed changes to the interface. Clearly define the requirements and reasons for the modification.
    • Discuss the proposed changes with the component owner and the architecture team within the issue ticket. This ensures alignment with current and future architectural needs and maintains interface consistency across all components.

  2. Develop and Document:

    • Create a branch from develop based on the issue ticket ID (e.g., issue-123-interface-update).
    • In this branch, implement the interface changes and update the corresponding documentation. Ensure the documentation accurately reflects the modified functionality.

  3. Review and Approve:

    • Raise a Pull Request (PR) for the changes in your branch.
    • Request review and sign-off from the component owner and the architecture team. Address any feedback or concerns raised during the review process.
    • Once approved, merge the PR into develop.

  4. Update Testing Suite:

    • Raise a separate issue ticket for any required changes or upgrades to the testing suite due to the interface modification. Define the new testing requirements within this ticket.
    • Create a new branch (e.g., issue-124-testing-update) for modifying the testing suite.
    • Implement the testing suite changes to validate the updated interface functionality.
    • Raise a PR for the testing suite changes. Request review and sign-off from the architecture team and code owners.
    • Merge the PR into develop after approval.

  5. Release:

The component owner manages the release of the updated interface and testing suite, adhering to the following guidelines:

  • Release Cadence: Releases follow a defined cadence methodology to ensure regular updates.
  • Semantic Versioning: Both the header file and testing suite utilize semantic versioning (MAJOR.MINOR.BUGFIX) to indicate the nature of changes.
    • Major interface changes require a major version bump in both the header file and the testing suite.
    • Minor, binary-compatible interface changes result in a minor version bump for both.
    • Bugfix, either in the testing suites or the header file, will have no effect on the binary
  • Version Alignment: The testing suite version is aligned with the header file version to ensure compatibility.
  • Automated Upgrades: Consideration should be given to how the testing suite can automatically upgrade to accommodate minor interface changes, potentially through mechanisms provided by HALIF.
  1. Vendor Integration:
    • Communicate the interface changes to vendors. Vendors must adjust their code and ensure compliance with the updated testing suite.

Important Notes:

  • Peer review will automatically fail if the GitHub process outlined above is not followed.
  • Maintain backward compatibility with existing code whenever possible.
  • Clearly document all changes and justifications within the relevant GitHub issues and PRs.

Testing

  • All code must undergo manual testing before commitment.
  • Engineering teams must perform iterative testing for validation and approval before merging changes.
  • Code merges are gated by successful tests.

Requirements

  • Changes must maintain backward compatibility.
  • All modifications should be controlled and documented meticulously.
  • Legacy platforms may run older interface versions.
  • Future changes will be managed through dynamic discovery.

When functions or structures are updated, but the interface is deemed insufficient, upgrades are allowed but must be marked with a comment:

/* TODO: This <functionality/structure/etc> is deprecated, and future modifications will require a redesign. */

Conclusion

Interface stability should be maintained across all platforms and versions. The architecture team has sole authority over change decisions, and any modifications require design approval and final sign-off.

Clone this wiki locally