[RFC] `torch_xla` Backward Compatibility Proposal

[zpcore]

Recently, we have started the process to reduce the torch_xla API footprint in favor of torch API to improve the usability. This RFC focuses on the process to deprecate any functions.

Backward compatibility

We propose to offer a 6 months (2 releases) grace period before completely removing the deprecated API. As is shown in the graph below:

Developers should follow the illustrated timeline with the following action:

• Before version X-1 branch cut, developers check in API changes and wrap the function to be deprecated with the warning message. The API to be deprecated should still be usable but it should print out the warning message once if any code is calling into the function. In this way, starting from version X and version X+1, we should see the deprecated message that mentions API xxx will be deprecated in release X+2.
• Before version X+2 branch cut, developers completely delete the deprecated functions along with the warning deprecated message.

If we follow the timeline, the deprecated API should still be usable for two releases, in which we guarantee backward compatibility.

For each deprecated API, mention it in the release X’s release note including what’s the suggested new APIs and when to completely deprecate the old one.

Actions to take for deprecation:

Github actions for API deprecation

Before deprecate any APIs, create a github issue to include the following details:

• Function to be deprecated and whether we have a new API as a replacement.
• Proposed timeline before completely deprecating the function. We need to guarantee the deprecated message lasts for at least 2 releases.

  How to mark function to be deprecated

  Here is the example on the code changes if we want to deprecate torch_xla/core/xla_model.py:xrt_world_size() with torch_xla/runtime.py:world_size(). There are two ways to mark a function as deprecated:

• Use deprecated function (full example PR):

  
  # In torch_xla/core/xla_model.py:
  from torch_xla.experimental.deprecation import deprecated
  from . import xla_model as this_module
  xrt_world_size = deprecated(this_module, torch_xla.runtime.world_size,
                          'xrt_world_size() will be removed in release 2.7.')
  # Remember to comment out or remove the original xrt_world_size in the file.
  """
  def xrt_world_size():
  ...
  """

In torch_xla/runtime.py

def world_size(): ...

- Use @mark_deprecated decorator:
```python
# In torch_xla/core/xla_model.py:
from torch_xla.experimental.deprecation import mark_deprecated

@mark_deprecated(torch_xla.runtime.world_size, extra_msg='xrt_world_size() will be removed in release 2.7.')
def xrt_world_size():
  ...

# In torch_xla/[runtime.py](http://runtime.py/), define the new function:
def world_size():
  ...

[zpcore]

@miladm @ManfeiBai @JackCaoG

[ManfeiBai]

Thanks, LGTM, let's add in 2.5 release

[miladm]

Can we pin this issue to the top of the issue list on GH? @zpcore

[zpcore]

Can we pin this issue to the top of the issue list on GH? @zpcore

Issue pinned now.