Roadmap to 1.0

[jgaskins]

We've had some changes lately and a few new features are incoming (see my blog post), but I just wanted to have a place to discuss the features we're looking at to be able to release a 1.0 beta.

• Server rendering (Server rendering #20)
• Hot loading in development
• Trimmed-down JS payload (Remove opal-browser dependency #32)
• Referencing rendered DOM nodes (Add DOMReference class #35)
• Black-box nodes (Add BlackBoxNode #34)
• Documentation that's better than our current README

These features may also be worthwhile:

• Routing/history support for IE <= 9 (comment on #31)

I've already gotten code written for all of the features except docs, but I'm looking for critique. Do these features seem reasonable?

If you can think of other features that should be implemented or bugs that should be fixed before 1.0, please post issues (unless there is one already) and mention them here and I'll update the list. We're going to treat this as the meta-issue for all things 1.0, so once all the requisite boxes are checked and we've agreed that they're all the features we need for 1.0 (by "we", I mean anyone interested in the future of Clearwater that wants to chime in here), we'll release a beta.

[jgaskins]

I think it might be a good idea to push the hot-loading feature out into its own gem simply because it depends on a gem to run a websocket server and another to listen to the filesystem for changes. It seems like a lot of unnecessary dependencies if you're not using that feature and all you want to do is write a simple Ruby front-end app.

[wied03]

@jgaskins - Given MSFT's recent announcement, you might be able to get away with IE10/IE11 only.

[jgaskins]

@wied03 That's kinda what I'm hoping for. I don't want to complicate the router with fragment-based routing if we don't have to. I'm just not sure if IE8-9 will still be used even without Microsoft support.

Basically, if lack of IE8-9 support is stopping people from using Clearwater for their app, I'll probably add a fallback for it. Otherwise, I'm fine leaving it out. :-)

[jgaskins]

I spent some time on the IE <= 9 routing support over the past couple days, trying to dynamically choose between the location.hash and the history.pushState APIs. Turns out, you can't remove the location.hash portion. You can only set it to an empty value — which doesn't remove the # from the URL, and that's ugly.

I guess we could just provide a Clearwater::HashRouter class that trades out history.pushState(...) with location.hash = .... This would be a relatively small change, wouldn't break backwards compatibility, but would require the developers of a Clearwater app to determine whether they need to support the hash.

[jgaskins]

I merged in #20 last night and everything looks okay, which is great considering I've done very little to keep it updated since I originally submitted it. I'm able to navigate around a server-rendered Clearwater app with JS disabled, which is a little mind-bending.

[johnsusi]

@jgaskins is there any specific part that needs testing or documenting that I can help with? I think my webpack doc is already a bit outdated and it should be removed. We don't use it anymore.

Otherwise I think clearwater is stable enough to be 1.0. We use it in production since a few months back and have had no issues (related to clearwater ;-) )

[jgaskins]

@johnsusi I agree, 1.0 should've been released months ago. I've been working on too many other Clearwater-related things and not enough on docs. I'm just so bad at writing them. :-)

I've got a meta-issue on the Clearwater docs repo to highlight things that need to be worked on: clearwater-rb/clearwater_docs#1 Specifically, I think design and API-level docs are the most urgent if you'd like somewhere to start.

I built a Markdown parser (based on marked.js) that emits Clearwater components that I thought we might be able to use to streamline the process:

• Write up the docs pages in GitHub issues/PR bodies
• Copy the raw markdown into a component for that page

That's a much better than hand-writing Ruby code for what basically amounts to static content. Plus, I think we'll want a Markdown gem in the Clearwater ecosystem anyway for people wanting to render dynamic text blobs.

I'll publish the parser as a gem and bring it into the docs site. Until then, if you'd like to help document some things, the writing is the hard part (for me, anyway), so I'd be ecstatic if you were able to post issues for any content listed on the meta issue that need it.