META -- how do we deal with deprecated APIs in 8.x-1.x

Examples is a documentation project where we demonstrate best practices, including not using deprecated APIs.

True. But we are also a major source of sample code to help people get their work done. We are a essentially at teaching and training project. The "best practices" and "learn how to code this efficiently" goals are not necessarily at odds, but neither are they the same.

For issues like this: #2581559: Port Field Permission Example to Drupal 8 we have a choice: We can commit a module with deprecated code and then follow-up, or we can say fix the deprecations and then we can commit it. Either way, we fix the deprecations. :-)

We do need to fix the deprecated calls. The question is: when and how. Let's look a bit more at the Field Permission Example. The entity_*() family of functions are deprecated, but at present, you'll find very little in Core currently uses anything else (try it -- I checked). In spite of these functions getting deprecated very early in the Drupal 8 dev process -- back in 2013. You won't find a lot of code in Core done in the style of my latest FPE patch. The closest I found was in the implementations of the old procedural functions themselves.

So why are they still so heavily used in Core?

Part of it is how much more verbose the "recommended API" is. The D7 entity methods are, by in large, more compact than the OO methods that replace them. So even after the old procedural function were deprecated -- as many as two years after -- people working on Core kept on using them. This isn't a problem with OO code per se. But I do think it's a problem with some of our current OO APIs. In places, we really do need some convenience functions in the new APIs that are currently missing. In the meantime, some of the procedural functions are considerably more concise, and therefore, it's easier to write correct (as in "it works correctly") code using them. So even in Core, the functions keep popping up. It's still easier to write code that looks like what it means, and actually does what it says, if you use some of the convenience functions. So people keep doing it.

Because some of the new style coding is a PITA, I strongly suspect that some of the APIs will get extended a bit for the sake of better developer experience. But that will happen because people start changing Core, and not because we or anyone else tries to implement the deprecation strategy before it actually gets further along in Core.

Another part of the reason is how much of our test code still uses SimpleTest, which does not mix well with some of our newer OO code. For example, SimpleTest test classes are not containers; in fact, due to how they get called, they actually can't be containers. You can clean up some of this kind of code, but there's a conflict between coding clearly (i.e., writing code that is at least somewhat self-documenting) and coding "correctly", as we've been defining it. For the FPE, I needed to look at the test code used in Core, which is very old-style. I could use the existing KernelTest based code as a model (bad?) or I could write an entirely new base class for the FPE. Which might differ more than a little from whatever PHPUnit based test will ultimately replace the current base class, some time before we get to 9.0. But in some cases, changing to PHPUnit tests before Core does is very tough, very low level coding.

Take the Rules module for D8 as an example. The code for Rules D8 has gone pretty far in this direction. I've done a fair bit with the Rules people. fago and klausi write very cutting edge Drupal code, and excellent code it is. But it's not a fast process. Perhaps we will have a usable very of Rules in time for DrupalCon New Orleans. But we may well not. What klausi did to make that happen in Rules was hard. I encourage anybody to ready his base classes for Rules phpunit tests. There's very little like it in Core, and it works nicely. But even for klausi, some of that code didn't quite do what he thought it did, as we discovered when we found that the new code didn't behave like the older procedural style code. Which did what we thought the code should do. Which is a risk you take when you diverge from what typical Core code looks like.

This is a case where, like the French say, the Best is the Enemy of the Good. Part of what's keeping back D8 adoption is a lack of good sample code. Part of the Example project's goal is to be just such a source of good sample code. But since so much of our code is churning in patches, and not getting checked in, it's not very available sample code. For a lot of Drupal coding work, Core is still the only sample code that people can find. And it's not necessarily as usable as we might like.

I think that there's a balancing act between suppling the Drupal community with good code to work from as soon as we can, vs. supply the community with the "right" code, whenever we can finish it. I'd argue that we may want to rebalance how we're approaching that.