Use front matter to version templates

Initial thoughts:

• Additional folder hierarchy: templates/3.0.0/... and templates/3.3.1/...
• Create "sub-base-themes" (essentially the same as above, but less than ideal)
• Version in filename, similar to what Drush allows: .drush.d7.inc
page.3.0.0.tpl.php and page.3.3.1.tpl.php
page.3-0-0.tpl.php and page.3-3-1.tpl.php
page.300.tpl.php and page.331.tpl.php
• Annotations/schema in template docblocks (would still require one of the methods above; mentioned somewhere in https://www.youtube.com/watch?v=FKu_DdbBV6s)

@joelpittet, I'm not sure I follow exactly. Can you please elaborate?

This issue isn't about d.o project versioning, but rather external framework versioning.

Ah, I see what you mean now. However, no we're not limited to just template files, this can extend to our theme functions and process/preprocess functions as well.

Due to the shear amount of overrides we have to make in this project, we already alter the theme registry so we can organize these functions into separate files for easier management:

Theme hook functions are found in: *.func.php
Process/Preprocess are found in: *.vars.php

So the above pattern in #2, for example, could be extended to templates/block/block.vars.php:
block.3-3-1.vars.php (or something similar)

This likely isn't going to happen in 7.x.

In 8.x, this will be much easier since everything is OO and we can extend classes as needed, especially given all the various @Bootstrap* plugins that exist now.

---

Summarizing what I mentioned in the drupal#bootstrap slack channel:

• Once #474684: Allow themes to declare dependencies on modules lands, we can add a bootstrap_core module to the base theme and depend on it.
• bootstrap_core would have a site wide version setting, where [sub]-themes could override as needed.
• bootstrap_core would provide some "version choosing logic", likely a service/handler or something
• Implement said service/handler in theme registry alter and @Bootstrap* plugin discovery processes.
• This would allow the base theme to break major version parity with the external Bootstrap Framework.

---

Only thing now is to determine naming/path conventions as mentioned in #2.

Not sure this is going to happen for 8.x-3.x either.

What are the drawbacks to trying to support multiple versions with the same Drupal code?

As we really haven't done this yet, I cannot really answer this properly. I suppose the main "drawback" would be that the project itself may seem to "bloat" in filesize. The typical argument against the "bloat issue" however is almost as large of a misnomer. While there may be additional files, the system itself, while it may have a few more files to scan initially (and then cached), doesn't load any of them until they're actually needed.

I haven't looked much yet into the differences between 3 and 4 but the first thing that comes to mind is potentially making things more complex and just as hard to maintain as if you had two separate versions.

As I stated in #2554199: Bootstrap 4, this specific issue isn't a hard blocker for the BS4 release... merely a "nice to have". There are a lot of similarities between the two versions though and if we can get away without having to duplicate code, I'm all for that.

The other reason for a singular code base is partially just due to how d.o, git repositories, versioning and packaging [currently] work. Having separate branches is a lot of work. Having separate projects it's even more work (i.e. overall maintenance costs).

The primary purpose of this issue is to introduce a mechanism that allows us to introduce accumulative changes introduced by newer versions of the external framework.

The best way I can think of describing (as close as possible) for what I'm trying to do here is perhaps how Apple handles its iOS updates.

The underlying architecture of iOS (BS/external framework) relatively remains the same over time.

They release a single update (single project/branch) but it works across multiple devices (multiple BS versions).

Older devices (older BS versions) won't necessarily have all the new features as they're only introduced in newer devices (newer BS versions) that actually support them.

How stable is Drupal's Bootstrap 3 support already?

It's quite stable.

BS3 to BS4 is a major change, sure, but I think you may be getting hung up on this specific major version change just a tad due to the aforementioned issue.

Introducing some sort of "versioned" mechanism would also allow us to make changes that were introduced in minor or patch releases of the external framework. These changes can happen when a new feature is introduced, a bug is fixed or a security issue has to fundamentally change the markup.

While Bootstrap certainly attempts to follow semver, that actually hasn't always been the case (they're certainly getting much better about it).

This issue is just a way to help better bridge the external project and existing installs within the Drupal eco-system.

---

Another thing that really hasn't been mentioned yet but has been swirling around in my head is better support for knowing when a sub-theme needs to upgrade their own templates.

Currently, sub-themes that implement their own templates can sometimes get overlooked when the base theme templates have been updated.

Introducing some sort of "versioned" mechanism like this could allow a UI (or CLI) tool to quickly identify which templates in the sub-theme may need updating.

---

Suffice it to say, this issue is far from perfect and I don't have all the answers. That's why this issue exists. However, this is indeed a real issue. One that has become increasingly apparent over the years of maintaining (and upgrading) multiple versions of BS: how to introduce new version changes without breaking BC of existing installs.

This entire issue needs an IS update as well, so tagging as such.

#2920309: Add experimental module for Help Topics is using <meta> tags in twig templates and a custom discovery mechanism to accomplish similar "metadata" in twig templates, e.g.:

<meta name="help_topic:label" content="Changing basic site settings"/>
<meta name="help_topic:top_level"/>
<meta name="help_topic:related" content="user.security_account_settings"/>

In theory, we could do something similar. We'll likely need Semver support to parse the constraints though:

<meta name="bootstrap:version" content="^3.3.4">

That being said, and perhaps for security reasons, we probably don't want to include this meta info in the template itself. I'm guessing that since help topics are typically only user/admin related, this is less of a concern (edit: it's XSS filtered). Whereas with this project, the templates are public facing.

PHP appears to still be able to parse the metadata (http://ideone.com/uFfQi1) even if they're wrapped in a Twig comment (which PHP has no concept of):

{# <meta name="bootstrap:version" content="^3.3.4"> #}

I've gone ahead and opened https://github.com/twigphp/Twig/issues/3082

Using front matter makes the most sense:

---
bootstrap:
  version: >=3.0.0 <4.0.0
---
<twig-template>

#3064854: Allow Twig templates to use front matter for metadata support