Should we keep deprecation messages as short as possible?

[alexanderschnitzler]

Discussion Topic

While we are now having rst files whenever we deprecate stuff and while having the extension scanner which actually guides you towards these files, do we still need deprecation messages that explain the subject?

We often have messages like:

X is deprecated from version foo on and will be removed in version bar, use Y instead.

I’d like to keep these messages to a minimum and drop the latter part, use y instead.
I think a deprecation message should only tell you what exactly is deprecated and when it will stop working but should not contain any further information as there is a rst file in place with all the info you need.

What do you think?

Impact

You need to read the rst file to know the whole story. However, you always should…

Pro

Messages are short and reduced to the bare minimum. And hopefully no multiline.

Con

People need to RTFM. Well, we want them to, don’t we? That’s why we insist on having rst files.

Organizational

Topic Initiator: Alexander Schnitzler
Topic Mentor: None

[tmotylewski]

Just a side note. The deprecation message should also contain info regarding context - e.g. from where the stuff is thrown, as stacktrace is often not enough to figure out which extension is guilty (especially important when some config is deprecated).

[mbrodala]

I agree that deprecation messages should be as short as possible:

1. Deprecation logs are easier to scan since the messages are short.
2. We have docs with details about replacements as you mentioned.
3. It is not always possible to explain replacements in a few words; consequently having a replacement in one location but not in the other would be inconsistent.

[bastianbalthasarbux]

If it guides you to the exact .rst file, where you could find DETAILED information about what got deprecated and how to overcome (and eventually also why it got deprecated, but that’s not too important for extension developers IMHO), I would be fine with shorter logging messages.
But if the .rst file is a couple of megs big, including every change everywhere in the whole cms, I would tend to keep the message as it is, it’s already too little information. …
The problem I can see growing the last couple of years is, that I find it really difficult to get qualified information when moving along with extensions. 4.5 -> 6.2 was pretty straigth, all information was prepared understandable, but since then the situation got worse.

[alexanderschnitzler]

A little OT:

But if the .rst file is a couple of megs big, including every change everywhere in the whole cms, I would tend to keep the message as it is, it’s already too little information. …

It seems you have not yet seen any rst file. Have a look at this page for example. It shows all the deprecations of the current development.

https://docs.typo3.org/typo3cms/extensions/core/Changelog/master/Index.html#deprecation

Since 8.0, every change needs to be documented, so you should have a better upgrade experience in the future.

See https://docs.typo3.org/typo3cms/extensions/core/Index.html for all changes that happened between 7 and 8 LTS.

[bastianbalthasarbux]

Well, the last one is a good example for making a switch from LTS to LTS painful. But yeah, I accept it is already WAY better than this hell of a documentation: https://wiki.typo3.org/TYPO3.CMS/Releases/7.6/Deprecation
And maybe my level of ‘lostness’ is also influenced by the myriads of deprecations between 6 LTS, 7 LTS and 8 LTS …

Sorry for OTing this thread … feel free to delete my posts.

[bastianbalthasarbux]

+1 for shortening deprecation log.

[jigal]

Extension authors can use the scanner to find the majority of the issues before even testing an extension. A code review helped by tools in a good IDE will reveal most other issues. One should not expect that many entries in a deprecation log.
In production context logging deprecations ought to be disabled.

Can you explain what the real problem is?

[alexanderschnitzler]

Hi Jigal,

who exactly are you addressing now with that question?

[opi99]

It seams Jigal addressed you Alexander Schnitzler.

I also don’t get, what the real issue is with the deprecation messages now.
Sometimes I wish, the ticket number would be added to the deprecation message, which makes it faster to find the correlated rst file.

[alexanderschnitzler]

Hmm, I thought this is actually pretty clear.
It’s just about the amount of information we give in the the deprecation message as this is often a topic during reviews.

Should the deprecation message simply just tell you what is deprecated or should it contain additional information such as:

• Since when is it deprecated?
• When will it be removed?
• What should be used instead
• and so on

This discussion is about what information exactly should be part of a message and I personally opt for having as little as possible as we have the docs and the extension scanner. In the end I’d like to have a clear decision we can all rely on and avoid discussions during the reviews.

[neufeind]

Would it make more sense to add the issue-id parseable (always as last part, …) of a deprecation? That way the system could figure out which RST to link to/show. Of course those numbers alone would be not too useful - but with the RST-file “linked” this way deprecations could get a details-link. And with RSTs available that could be a local RST-viewer, while with the ticket-number we could also link from there to a wiki-page for user-contributed notes maybe.

[richardhaeser]

I’m also in favour of shorter deprecation messages. To make life easier for a dev I think mentioning the issue-number of deprecation would be great as @neufeind mentioned . That way it is easier to find the specific information about the deprecation.

I think the linking part is for the dev himself to arrange and maybe there can be a nice PhpStorm plugin for example. For me the number itself is more than enough.

[kevin-ditscheid]

To be honest, I find myself time after time wishing that the deprecation message could give me MORE information about what to use instead. I think good code does document itself and that should also be applied to deprecation messages. To assume that the developer has to leave his code to search for a simple replacement of a deprecated method, is no good solution. Sure the deprecation message shouldn’t be too long, but a simple “see method XY” isn’t really a long info and it definitely isn’t unnecessary, because it gets the developer back on track right away, without forcing him to search through massive docs, when he actually found his solution already.
Sure developers should read docs and manuals, but who of you have never met a guy, who’s asked a question that could be answered by reading the docs?
I really would like all deprecation messages to contain at least a reference where to find new logic, be it a simple method reference or a short URL to the docs.

[minifranske]

The forge id should be enough for every developer

