.. _omnigraph_internal_versioning:

OmniGraph Versioning And Deprecation
####################################

There are many ways in which the OmniGraph code can change from one release to another. This document sets out to
enumerate all of them and provide guidelines on how to handle each of them.

.. important::
    The overall philosophy of versioning in OmniGraph is "First do no harm". Many internal and external customers will
    be relying on many different versions of OmniGraph so it is up to us to minimize their disruption by providing
    backward compatibility for as long as possible. Breaking changes should be rare, and vital for future development.

.. _omnigraph_deprecation_approach:

Deprecation Approach
********************

On those rare occasions where it is necessary to deprecate and eventually remove existing functionality the deprecation
should always follow a safe process. This is the generic set of steps to follow for any kind of deprecation. You can
see what it should look like to the user in :ref:`omnigraph_deprecation_communication`

If there is a significant amount of code to deprecate then you should move it into a separate location for easier
removal later. External functions follow the Carbonite ABI versioning :ref:`omnigraph_versioning_carbonite`.

If an internal function call is significantly different between the two behaviors then
introduce a new version of the function and move the old implementation to a `deprecated/` subdirectory.

.. code-block:: c++
    :caption: Pre-Deprecation Version

    struct MyStruct
    {
        void mySnazzyFunction();
    };

.. code-block:: c++
    :caption: Post-Deprecation Version

    struct MyStruct
    {
        void mySnazzyFunction();

    private:
        // Deprecated functions
        void mySnazzyFunctionV1();
    };

    void MyStruct::mySnazzyFunction()
    {
        if (OmniGraphSettings::myDeprecationFlag())
        {
            mySnazzyFunctionV1();
            return;
        }
        // do the new stuff
    };

Code Notices
************

It's a good idea for the deprecation path to clearly mark all of the deprecated code paths. Here is a simple but
effective comment that can be inserted before any deprecated code.

.. code-block:: cpp

    // ==============================================================================================================
    //  _____   ______  _____   _____   ______  _____         _______  ______  _____
    // |  __ | |  ____||  __ \ |  __ \ |  ____|/ ____|    /\ |__   __||  ____||  __ |
    // | |  | || |__   | |__) || |__) || |__  | |        /  \   | |   | |__   | |  | |
    // | |  | ||  __|  |  ___/ |  _  / |  __| | |       / /\ \  | |   |  __|  | |  | |
    // | |__| || |____ | |     | | \ \ | |____| |____  / ____ \ | |   | |____ | |__| |
    // |_____/ |______||_|     |_|  \_\|______|\_____|/_/    \_\|_|   |______||_____/
    //
    // Code below here is no longer recommended for use in new code.
    //
    // ==============================================================================================================


Specific Versioning Information
*******************************

These documents illustrate versioning and deprecation information that is specific to the modification of particular
facets of OmniGraph.

.. toctree::
   :maxdepth: 1
   :glob:

   Carbonite ABIs <versioning_carbonite>
   ONI ABIs <versioning_oni>
   Existing Node Types <versioning_nodes>
   Code Behavior <versioning_behavior>
   Extension Numbering <versioning_extensions>
   Using Settings For Deprecation<versioning_settings>
   USD File Format<versioning_usd>
   Python Support<versioning_python>
   Python Deprecation<deprecation>
   Compatibility Testing<versioning_testing>
