[markdown] Release 8.x-2.0

I've gone ahead and technically added a "Mentions" extension that will show up in the UI, but also prevented it from being enabled and added an experimental notice pointing to #3160927: Add Mentions Extension. This way, the issue isn't a blocker and it will (hopefully) give people a way to focus on just that one thing if it's really needed.

So, the only thing left to do is really #3135360: [markdown] Add/fix documentation, which anyone can tackle.

I don't think I'll be able to get to this anytime soon. But I will gladly commit fixes to the repo and help with the docs if something specific on my part is needed.

Once that's done, we can release 8.x-2.0 and open the 3.0.x branch for D9+ support.

@markhalliwell
Why don't make 8.x-2.x (and perhaps also 8.x-1.x) D9 compatible as well? Or what's the reason to keep D8 and D9 support separate? Are there major drawbacks in trying to support two major versions of Drupal?

Thanks for maintaining this module.

@MegaChriz The only drawback that I can see is that 2.x will have a minimum Drupal core requirement of 8.7.7, since that's when they added the .info.yml key to specify core version requirement ranges (including major versions, like 8.x and 9.x). That's assuming that not much deprecated code is used in Markdown 2.x, but I haven't taken a close look.

@Ambient.Impact is correct. The reasoning behind why I decided to approach it this way was primarily due to BC (backwards compatibility):

https://www.drupal.org/project/markdown/issues/3103679#comment-13561137

As much as core touts "not breaking BC", the reality is that keeping feature parity for all versions of D8 is nearly next to impossible given the introduction (afterthoughts) of many new features and APIs. They may not technically "break anything", but they certainly add/change API directions far too often to be considered "stable" IMO.

The biggest culprit though is the core_version_requirement key that was added. While that change record (CR) is quite thorough, it is also poorly worded (and quite overly complicated, if I'm being honest).

Essentially, an extension can only use both the core and core_version_requirement keys if the latter is set to the following: ^8 || ^9 (notice the lack of any minor version).

If a specific version is required (to ensure that new APIs can be used), then the latter must be set to something like ^8.8 || ^9 and the former core key must be removed entirely (or an exception is thrown). This, inherently, means that any sites running prior to 8.7.7 cannot install said extension.

Never mind the fact that, in D9, a lot of the deprecated code must be removed for it to run properly at all; thus, keeping BC code in an extension isn't really possible.

---

So really, the only choices a developer has are:

1. Specify a "generalized" core version and have to manually check for the existence of newer APIs or lack there of (providing manual BC for when they don't exist):
   

   core: 8.x
   core_version_requirement: ^8 || ^9
   

2. Specify a "specific" core minor version that alienates sites running prior to 8.7.7
   

   # core: 8.x # cannot be used when specifying a specific minor core version
   core_version_requirement: ^8.8 || ^9
   

3. Kind of a hybrid approach of both, but using the normal "major version/branch bump" approach like we've always done with new core versions.

I opted for the latter option; it's just easier.

The goal of the 8.x-2.x branch is to keep around a 100% D8 compatible version, no matter which D8 version it is.

The goal of the 3.0.x branch is to remove all the deprecated code and make it 100% D9+ compatible (assuming they don't introduce a major change like core_version_requirement in a minor release again).

---

This is why semver exists in the first place.

Why core ultimately chose to muddy the waters and add, yet another, Drupalism to complicate things; I will never know. I do know that, in principle, it was done in an effort to allow (smaller) modules the ability to support multiple versions, which is fantastic in theory. However, the execution was actually done rather hastily and without much thought to the grander scheme of things.

The reality is that it is far easier to maintain separate versions/branches at a project level (for specific core versions) than attempting to say that a single version/branch is going to be able to support all core versions.

If one is going in to "add a line in an info file", you might as well just create a new major version/branch and go from there. This is how we've always done it; why does it have to more complicated now?

The core team also is (mostly) just concerned about the path moving forward; bleeding-edge if you will. This is fine and certainly a lot easier to maintain such a large project. However, the reality is that many large sites (at least the ones I have worked on) are often built starting at a specific core version. As things progress and the site starts to take a life on its own, the reality is that sometimes it can't always "upgrade to the latest version" especially due to the shear complexity of it. Instead, individual security holes are patched as needed while the underlying structure remains the same.

That's why some sites still run (technically) "older" versions of core even to this day. They shouldn't suffer at the extension level because of this. As noted in #3103679: [PP-1][markdown] Drupal 9 Support, patching core security holes is far less complicated than attempting to patch an extension's composer file.

---

Apologies for the long winded explanation. I just feel that a lot of this needs to be explained so people see that it isn't just a "rash" decision on my part and that there is actual thought behind why I've taken this approach with this project.

edit: I forgot to mention that (as an example) this project has a BcSupport folder where newer core APIs have been backported so that older D8 sites can still use this project.

edit: I also forgot to mention that part of the key factors here are PHP versions as they keep bumping the minimum PHP version even in minor releases. While this is fine (per semver), it definitely makes it harder for a project to continue to support an entire major version across its lifespan. Not saying that it can't be done, but it is a DX paradigm shift and it's just easier to keep two separate branches/versions at that point so you don't have to worry about things (i.e. can I use typehints yet, array destructuring, other PHP 7.2+ features etc.).

@markhalliwell No worries; I appreciate the detail and thought you put into the explanation!

@markhalliwell
Thanks a lot for your detailed explanation! Appreciated. And I accept your choice.

For my own modules I had decided to increase the minimum required core version, as soon as the old requirement no longer officially received security support, but only if it was necessary for fixing new deprecations. My thought behind this is that I assume people that don't update Drupal core (or cannot update), are less likely to update contrib modules. What also plays a role is that the modules for which I did that, were still in alpha or beta. And that I didn't found it worth the effort to put a lot of time extra in developing major changes for no longer supported core versions.
I can imagine that for major versions that have a stable release, it's a lot easier to keep providing support for them. It's great that you do for those that have issues in keeping their site up to date.

the reality is that sometimes it can't always "upgrade to the latest version" especially due to the shear complexity of it.

I haven't experienced major issues in updating core so far, but I've read others had. Maybe I would have made a different choice for my modules if I had that experience.

I'm curious what's holding up this release... Markdown is the one module holding back several of my sites from being able to upgrade to Drupal 9. Drupal 8.7 and older is past end of life, and even Drupal 8.8 reaches end of life later this year. Can we get a new major release with Drupal 9 compatibility published?

@freelock: #7 explains in detail some of the issues, but I would also guess that Mark is pretty busy, so that's also a factor. If you're able to, open pull requests to get that branch closer to release - I may do that myself when things get a little less hectic for me.

Now that Drupal 8 is EOL and Drupal 9 has a stable release in Markdown 3.0.0, let's close this.