Searching for #12345 in the code gives him/her the rst file describing the deprecation. And https://forge.typo3.org/issues/12345 will give the full history of the deprecation issue and a link to the patch.

And if the developer doesn’t know of our issue system yet they will probably search/google for typo3 #12345 and find the same info.

Having the issue ID in de source code also helps the developer that finds a deprecated method on his quest of building some new functionality. Currently it isn’t that easy to find the rst file describing the alternative without having access to git annotations in the core code.

@alexanderschnitzler can you maybe give some examples of the new proposed deprecation messages?

Example:

• “Method Class::Method() is deprecated #12345”
• “Class Class is deprecated #12345”

[alexanderschnitzler]

To assume that the developer has to leave his code to search for a simple replacement of a deprecated method, is no good solution.

This statement makes me wonder if people already know the effort that is put into the extension scanner and the documentation that has to be written for every change.

Let me shorty describe how I would deal with an extension upgrade for version 9 and why I don’t really get these concerns.

Given you have a version 8 installation with some extensions, you

1. Uninstall all extensions
2. Upgrade the core
3. Enter the install tool and start the extension scanner which covers (at this very moment) about 60-70% of all deprecations that we have in master.

I assume you browse the messages and study the documentation to understand what has changed and why. Then you adjust your code according to the documents. After that the chances are high you have very few or no parts in your code base that rely on deprecated code. However, you might have an inspection (PHPStorm) in place that scans for deprecated stuff and there are a few things left.

Q: Why aren’t these things covered by the extension scanner in the first place?
A: It’s very likely that it could not be covered by a simple rule and therefore is a change you can hardly describe in one sentence.

Given that statement is true in most cases, a oneliner, hardly describing the change, will not help you at all. I’d even say, that if you are willing to solve a problem, that couldn’t be covered by the extension scanner, on your own (without or with hardly any documentation), you are doing something wrong.

I truly believe that all of us will even become better develoers by reading the documentation, even if you are not struck by a change. Because, in most cases, changes happen as code is improved. Especially when things become deprecated.

Sure developers should read docs and manuals, but who of you have never met a guy, who’s asked a question that could be answered by reading the docs?

Sorry, but I really hope everyone did. Why should we even write documentation in the first place if developers first try to solve problems on their own instead of getting all the necessary information from the one who is responsible for the change and therefore the work the developer is dealing with?

I really would like all deprecation messages to contain at least a reference where to find new logic, be it a simple method reference or a short URL to the docs.

I assume providing a link might be difficult as the link is not known at the time of writing the patchset, but we have the issue number. Like many others said, we could add that to the deprecation message and you’ll easily find the docs, if you are not using the extension scanner or the scanner didn’t help.

[alexanderschnitzler]

Currently it isn’t that easy to find the rst file describing the alternative without having access to git annotations in the core code.

Unfortunately you are right. When browsing https://docs.typo3.org/ it’s not even easy to find the Changelog. At least I struggle with that all the time. And on top of that I don’t see that the search in the docs is working at all. I mostly do not have a single hit.
Example:
https://docs.typo3.org/typo3cms/extensions/core/search.html?q=82975&check_keywords=yes&area=default

The doc about the issue 82975 does exist, the number is part of the filename and the title, yet the search doesn’t find that.

So, I’d like to see that improved so we have one working way we can tell everybody. Very often TYPO3 lacks a “definite guide to XYZ” because there is not just that one way but dozens and all of them have their flaws.
Sorry, that was quite OT.

@alexanderschnitzler can you maybe give some examples of the new proposed deprecation messages?

Well, I don’t have the perfect idea but I’d start with:

X is deprecated from version Y on, see issue #12345

I’d even not tell when something stops working because very often we couldn’t manage to remove the code in the stated version. And besides that I don’t think it matters at all because from the moment on something is deprecated you must expect your code to break anytime if you don’t adjust. On top of that we have a rule of thumbs that we deprecate at least for one LTS version, so why explicitly mention that version at all?

To me the idea of a deprecation message is to inform the developer that he relies on legacy code and he/she must inform him/herself about the change and act. The sooner, the better.

[kevin-ditscheid]

Sry, but I didn’t knew that an extension scanner even exists.
I haven’t had an upgrade in mind when talking about developers finding themselfes using deprecated methods, but simply stuff that worked for years and has been deprecated at some point, without the developer noticing.
I am not reading every changelog of every update I must admit, because I do not get the time to do such stuff. It always is my freetime.
As an example of what I mean: I searched for a way to get the PageRenderer instance and lots of search results on google led me to the deprecated way of getting it from the getter in $GLOBALS[‘TSFE’]. Here I was stuck, because the deprecation message never told me what the replacement is and even how to find evidence on where to find the information on the deprecation itself and its replacement. I had to stop development and search through the docs.
I overred the issue number idea, I apologize, but this would be a good solution to the problem I see many people facing with the deprecation messages only telling that something is deprecated and nothing more.
Not all developers who are using TYPO3 care about reading all documentation, sad as it is. I am not saying that the effort of creating those docs and information is useless, because lots of good developers will care about having good documentation, but for people who want to integrate functionality fast, this could just be a very tedious hindrance. Telling the developer: “Hey, what you are doing is outdated, please go here to learn why and what to do” is much much better than just say: “You are doing it wrong”.

[acrivelli]

I disagree to have too short messages. We should at the very least link to the issue which will contains all information needed to upgrade code. But I would prefer to have that information directly in the code itself.

[mbrodala]

I like the idea of adding the Forge ticket number to the messages. We could register a very short domain name who redirects to the requested forge ticket to keep the messages short.

Since this would be the same for every single message, we’d have a consistent and single source of truth (Forge), no matter how easy/complex a migration is.