Workshopper: new API

[rvagg]

Not sure if this is the best place for this but if people are going to be using workshopper to build stuff for NodeConf, be aware that I'm rewriting the guts of it because (1) it quickly became apparent the many horrible hacks were needed to move beyond the stream-adventure model of problem definition and verification and (2) it's a big ball of inconsistent awkwardness. I'm working on this right now but I can't make any promises about timeframe so don't let it hold up progress on writing anything against the current API. I'll document a migration path for upgrading existing code when it's all merged in.

Notes are here: https://github.com/rvagg/workshopper/issues/12 please add any thoughts you have regarding pain-points you've experienced developing against the existing incarnation.

Dev is happening on the newapi branch and is largely about feeling out the best approaches based on existing experience and some new content I'm writing ontop of it rather than tackling some grand plan.

[mikeal]

This is definitely a good place to post this :)

Given that you don't have a timeline people should just write to the old API right? Can you point to the docs for that?

Also, is there a good place for people using the old API to give feedback that might make it in to the new one?

[rvagg]

Yes, proceed with the existing API until further notice! I'll keep y'all informed of progress here.

Some, incomplete documentation of existing API on the workshopper README.

Mostly I'd suggest grokking how stream-adventure's exercises work, note that it's not all about printing stuff to stdout so you can compare submission output against solution output. setup.js can also hijack stdout and verify that way so you don't even need to get the workshopee to touch stdout at all.

Lots of examples of how to do more complex things can be found in the learnyounode and levelmeup exercises. There's some particularly advanced stuff in learnyounode that tracks which modules you use in the execution and some other things using the concept of an "exec wrap" that lets you execute a program wrapped in an outer program that can trap stuff. Very awkward but workable.

In learnyounode, look at "MY FIRST I/O!" and "MY FIRST ASYNC I/O!", they do some crazy advanced hackyness to check whether you use fs.readFileSync() or fs.readFile() and fail you if you use the wrong one even if the output is correct.

In levelmeup there's lots of use of the stdout hijacking to verify, get the workshopee to write something to a leveldb store and then it gets verified by streaming the contents to stdout.

The aim is to improve on these kinds of advanced setups and not force workshopper authors to bend their problem definitions into a form that can use stdout because that often leads to awkward problem definitions (a very leaky abstraction). I also want to make it easier to do basic code inspection, perhaps with esprima or arcorn or whatever, but this'll probably be via an optional package.

Provide feedback in the workshopper issue about the new API (note the stuff I've written there is a little dated, my thoughts have evolved a little but the basics are the same).

[rvagg]

Oh, and an important consideration for this new work is to be able to give the workshopee pre-existing code that they have to build upon, or fix, or use in some way.

"There is a new file in your current directory named spooge.js, it's supposed to do X but doesn't work when Y, fix it to pass this exercise".

I imagine there's lots of cases for the more complicated workshoppers where you want to get them started with boilerplate and don't want complex instructions on how to get that boilerplate. So it should be simple to do this with the problem definition.

[mikeal]

the debugging session @othiym23 is doing comes to mind in needed this "new file in your current dir" feature.

[rvagg]

It's kind of late to be doing much about this, presumably everyone's at least started their workshopper and are either using what's already available or are rolling their own. Does anyone need more assistance with workshopper? learnyounode is supposed to serve as the best source of documentation (so far ... still haven't found the time to properly doc everything).

My native addons workshopper is still in it's infancy but I'm using it to push some new things in workshopper and I'm trying to keep up with comments to make it useful as something to copy. If anyone's interested then I can add you to the repo or even just open source it right now.