Next-gen rearchitecting plan

[binford2k]

The Showoff codebase has outgrown its monolithic roots. It's time to redesign from the ground up. I plan to do this in several stages, so that we can iteratively build a solid new architecture but keep disruptions as minimal as possible.

Ping @gepandz for collaboration. Comments on this issue are invited.

We'll work in a "parallel" codebase, starting with only core features and porting things one at a time. This allows us to release and update both lines simultaneously and select at runtime.

I also plan on abstracting out optional subfeatures, with both server side plugins to the Ruby based compiler/server and viewer side as javascript plugins.

During the development of Showoff-ng, access to the new codebase will be gated by either a feature flag or by a small CLI wrapper utility. Initially, we'll do a bug-for-bug port, and then will start to improve the language as well*. We'll favor refactoring rather than writing new. As we generate each class/method, the unit/integration tests will be written before the implementation. (that shouldn't need to be said, but testability is one of the drivers for this, so I want to make sure that's the first thing we think of.)

Decisions to be made:

• Can we replace the js slide library while we're at it?
• Are we ready to revamp the web side as well? Maybe @marrero984 wants to get involved again.
• Let's take another look at markdown library support. Does it really make sense to continue to support everything under the sun?
• At minimum, let's consider switching to commonmarker by default
• Should we start the language redesign from the beginning too, rather than carrying it forward bug-for-bug?

Stage 1:

1. Design the first iteration of the architecture
   • Expected Ruby classes:
     • Showoff::Config
     • Showoff::Compiler
     • Showoff::Compiler::<components> # things like the forms generator, etc
     • Showoff::Presentation
     • Showoff::Slide
     • Showoff::Server # just the webserver
     • Showoff::Transport # the websockets control protocol
2. Design the first iteration of the API
   • VERSIONED!
   • Should the presentation continue to be a single-page app, or should each slide be lazy loaded on demand? It would be easy enough for the server to support both.
   • Should the forms be ported to use the standard websocket transport like everything else, or should most things be ported back to a RESTful API?
3. Build the compiler
   • This will be a command line tool that implements showoff static
   • It just reads the presentation source and generates HTML on disk
4. Build the barebones webserver
   • This will only serve the presentation. It will not include interactivity to begin with.
5. Build the protocol transport layer
   • This could probably use a better name!
   • This does the interaction, like page following and presence detection

Stage 2:

1. Design and build the development toolkit
   • validate, info, new slide, new presentation, etc
2. Design and build the publisher framework
   • Build the presentation and publish to:
     • GitHub pages
     • Heroku
     • ios/android mobile app
     • Docker instance
     • zip/tarball
     • other?

Stage 3:

1. Feature parity and exhaustive testing
2. Design language improvements
   • if we do this right, it allows us to take better advantage of renderer features
3. Merge codebases and release next-gen

[binford2k]

Markdown support options (checked if it seems maintained):

• Redcarpet: last release this year, but only minor updates
• rdiscount: last release in 2016, nothing special
• Maruku: last release in 2017, but adds latex support
• Bluecloth: last commit in 2011, nothing special
• kramdown: still actively supported
• CommonMarker: actively supported, supports all GitHub flavored extensions

I think that if we need to support multiple renderers, then supporting more doesn't hurt. But that said, perhaps we should drop rdiscount and BlueCloth since they don't seem to be maintained.