Should we keep deprecation messages as short as possible?

Discuss Topics
#21

I like the idea of the short urls but I dislike linking to forge. Forge has horribly formatted text, is not structured and no actual source of knowledge. In the worst case someone is just complaining about something there. Also, you don’t have a clear path from forge to the docs.

#22

That’s true. Then a link to the docs would make sense, but the docs URL won’t exist the moment a change is posted to Gerrit. Of course, if there’s a separate domain, you could add an URL which will start working once a new (sprint) release is published.

#23

As others already said here, I am in favor of shorten the messages only if the information you subtract does not get lost i.e. there is something that points where to find more detailed informations. (the issue, the relevant rst file…).

#24

So shortlink to the documentation of the rST files (not only for deprecations also for the features) like
short.typo3.org/issueNumber ?

#25

I’d love to have that, so I’d propose to do the following:

  • Shorten deprecation message
  • Always add the issue number as identifier
  • Write a “parser” linking the issue number in reports module / deprecation log to link the issues to the short link
  • have short.typo3.org/issueNumber (subdomain tbd) and have it redirect to the rst file
4 Likes
#26

My proposal for a deprecation message:

trigger_error('Using $noWSOL as second parameter will be removed, use your custom database query for it', E_USER_DEPRECATED);
trigger_error('Configuration option XYZ will be removed, use ABC instead,', E_USER_DEPRECATED);
trigger_error('Configuration option XYZ will be removed. See Breaking-12345.rst', E_USER_DEPRECATED);

For a method this should be the rule:

trigger_error('getUserObj() will be removed, use GeneralUtility::makeInstance() instead.', E_USER_DEPRECATED);

Where the method comments should have a @deprecated information with more information because this is not logged anymore.

@deprecated will be removed in TYPO3 v10.0, if still necessary, rebuild it on your own by copy over the code in your function. See Breaking-12345.rst for more details.

Basically:

  • “has been deprecated” and especially “since TYPO3 v8.2” should not be used anymore AT ALL.
  • “will be removed” does not contain a version in the trigger_error call.
  • deprecating a method should have trigger_error() and @deprecated, and trigger_error should contain the method name (although we could get this through the backtrace as well)
#27

@Benni: I thought the idea was to have the issue-id easily parseable so a deprecation-log-viewer in the backend could figure out how to link to a page fetching/rendering the appropriate rst-file.

#28

Although a deprecation viewer module in the backend would be nice, imo it has no additional value for a developer who comes across the deprecated method in the code, because he again has to leave his code to search the backend for the module, which he has to search through to find the link to the actual information. I am in favor of doing short links, because the developer can jump to the information right out of his IDE and does not have to search through additional stuff to find what he needs to know to go on with development.

1 Like
#29

I thought more as message:

getUserObj() will be removed. See #12345

2 Likes
#30

This topic was automatically closed after 14 days. New replies are no longer allowed.