yesodweb/yesod-scaffold

Outdated README instructions for developing on scaffolding

Closed this issue · 8 comments

MaxGabriel commented

The current README references yesod-scaffold-merge and yesod-scaffold-build which afaict no longer exist. I sort of reverse engineered the usage to be:

  1. Install dependencies: packdeps, cabal-install
  2. Run stack install
  3. Run yesod-scaffold build / make-template / merge / push. I am not sure what make-template does though, or how to use it.

My workflow for testing changes to the build script was was pretty hacky. I made a branch postgres-add-readme where I made changes to the scaffolding, then I changed this code to only reference that branch:

branches :: [Text]
branches = [ "postgres-add-readme"
           ]

master :: Text
master = "postgres-add-readme"

Is there a better way? Maybe something to do with make-template?

snoyberg commented

The individual -merge and -build executables got folded into the main yesod-scaffold executable as subcommands, so now anything which would have been yesod-scaffold-merge is just yesod-scaffold merge. I'll make that update.

Typically, if you're just making a change to one branch, using stack build in the normal way is all that's needed, the rest of the commands are meant for helping with updating branches and testing all of them at once, as well as ultimately creating the template files used by the stack-templates repo.

snoyberg commented

I've made a few updates to README.md, can you look them over?

MaxGabriel commented

README looks solid now, thanks @snoyberg! I think your changes are sufficient, especially because I think only a handful of people use this functionality, but if I was to look critically:

  1. It doesn't seem to be possible to get help text for the additional options of yesod-scaffold build or merge, even though the code defines them. This is maybe worth a separate issue unless I'm misusing --help:
maximiliantagher@Maximilians-MBP ~/D/C/H/y/yesod-scaffold> yesod-scaffold build --help
yesod-scaffold dev tools

Usage: yesod-scaffold [--version] [--help] COMMAND
  Provides functionality for working with the Yesod scaffolding

Available options:
  --version                Show version
  --help                   Show this help text

Available commands:
  build                    Compile all of the scaffoldings
  make-template            Make a template
  merge                    Perform merge
  push                     Push to origin
  1. make-template isn't documented in the README. Possibly it's not important enough to warrant being included in the README—I don't really understand how it's meant to be used.
snoyberg commented

You're right about the missing help info, see: fpco/optparse-simple#7. I'll push a patch to use the newest version of optparse-simple.

It may be worth just removing make-template if it causes confusion. IIRC, its purpose is simply to create a single .hsfiles output, but the build command is the only one I use for that now.

MaxGabriel commented

Ok, I figured that's what make-template did, I just wasn't sure how to pass arguments to it correctly. I think I have it though:

yesod-scaffold make-template "." testFile.hsfiles postgres

I actually think that command is pretty useful and I would definitely have used it in the PRs I was working on. I'd say keep it!

MaxGabriel commented

How about this to clarify usage? #167

snoyberg commented
MaxGabriel commented

Think this is resolved now