search

pattern-lab / patternlab-node

The Node version of Pattern Lab
http://patternlab.io
MIT License
2.05k stars 407 forks source link

Pattern Lab Node Core 3.0 #603

Closed bmuenzenmeyer closed 6 years ago

bmuenzenmeyer commented 7 years ago

Single mega-issue to track all work and longform explain 3.0 goals and direction. Buckle up.

Acknowledgement: I highly respect Moving Fractal Forwards for publically summarizing their road ahead and wanted to take the time to do the same here, as we got a lot in motion too.

Pattern Lab Node has enjoyed tremendous interest from its humble roots. I have y'all to thank for its continued relevance and success. Thank you to everyone who has used the tool, encouraged me, contributed back, reported issues, and shared what they've built - it's humbling and intimidating and represents to me the best in open source. I know it's used everywhere from Fortune 50 companies, to major open source foundations, to agencies, to individual users. I've even seen Pattern Lab experience show up in job descriptions. what?!

Opportunities

And with this growth has come increased awareness of the library's shortcomings. I'll attempt to list and address some here:

It's too hard to use Pattern Lab as a dependency

Pattern Lab 1.0 was a monolithic monstrosity of grunt and gulp tasks, all assets, and the core library all delivered in one repository. Pattern Lab 2.0 introduced the Pattern Lab Ecosystem which went a long way toward achieving more modularization. But still, Pattern Lab Node was not oriented well for direct consumption. We intend to fix this with Pattern Lab Node 3.0 with the introduction of the CLI (command line interface).

The CLI will encapsulate Pattern Lab core functionality and provide a consistent, well-documented means to access it. It will allow users to initialize a new Pattern Lab instance anywhere, even as a dependency in a larger project. It will exhibit much of the functionality currently shipping within editions.

The great news is that the CLI is already in alpha, created by the wonderful @raphaelokon. A couple small things remain for this to hit the big time. Be excited, because I sure am!

Pattern Lab build times are increasingly slow with increasing numbers and complexity of patterns

Issues like this one started cropping up with evolution of the tool. It also led to some mismanagement on my part of potential solutions. The amazing, knock-your-socks-off good news is that this problem has been tackled with the stellar contribution of @tburny and Incremental Builds. In some non-scientific testing against a large pattern tree, this new feature decreased build times 7-fold. I've long wanted to do a spike on performance, and this feature preempted my best efforts and goes a long way toward making performance problems a thing of the past.

@geoffp is also laying the ground work to make the entire library run asynchronously - with the side benefit of adding performance.

Staying "up to date" with edition-node-gulp/editon-node-grunt is too difficult

Because of the architecture of Pattern Lab Node 2.X - grunt and gulp editions performed too much work on behalf of users. Your shipped gruntfile/gulpfile has many brittle tasks that I consider plumbing. We will be black-boxing most of that functionality in the future. For example, you don't need to know how we copy source/_js to public/js, just that we do, and if you want to do something, you operate on whichever destination makes the most since for you.

Because we shipped with all our guts hanging out, updates were always messy, manual affairs we had to announce and pray people noticed. It's annoying to have to integrate gulp/grunt tasks into your own build chain.

Also, my choice to use gulp 4 has led to too much confusion. The advent of the CLI will do away with the need for nearly any grunt or gulp tasks. The existing editions will be major revved and become even simpler example repositories. New repositories, patternlab-node-gulp and patternlab-node-grunt will expose thin wrappers for consumption, if need be.

The Getting Started experience could use a better UX

I want to make Pattern Lab even more approachable than it is now. Starterkits and demo.patternlab.io provide some direction, but I've been asked a number of times how one "starts". I think this is part tooling and part workflow. I am planning some additional content to address this, and excited at the prospects. Stay tuned.

Customizing the Pattern Lab UI is not intuitive or for the casual user

Forking StyleguideKit Assets Default is not the simplest endeavor, but can lead to complete customization of the Pattern Lab user interface. I want to reduce this barrier to entry even further by providing a simple plugin for UI theming and menu extension. It's on the list. It will happen.

Pattern Lab Node plugin installation is a bit wonky

Feedback from users is that plugin installation is odd and annoying on update. I plan to improve this by putting more configuration into patternlab-config.json in the near future, to, for example, configure the tabs to add to plugin node tab at any time.

Pattern Lab could do more to chase the holy grail

Features like Exporting Patterns aim to make Pattern Lab output more consumable. I want to know in what other ways we can do better. Let us know.

