Skip to content

Pattern Lab Architectural Observations Recommendations

Jump to bottom
Brian Muenzenmeyer edited this page Nov 26, 2019 · 1 revision

I took a couple bunch of hours earlier today to look through the current codebase + Github and NPM orgs and wanted to share some initial high-level thoughts / observations.

TLDR: From a code health and code maintainability POV, I don't think we're in good shape right now. 😨

With some work however, I think we can turn this ship around. I'm just super hesitant to change anything till I get some feedback from the team!

CC @bradfrost

Observations (Current State of the Code)

Packages Released to NPM (@latest NPM tag) Prematurely

Problem: We shouldn’t be publishing out alpha or beta versions of code to the @latest NPM tag as this can lead to some serious stability / reliability issues down the road. (ie. installing code / plugins not ready for public consumption)

Examples:

Duplicate NPM repos (maintainability issues)

Problem: There's a high number of duplicate packages published to NPM.

Tab Plugin: https://www.npmjs.com/package/plugin-node-tab https://www.npmjs.com/package/@pattern-lab/plugin-tab

While this isn't always / necessarily a terrible thing however seeing both repos updated right around the same time 1. makes me anxious and 2. makes me question why the old NPM package isn't flagged for deprecation and/or isn't pointing to the new NPM package instead.

Repo vs NPM Versioning Differences

Problem: The latest versions of code for many of the @pattern-lab packages that have been published to NPM do NOT match up with the latest version numbers in the repo itself.

Ex. Latest published version of the @pattern-lab/cli package is v0.0.1-beta.1 on NPM (https://www.npmjs.com/package/@pattern-lab/cli) and yet the latest version on the dev branch is v0.0.1-beta.0 (https://github.com/pattern-lab/patternlab-node/blob/dev/packages/cli/package.json)

Versioning Differences Between Packages Themselves

Problem: Just focusing on the packages in the https://github.com/pattern-lab/patternlab-node repo itself, many of the independently published package's version number varies quite substantially.

This makes it unclear what state any particular package is in and what packages depend on what other packages.

NPM Packages (not even including all the Github Repos out there):

No Release Notes on Github Releases

https://github.com/pattern-lab/patternlab-node/releases

Problem: No release notes on the releases page (ex. what things did we add, remove, fix, etc with v3.0.0-beta.2)

Codebase vs Website Disconnect

Problem: The PL Website (ie. where the docs and demos are located) lives in a totally separate codebase than where the code itself lives meaning new PL releases can't / don't include corresponding docs to support new specific features as things get rolled out the door.

^ this further complicates the process of automatically testing / deploying the codebase as part of every release / successful Travis build

Tests Folder Monolith

Problem: The current monolithic folder of tests in the PL core/tests folder isn’t maintainable and tries to cover everything vs just the responsibilities of the package containing the tests.

Recommendations

Improve Publishing Process (Tooling)

  • Switch the monorepo over to use Yarn + Yarn workspaces with Lerna
  • Update Lerna to publish using fixed versioning
  • Verify our release process docs + version of Lerna being used are up to date
  • Add NPM scripts to the main package.json file to help with simplify publishing out pre-releases vs full releases.

Improve Publishing Process (Workflow)

  • Ensure published changes to NPM always update the version number of the corresponding package in the repo.
    • For pre-releases, this should happen on a maintained branch that’s separate from the stable code being published to the @latest NPM tag (ex. we could introduce a next branch on Github to allow for super new stuff to get released while still maintaining the last stable version of the codebase)
  • Clarify / ensure we have a set up that can handle releasing hot fixes for the latest stable version of Pattern Lab separately from the latest pre-release / next up release being worked on.
    • Update branching strategy docs to account for pre-releases vs full releases if needed

Fully Automate The Publishing / Deployment / Release Process

Retire / Archive Old Repos and NPM Packages

  • Start the process of retiring old Github repos + NPM packages that are being migrated (or have already been migrated) over to the monorepo
    • Archive old repos + point to corresponding monorepo package
    • Deprecate old NPM packages
      • For packages with non-breaking changes, you could even point the existing package to the new monorepo-published package to simplify the transition

Split Apart Tests Based on The Thing Being Tested

  • Ex. Handlebars-specific tests live with the handlebars-specific engine

Unify The Docs w/ the Code Being Documented

  • Move the existing pattern-lab site into a new top-level /website folder
    • Eventually rebuild / migrate off of Jekyll (Gatsby?) however leave this in place for now

Improve Codebase Maintainability / Organization

  • Rename and simplify many of our package naming conventions

For example: - Pattern Lab Edition Node = Mustache Starterkit - Pattern Lab Node - Development Edition Engine Handlebars = Handlebars Starterkit - Development Edition Engine React = React Starterkit - Base StarterKit for Twig (https://github.com/pattern-lab/starterkit-twig-base) = Twig Starterkit

  • Move all starterkits into a single top-level packages/starterkits folder

  • Break apart UIKit into smaller ui-specific packages (pick and choose / extend PL’s UI)

  • Reorganize how our code in the monorepo is organized by grouping together similar things. For example:

pattern-lab/
├── packages/
│   ├── core/
│   ├── cli/
│   ├── engines/
│   │   ├── react
│   │   ├── handlebars
│   │   └── twig-php
│   └── uikit/
│       ├── minimal/
│       └── default/
├── www/
│   ├── 404.html
│   ├── contribute.html
│   ├── download.html
│   ├── index.html
│   ├── resources.html
|   └── roadmap.md
├── docs/ 
│   ├── getting-started/
│   ├── working-with-patterns/
│   ├── working-with-data/
|   ├── integrations/
│   └── advanced-features/
├── examples/
│   ├── handlebars/
│   ├── gulp/
│   ├── react/
│   ├── drupal-integration/
│   └── twig-php/
└── starters/
    ├── handlebars/
    ├── drupal/
    ├── react/
    └── twig-php/

Drop Support For Code We Can’t Maintain

For example, do we really need our own custom live-server package (code that we’re now on the hook to maintain)? Couldn’t we switch to something like browsersync or webpack dev server instead?

Drop Support For A Few Pattern Engines?

If we don’t have enough bandwidth to properly maintain every single Pattern Engine currently in the repo (unless we get substantially more help) we should seriously consider dropping support for at least a few of them — at a minimum, drop support for these until we can get all of our other ducks in a row.

Ex. Could we potentially drop 1st party support for the Mustache, Nunjucks and Liquid engines (including Twig, once the Twig PHP engine is in place)

Misc

  • Clarify docs on what the heck a "starterkit" actually is / is supposed to do

Note: If we need special code for testing / validating our work, we should include that in the starterkit code itself (and just publish out a sub-folder to NPM)

⮑ ex. move these into new /packages/rendering-engines folder (or something like that)

Clone this wiki locally