2.0.0 Release Checklist

[kirsle]

The alpha versions on npm should be code-complete and more or less working.

The git repo though needs to be cleaned up to update to the 2.0.0 version and remove any inconsistencies.

• [x] The documentation generator script needs to be updated to read the JavaScript sources because the CoffeeScript ones no longer exist. (PR #271)
• [x] All the examples in the eg/ directory need to update their use of reply() and the other functions that have broken backwards compatibility.
• [x] Other tickets in the v2.0.0 milestone
• [ ] Documentation for the 2.0.0 migration.
  • A stand-alone Upgrading Guide that details every single way the API has broken backwards compatibility and how to fix it.
  • An introduction to the new features that async/await brings and why users should bother upgrading to v2.

v2.0.0-alpha.5 is now live with all the critical features needed. After some time in the wild I'll move forward with final releases.

[dcsan]

so this is a breaking change? anything using reply() needs to be updated as r = await bot.reply() or we just get a promise back?

it might have been nicer to not break all the old code bases, for example adding a new method if the API signature changes. I have a few old bots in production that I don't really want to touch.

[kirsle]

For async/await, there was no choice but to break backwards compatibility. To use the await keyword, your function must be an async function, and those always return a Promise (even if you return a string, it wraps it in a Promise automatically).

And so the synchronous reply() function that just returned a string couldn't exist. The await keyword affects the whole call stack and it's Promises all the way up.

However, async/await in turn provides all sorts of benefits because now I can await in various places inside the reply and these things will be possible:

• Using an async object macro in a condition. i.e.,

  // assume the object macro runs an async http request
  // and returns a Promise with "true" or "false"
  + does * exist on wikipedia
  * <call>wikipedia exists "<star>"</call> == true => It does exist.
  - It does not.
  

  In v1.x of RiveScript you can't have an asynchronous object macro in a condition, because the bot needs the answer now because reply() was a synchronous function that couldn't wait. And now it can.

  This already works in the v2.0.0-alpha.* versions.

• It will be possible to swap out the user variable session manager (currently an in-memory JavaScript object) with one backed by Redis or MongoDB or anything else. Like the Python, Go and Java versions of RiveScript.

  • Similarly to the async <call> in conditions, user variables couldn't be async either. A single call to reply() would set and get user variables many times, sometimes the JavaScript code itself would, but sometimes your RiveScript code as well -- think <set name=<formal>><get name>. The reply() function couldn't wait around for user variables to be stored asynchronously before, and now it can.
  • #268 I intend to have the interface available (to provide your own object to fullfill the session manager functions) for v2.0.0 stable.

So the choices came down to either: delete the reply() function completely, because there's no way to make it work anymore, or just change it to return a Promise because that's the only thing it can do now.

[julien-c]

This is awesome @kirsle 👍

[dcsan]

OK understood now. it should be a great benefit and not such a big changes for us to make. thanks for the info!

[kirsle]

I've published v2.0.0-alpha.5 to npm now which adds the User Variable Session Manager interface.

Backwards Incompatible Changes

For the user variables to be async everywhere, all of their functions now have to return Promises.

If you are using these public RiveScript API methods to interact with user variables, these will now return their result as a Promise:

• setUservar(user, name, value)
• setUservars(user, data)
• getUservar(user, name)
• getUservars([user])
• clearUservars([user])
• freezeUservars(user)
• thawUservars(user, action="thaw")
• lastMatch(user)
• initialMatch(user)
• lastTriggers(user)
• getUserTopicTriggers(user)