Lifecycle of workarounds

[atamazov]

Motivation

Usually we use workarounds when external components have issues that affect the library. As a rule, such issues begin with some version of the external component, and fixed in one of the subsequent versions.

The library, in turn, is also evolving. During this process, old versions of external components become a bottleneck, and we find ourselves forced to dismiss support of these old versions.

One typical example of such external components is the HIP compiler. A bug appears in some version, then in some other version it is fixed, then at some point in time the old version of the compiler is no longer supported by the library.

These three points should be reflected in the workaround life cycle. Ironically, the main objective of the life cycle is the end of life of the workaround, i.e. cleanup the workarounds that have become unnecessary.

Similar considerations apply to cases where the source of the issue is in the library, or is unknown. To resolve an issue quickly, we can apply workaround. This gives us the time needed for detailed research and / or making complete fix.

Guidelines

• (10) Introducing the workaround
  • (10.10) Define some symbolic entity of the form ...WORKAROUND_<reference-to-the-issue>.... Consistently use it across the source code.
    • Use ..._ISSUE_XXX in the macro name to refer to the public repo (preferred).
    • Use ..._MLOPEN_ISSUE_XXX to refer to the private repo.
    • Use ..._SWDEV_XXX to denote Jura issue.
    • Example for C/C++: macro definition like #define WORKAROUND_ISSUE_2331 1.
  • (10.20) Mixing several issues in the single symbol, e.g. WORKAROUND_ISSUE_2174_2222_2224_2243, is not allowed. This situation means either duplicate issues or different issues that can be resolved by identical workaround.
    • Duplicates shall be resolved within bug tracking system, so only one is left open.
    • Otherwise we shall use the boolean logic, like #if WORKAROUND_ISSUE_2174 || WORKAROUND_ISSUE_2222 || WORKAROUND_ISSUE_2224 for C/C++.
  • (10.30) Check previous version of the external component.
    • If the previous version is free of this issue, then use version detection machinery and switch the workaround off for previous and older versions.
      • This may require the development of the version detection machinery for the component, if we do not have it already.
    • Otherwise keep workaround enabled unconditionally.
• (20) Disable the workaround after the fix.
  • This needs to be done as soon as the issue in the external component is fixed, even prior the official release of it.
  • Use version detection (see 10.30 above) and disable workaround for the fixed-version and newer versions.
• (30) End of life - dismiss W/A and clean up code.
  • This should happen when we dismiss support for the older versions of the component, including all versions prior to the fixed-version.