Mark OTOBO code as deprecated

[stefanhaerter]

Requirement

Being able to mark OTOBO code as deprecated

Findings so far

We seemingly need to make a difference between marking subroutines as deprecated and marking whole modules as deprecated. So far, my impression is that every approach boils down to issuing a warning when the code is called.

It needs to be discussed what the scope of marking OTOBO code as deprecated actually is. Issuing a warning would manly affect users of OTOBO. If the goal is to remind developers of deprecated code, the mechanism needs to be a different one.

Nonetheless, I will include the common approaches briefly:

• perldoc warnings includes the following code example, making use of the standardized warnings category 'deprecated':

  package MyMod::Abc;
  
  sub open2 {
      if (warnings::enabled("deprecated")) {
          warnings::warn("deprecated",
                         "open2 is deprecated, use open instead");
      }
      open(@_);
  }
  
  sub open
  ...
  1;

• for simplifying this, there is the cpan module Attribute::Deprecated
• according to this stackoverflow post, the preferred mechanism for marking a module as deprecated is:

  If you are deprecating a whole module, put the warning in a BEGIN block in the module.

[bschmalhofer]

Another issue is to have a document that lists the deprecations. In the best of worls this would include the date or version when the feature is removed. See #1204.

[stefanhaerter]

This is a solution which, in my subjective opinion, would be a proper approach to target the developers. But my feeling is that the hypothetical list should be wired to the CodePolicy, git hooks or GitHub actions in some way to actually have an impact.

[stefanhaerter]

A list would also (presumably) provide the advantage that it could be used not only for perl code, but for javascript and perhaps other languages as well.

[stefanhaerter]

According to https://en.wikipedia.org/wiki/JSDoc, the standardized way to mark javascript methods as deprecated is to add the @deprecated annotation to the doc. Another possibility is to include a console log warning saying that the method is deprecated, but in my personal opinion, the first way would be preferred as it seems to be more standardized.