Unify Pattern Lab Core

[bmuenzenmeyer]

Okay, here goes.

TL;DR Officially declare the authoritative representation of the Pattern Lab spec to be Pattern Lab Node. Signal our intent to deprecate and place Pattern Lab PHP to be under community maintenance only.

Since Pattern Lab was a scrappy proof of concept that @bradfrost created many years ago, the specification of what Pattern Lab is and isn't has been represented by the functionality implemented within the PHP application. Dave and Brad quickly turned around new features, responding to needs of the community. When Pattern Lab Node came along, I had a truly great living reference to build toward.

Cue Pattern Lab 2.0 🎉

With 2.0 came the ecosystem, an architecture and separation of concerns that powered our cross-platform efforts for going on 2 years now. Dave wrote the spec, which captures some of the essence of Pattern Lab's features - but I'll admit, in practice, the most current version of Pattern Lab PHP has always been what I reference as the authoritative spec.

I've spent hours comparing output between PHP and Node, usually to better understand where I need to go on the Node side. This process led to broad feature parity (though probably not complete), with updates and more movement coming out of Node. I've had to compare output less and less, excepting nuanced use-cases that required a suitable cross-platform acid-test. This process, while fruitful, is still slow. Effort within core and the styleguide front end forever need to be made in synchronicity with both platforms. It's a burden on maintainers and our users to compare and contrast versions, even forced to make hard decisions about converting from one to the other due to the issue or workaround of the hour.

Substantive changes to the core engine are proposed and implemented with a reasonable degree of success by utilizing this very spec repo - but the process is still duplicative. People have noted the irony in Pattern Lab, a tool to help make DRY componentry, offers a fragmented experience. This makes us slower and again harder for the community to know what features are in what platform.

What I propose is this. Deprecate Pattern Lab PHP. Unify the core engine under the Node repository.

Pattern Lab Node 3.0, once released, is positioned to be much more than it's predecessor.

• Pattern Lab Node can run standalone, without the need for a task runner like gulp or grunt
• Asynchronous rendering opens up more first-class support for PatternEngines like React 👀 , Liquid, even Twig.
• Ever-increasing unit test support brings more confidence to the end-user and contributors
• Improve documentation and configuration across the board

I'm excited about all of this - and what comes after these capabilities are present. We have big plans. The benefits of unifying core are broad. For our users, our documentation, our workflow, and our product.

• Pattern Lab output need not be laboriously cross-checked between two separate systems
• Maintainers can respond quicker to the needs of the community
• New features from contributors do not need to be labeled or cross-checked as "on" or "off" spec.
• Major architectural refactoring can occur across a smaller footprint
• Simplify the documentation
• Unify the communities
• Create a single entry point into the ecosystem
• Users get a clearer sense of what features Pattern Lab offers

The way forward

I don't expect this issue to completely answer all the questions that may arise from this effort. The initial outline of work is tangible, however. If approved, I plan to break out a bunch of milestones.

• Announce intent (this issue)
• Audit and catalog differences between both platforms - create issues within Pattern Lab Node where needed
• Create starterkit-mustache-spec - a combination demo / acid-test that demonstrates Pattern Lab features succinctly. This won't be the polished web design project like the current demo is. Rather, it will be a terse set of patterns that in isolation (or together, where needed) demonstrate current behavior. It's my hope to build this, automate its build, test against it during CI/CD, and automatically host results, also via CI/CD
• Update all documentation
• Invest in more tooling to make collaboration more possible. Think prettier, standard-version, CI/CD integration tests, more people releasing
• Stabilize and release Pattern Lab Node 3.0
  • I understand there are things about Pattern Lab Node that are sub-optimal, broken, or "off-spec". Let's fix em!

I think the above effort, and honestly this entire decision, will help in these ongoing or proposed efforts:

• Storefront mode architecture
• Monorepo architecture for Core + Engines
• Monorepo architecture for Styleguide
• JSON Schema Editor

All of this won't happen overnight. Believe me - I understand how time is tight. But discussing this decision and communicating intent is the first step. So here we are!