Issue / PR Bankruptcy

I've let some PRs and issues grow stale, irrelevant, or the codebase has just plain evolved since they were opened. If I offend anyone with closure, please know that it is not out of disregard or disrespect for your work - it's just that there is only so much that can be reviewed, and only so much that can be prioritized out of my free time. My mismanagement of some PRs, whether in letting them get stale, or in not providing enough directional re-alignment earlier, is to me the single biggest failure I've had with the project (besides laughably poor code at times). I hope to continue to work with you all and by all means re-open anything you still see as relevant and are willing to carry forward constructively.

A Note About the Spec

Just because we will be incrementing the module's major version does not mean we are departing from the Pattern Lab 2 specification. I still plan to embrace all of the goodness that Dave baked into the re-write, with a strong emphasis on keeping a modular solution moving forward. There is now even an Acid Test Starterkit to test nuanced issues across the platform. I will be adding a new key to package.json or patternlab-config.json to signify this spec compliance version number.

Support Pattern Lab Node

I've set up a Patreon account to directly support continued work on the Pattern Lab Node project.

I need help and support to make Pattern Lab Node a sustained success. I devote a lot of free time and would-be sleep to make the project what it is, but nothing compares to hearing back from users. It means the world to me when people find value in Pattern Lab Node. I am ridiculously humbled to hear and see what y'all build with it.

If you find yourself here and balk and the idea of supporting open source software monetarily - I understand. Carry on, but please do share what you build - we all learn more together.

Work Breakdown (this will be updated frequently)

Check the milestone

geoffp commented 7 years ago

Bam -- I just did the first merge of latest master and the async stuff, and then came here and saw this! I still have a lot to figure out about what the hell I was thinking two months ago.

bmuenzenmeyer commented 7 years ago

Thanks for all your work so far @geoffp

Because others a stepping up to the plate and offering help with changes, I made a dev-3.0 branch to encapsulate our running work toward this milestone. I only merged what you had deemed stable, and still need to poke around some of the pattern ordering work (but did merge a pretty old fix of my own into it)

bmuenzenmeyer commented 7 years ago

@geoffp @raphaelokon @tburny all,

I will be documenting as many use cases as I can within https://github.com/pattern-lab/patternlab-node-cli/wiki/Use-Cases

more thoughts, after a braindump in chat. verbatim, pardon tersenss, ask for clarification is need. I will task out stuff best I can afterward.

Is the CLI a replacement for Editions?

i need to do a better job of articulating the mindset shift between 2.X and 3.X the CLI is not a replacement for editions to me, editions should be examples of how to interface with core, engines, etc they are intended to be standalone more so than what most organizations need people dont realize it, but anyone with bigger toolchains bastardize an edition on day one when they plug it into their tool chain my goal is that the CLI helps them do that quicker, and possibly skip the edition step altogether editions are great for those that want to learn about PL standalone, but most teams / orgs / professional developers will level up to direct usage before too long

How do we offer support for a Gulp based workflow via CLI ?

my thoughts on that are as follows will have to use an example i am comfortable with, but i think it applies BrowserSync is a powerful Node tool, and can be directly used by motivated indivudals. https://github.com/BrowserSync/browser-sync it has grunt and gulp wrappers that help developers interface with it from within toolchains: https://github.com/BrowserSync/gulp-browser-sync for example editions are NOT that, but they sorta intended to be i executed that poorly in 2.X and exposed too much internals so people saw the PL gulp edition with easy hooks to copy paste into their own workflows Pattern Lab can be that same powerful standalone tool with thin grunt and gulp wrapers if needed or someone can use "an edition" as defined http://patternlab.io/docs/advanced-ecosystem-overview.html to either get up and running in an opinionated way, roll their own, etc the CLI is a new thing, not really well defined within our ecosystem hence the need for use cases as we wedge it in concrete steps to move forward 1) get BS back into core 2) make core load any pattern engines more intelligently, and remove the default 3) alter each engine to spawn its head and foot pattern into _meta/ if not found 4) wrap up CLI work calling into Core BS - CLI Issue Needed 5) major rev editions, and make them clear they are example configurations 6) truly build patternlab-grunt and patternlab-gulp as thin interfaces into core 7) have the editions consumes 6 8) address the Core "CLI"

I hope this helps resolve some lingering questions or concerns with the direction of the project. I intend

stale[bot] commented 7 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.