Skip to content

Deprecation Policy

Description of Prowide policy to deprecate API and workaround for backward compatibility

Version 1.0 April 2016

Introduction

Deprecation and eventual deletion of pieces of code are an essential part of evolution. It's impossible to evolve efficiently without discarding some obsolete or non functional pieces that are naturally left behind in the process of evolving.

The main question we address with this policy is how to make this evolution process smooth to our users.

If you are facing a blocking issue with some deprecated API check the compatible mode switch below

Phases

Our deprecation policy consists of a set of phases, from a java deprecation mark for start and throwing an exception at the last phase. Each phase will last at least one year. A method may be retained in a deprecation phase for more time if required. Users are welcome to provide us feedback and comments about deprecation decisions.

Phase 1: Initial deprecation

In the initial deprecation phase elements are annotated as deprecated. Javadoc explains how to replace that code and why the deprecation occurred.

  • Period: at least 1 year
  • Source Level Compatible: Yes, source code that uses deprecated elements will still compile without modification during this phase.
  • Runtime Level Compatible: Yes, compiled artifacts that use deprecated elements will still execute without modification during this phase.

Phase 2: Warn and delay

In the second phase a log is printed each time a deprecated method is called. The log explains the replacement that should be used and any specific information related to that API. In order to make sure this log is visible a small pause is made to enable casual revisions to be alert of the situation. This delay is not compulsive and can be turned off by means of an environment variable .

  • Period: at least 2 years from deprecation mark
  • Source Level Compatible: * Yes**, source code that uses deprecated elements will still compile without modification during this phase.
  • Runtime Level Compatible: Yes, compiled artifacts that use deprecated elements will still execute without modification during this phase. However, there will be a visible impact on the runtime due to the log being printed and the pause introduced.

Phase 3: Runtime exception

In the third phase a runtime exception is thrown each time a deprecated method is called. The exception message explains the replacement that should be used and any specific information related to that API. This exception throwing can be turned off by means of an environment variable in order to enable old behavior.

  • Period: at least 3 years from deprecation mark
  • Source Level Compatible: Yes, source code that uses deprecated elements will still compile without modification during this phase.
  • Runtime Level Compatible: No, a runtime exception will be thrown each time a deprecated method is called, which can break the execution of compiled artifacts that use those elements. However, this impact can be turned off by means of an environment variable.

Phase 4: Delete

The forth phase involves deleting the deprecated API. This is done only in situations where the code cleaning is justified in order to have a more understandable API. Also note that this would be done at least 4 years after the initial deprecation mark.

  • Period: at least 4 years from deprecation mark
  • Source Level Compatible: No, deprecated elements will be deleted and will no longer be available, so source code that uses those elements will no longer compile without modification.
  • Runtime Level Compatible: No, compiled artifacts that use deprecated elements will no longer execute without modification, since those elements will have been deleted.

Compatible mode switch

Both phase 2 and phase 3 of deprecation have a visible impact on the runtime. This impact can be turned off in case of emergency, or if for some reason the code can not be adapted to the new API.

In order to bypass the deprecation and preserve the old behaviour set the environment variable:

    PW_DEPRECATED=[nolog][,nodelay][,noexception]

For convenience this can also be set directly from Java, adding the following line within your application initialization:

    DeprecationUtils.setEnv(EnvironmentVariableKey.NODELAY, EnvironmentVariableKey.NOEXCEPTION);

Definitions

Compatibility is a wide concept, so we'll refine it here:

  • Source Level Compatibility (SLC): means that our software may be upgraded without modification of existing source code that uses it. Note that source level compatibility does not exempt from recompilation, and that's why we also specify the next level of compatibility, which includes this.

  • Runtime Level Compatibility (RLC): means that our software may be upgraded by just replacing the artifacts in a runtime environment without need for recompilation. For example:

    void setFoo(String) Foo setFoo(String)

L1 and L2 are SLC but not RLC.

For this type of changes we'll add, if necessary, the practice of creating a new package and using the newer version classes from the new package. For the old classes/packages, we handle what we believe is very important for long term software, a clear deprecation/deletion policy.