@pattern-lab/voting-members

[bmuenzenmeyer]

My vote: 👍

[gjhead]

A++

[ThePeach]

👍 good to hear this. Approved :)

[bradfrost]

Big 👍 vote from me!

The only thing that I feel is absent is a lot of the discussion with @EvanLovely about having some semblance of a true PHP engine in order to ensure things like twig (not twig.js) renders properly. My understanding of that is that there would need to be some sort of a lightweight PHP engine that handles that part of the puzzle, but everything else would happen through Node. Do I have that right?

[bmuenzenmeyer]

Yes @bradfrost you are right - the existing Twig solutions are not adequate, and while I thought one of them did in fact delegate rendering to the actual PHP runtime, I will delegate judgement to someone more versed in PHP / Twig development.

Async rendering should enable the theoretical capability, but a true PHP-run Twig PatternEngine will be a new thing.

[aleksip]

I think the problem is that there doesn't seem to be a proper spec, only a table of contents. And that is why the PHP version has so far been the de facto spec.

If Pattern Lab had a proper spec, detailing everything at the required level, and an acid test project covering the entire spec, I don't think there would be a need to declare an authoritative representation.

Do we see value in having a proper spec? Is it worth the extra work? Personally I think it depends on whether it is possible to have true Twig support for the Node version.

[bmuenzenmeyer]

@aleksip right - the spec was only ever an outline - and something that would require herculean effort to flesh out in writing. That's why I mentioned creating a starterkit-mustache-spec. Mustache remains our default PatternEngine. Upgrading the default to Handlebars would actually do-away with a lot of cruft - but that's a different conversation!

Each engine needs to make a determination about what degree of the spec it supports, and how. Some engines are more capable than others (layout, extends) or do work differently (like the Handlebars PatternEngine ) than Mustache does. So, for the purposes of what is considered "spec" (especially in regards to template rendering), we are usually referring to Mustache.

No, I don't see value in having a true spec document. But I do see value in a hosted, terse, unit-testable starterkit-mustache-spec. That could even serve as the basis for deviations outlined within individual PatternEngine capabilities.

[bmuenzenmeyer]

I don't think there would be a need to declare an authoritative representation.

The declaration is less important as is how this decision plays out - it signals that the core team will not be supporting PL PHP in earnest in the long term.

[bradfrost]

@bmuenzenmeyer I think you do what you need to do in order to make progress. It sounds like a spec would incur a lot of work, and I think that's time that would be better spent building real software.

[geoffp]

👍 excellent.

[sghoweri]

The only thing that I feel is absent is a lot of the discussion with @EvanLovely about having some semblance of a true PHP engine in order to ensure things like twig (not twig.js) renders properly. My understanding of that is that there would need to be some sort of a lightweight PHP engine that handles that part of the puzzle, but everything else would happen through Node. Do I have that right?

I'd love to hear @EvanLovely's thoughts on this but speaking for myself and the Bolt Design System team (plus my 2 cents from the Drupal Pattern Lab Working Group's POV), I've got a couple thoughts to add:

I'm 100% behind this initiative and direction we're taking, so long as the Pattern Lab PHP community isn't getting left behind here and getting adequately represented.

For me, this means you guys understanding and updating PL Node to fully support the still-growing ecosystem of CMS-enabled Design Systems, having native Twig PHP support, support for Twig extensions, support for Twig namespaces, support for plugins, etc out of the gate -- flagship advantages to the current PL PHP Core that we can't do our jobs (or power our "Holy Grail" Design Systems) without.

We need a solid plan in place to make any changes needed on the PHP and Node sides of the house to get us all living under one roof 🙂

[sghoweri]

^ but yes @bradfrost you nailed it. We already have a working prototype (in the form of a tiny NodeJS file + PHP server / service running in the background) that takes in a reference to a PL Pattern + local data, sends that off to the Pattern Lab PHP / Twig engine for rendering, and returns back the rendered HTML.

Still some work to do (like getting @aleksip's refactor work folded in) but definitely a solid indication that we can keep running in this direction