This task involves the design, development, and implementation of a new API that will translate upstream version tags/numbers to their corresponding downstream version numbers. This API is crucial for ensuring consistency, traceability, and automation across the OpenShift Virtualization project's development and release processes, particularly in light of the ongoing Konflux migration and the established downstream fork strategy

Problem Statement and Justification: OpenShift Virtualization manages its codebase across both upstream and downstream repositories

While the downstream repository aims to stay continuously in sync with upstream, it also accommodates downstream-specific changes, bug fixes (e.g., for embargoed CVEs or older Kubevirt releases), and proprietary features that are not immediately or ever introduced upstream.

This dual nature creates a complex versioning landscape where a clear, programmatic way to map upstream versions to their equivalent downstream releases is essential for various automated and manual processes.

Relevance to Konflux Migration: The migration of OpenShift Virtualization builds to the Konflux platform introduces new requirements and challenges for managing release version.

• Precise Versioning for Bundles: The hco-bundle-registry requires a "precise release version" (e.g., v4.19.0.rhel9-123) for FBC upgrade paths and accurate bundle version tagging within Konflux. This API will be vital for accurately identifying and applying these precise versions for the bundle and its components

• Midstream Code Integration: The deprecation of "midstream" code necessitates its integration, and for Kubevirt, a "downstream fork" in internal GitLab is being created.
Konflux will host the downstream-specific build processes.
This API will facilitate the coherent management of versions across these integrated systems, especially as Konflux aims to enhance software supply chain security and optimize release processes.

• Managing Multiple Components: OpenShift Virtualization applications include numerous containers per version (approximately 60).
A future Konflux feature will re-architect how components are managed to allow for hierarchical structures and better coordination of releases for applications with multiple components.
This API will support the programmatic generation and tracking of tags for these different layers, aiding in the complex automation required

Relevance to Downstream Fork Strategy: The "Downstream Sync System" automates synchronization, aiming for continuous sync of upstream content into downstream while safely handling downstream-specific changes.

• Version Synchronization: The system relies on one-to-one upstream-to-downstream branch mapping and compares HEAD SHAs to detect drift. This API will provide a higher-level mechanism to understand and manage version alignment, complementing the SHA-based drift detection by translating semantic versions or tags.

 
• Downstream-Specific Features and Fixes: Downstream-only changes, such as bug fixes for embargoed CVEs or features for older Kubevirt releases, are implemented in the downstream fork and sometimes forward-ported upstream. The API will enable developers and automation to easily identify the corresponding upstream branch/tag when working with a specific downstream release, crucial for managing forward-porting efforts and avoiding conflicts.
 
• Release Engineering Realm: The "Release Engineering Realm" represents the actual code base shipped to customers. An API that maps upstream to downstream versions will be critical for maintaining consistency and understanding which upstream version corresponds to a specific customer-shipped downstream version.
 
• Jira Workflow Integration: Downstream-specific changes are tracked via Jira, with mandatory "Fix Version" fields. This API can help ensure that the "Fix Version" in Jira accurately reflects the corresponding upstream context, improving the traceability and auditability of changes.
 
• Automation and Compliance: The downstream fork's design emphasizes automation, transparency, and compliance. This API will directly contribute to these principles by standardizing version translation, reducing manual effort, and enhancing visibility into the relationship between upstream and downstream releases.
 
Expected Functionality and Benefits:
• Provide a standardized and automated method for version translation.
• Improve accuracy and consistency of versioning in Konflux builds and releases.
• Streamline developer workflows related to upstream-downstream synchronization and forward-porting.
• Enhance traceability and auditability of code changes across repositories.
• Support automated tag generation and version management for complex, multi-component applications.
 
Dependencies and Considerations:
• Definition of clear mapping rules between upstream and downstream versioning schemes.
• Integration with existing Git repositories (GitHub, GitLab) and potentially Konflux APIs.
This API will serve as a foundational piece of infrastructure, critical for the long-term maintainability and efficiency of the OpenShift Virtualization project as it fully transitions to Konflux and matures its downstream fork strategy.