Determine what to ship inside source/

bmuenzenmeyer commented 8 years ago

@dmolsen does PL/PHP ship with a source/ pattern tree or do you assume a user pulls in a starterkit right away?

dmolsen commented 8 years ago

Not sure what you mean. Can you give me an example of what you might be looking for?

On Jun 11, 2016, at 7:21 AM, Brian Muenzenmeyer notifications@github.com wrote:

@dmolsen does PL/PHP ship with a source/ pattern tree?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

bmuenzenmeyer commented 8 years ago

sure.

right now during dev, for convenience, I've left https://github.com/pattern-lab/edition-node-gulp/tree/dev/source populated with a default pattern tree. This makes pulling it down and running easier, but I wonder what PL/PHP does at the edition level. Is a user expected to load a starterkit first?

dmolsen commented 8 years ago

With the caveat that I think you can go in whichever direction you think makes sense for Node and NPM. I've said it before and I'll say it again, the Installer has been where I've spent a ton of time. I'm hesitant to make it part of spec and force you to follow. I also think this is a key area that will be tested by real use. It's still quasi-theoretical though the Drupal guys have rolled with it.

Obviously a PL/PHP Edition from the official org does not ship with files in source/. It's expected that an Edition will come with one of the following:

an explicit dependency for a StarterKit or
a list of StarterKit options known to work with the Edition that the user can choose from or
nothing and a user will choose to explicitly load a specific StarterKit (could be a blank one) via a command

The first one is managed via Composer. The last two are managed by custom code within PL/PHP and are downloaded as Zip files.

via Composer as an Explicit Dependency

As noted, a user can set up the following require in composer.json for their Edition and Pattern Lab will load the StarterKit on install.

"require": {
      "php": ">=5.3.6",
      "pattern-lab/core": "^2.1.0",
      "pattern-lab/patternengine-twig": "^2.0.0",
      "pattern-lab/styleguidekit-twig-default": "^2.0.0",
      "pattern-lab/starterkit-twig-default": "^2.0.0"
},

PL/PHP takes "advantage" of various install events exposed by Composer. Custom code moves stuff from vendor/ to source/ automagically.

If the StarterKit has been updated then a composer update or composer update pattern-lab/starterkit-twig-default will prompt the user to overwrite source/ or merge the changes in the StarterKit with source/. Again, this is custom code that takes advantage of those install events.

via Zip as a Suggestion or Command

This feature only works with GitHub currently. This feature ensures that a StarterKit is a true starting point and that dependency updates to their work won't affect source/. This can be invoked in two ways:

via a StarterKitSuggestions block in composer.json or
via a command-line command in the case of an Edition either not suggesting a StarterKit or not having one as a dependency.

via StarterKitSuggestions

This works kind of like Yeoman in that, on install, Pattern Lab will prompt the user via the command line and ask which one they might want to install. They choose a number, PL goes and grabs the Zip related to the choice, and installs it.

via a Command

The command offers these options (loses some of its formatting pasting here):

  Starterkit Command Options

  Usage:

    php core/console --starterkit|-k [--init|-i] [--install|-j] 

  Available options:

    --init    (-i)    Initialize with a blank StarterKit based on the active PatternEngine.
    --install (-j)    Fetch a specific StarterKit from GitHub.

  Help:

    The StarterKit command downloads StarterKits.

  Samples:

   To initialize your project with a base StarterKit:

     php core/console --starterkit --init 

   To fetch a StarterKit from GitHub:

     php core/console --starterkit --install <starterkit-name>

--init simply fetches a base StarterKit for the PatternEngine. So if we had Twig installed as the PatternEngine then it'd grab pattern-lab/starterkit-twig-base. Looks like I might not have a base Mustache StarterKit defined.

TL;DR

Well, you'll have to read a bunch of that. I just want to reiterate that you can find a solution that works for you. There's a lot of custom code in that set-up/install process.

bmuenzenmeyer commented 8 years ago

https://github.com/pattern-lab/starterkit-mustache-base/tree/dev

pattern-lab / edition-node-gulp