Roadmap Epic - ember-statecharts 2021

[LevelbossMike]

This issue is meant as a tracking issue for all the things we want to do in the near future. The plan is to make it transparent what things are being actively worked on and things that we feel will benefit the project in the mid-term. This issue can also be an entry point for people that want to help out with ember-statecharts but don't know where to start and give people an understanding of what we feel are the most important things to improve in the near future.

Roadmap

• Replace ember-cli-addon-docs documentation with docfy
  ember-cli-addon-docs has created problems for us and made it hard to upgrade the project to newer ember versions in the past. It doesn't feel like ember-cli-addon-docs is a future-proof way to document ember addons as it seems to have been pretty much abandoned and honestly has created more problems than it solves for us. Currently, ember-cli-addon-docs is blocking an upgrade Ember versions > 3.24.x which is very annoying especially because we are only using it as a dev-dependency for documentation and it is not something that is really needed for ember-statecharts functionality. - Use docfy - no more addon-docs. #355
• Test addon against embroider and make it embroider ready if it doesn't work for some reason
  We want to play nice with the upcoming way to develop Ember.js applications and have played around with embroider. Embroider is great and production-ready. We want to make sure ember-statecharts works with embroider as soon as possible but haven't had the time to check compatibility yet.
• declare XState a peer dependency of the project and don't pull it in as a dependency of the addon automagically
  The way we are bundling XState in the project as a dependency is an idiomatic way for an ember-addon but pretty weird in the greater scheme of things. We want to simply tell people that XState is currently a dependency of ember-statecharts and that people need to pull it into their project to use ember-statecharts. Declaring XState a peerDependency should be good enough for this use-case and as far as I understand is also the way that embroider would expect addons to be setup.
• use ember-could-get-used-to-this over ember-usable
  ember-could-get-used-to-this is the new version of ember-usable. We want to use this in host applications that are using Ember.js > 3.25. To make this work we need to refactor the way we are creating the usable. This will add a very small burden on current users of the addon where they will need to change the way they are invoking useMachine slightly when upgrading to an ember-statecharts version that uses ember-could-get-used-to-this. We want to provide a codemod for the switch to make it easy for people to upgrade. This is a minor refactor but is currently blocked by ember-cli-addon-docs. Thanks @NullVoxPopuli for his first spike on this!
• switch CI to github-actions
  Travis doesn't seem like a future-proof way to do CI for open-source projects. Github actions works well and we want to switch to it over TravisCI
• add a more complex example of how to use ember-statecharts in a "real" Ember.js application by writing an example application that is very similar to Xstate's Reddit API-example
  To make it easier for people to understand how powerful statecharts are in the context of building an Ember.js application and how to make use of XState's concepts when you are working in the context of an Ember.js application that provides primitives for global application state, routing etc.
• add proper API documentation based on Typescript types
  We want to document ember-statechart's API surface properly based on the typings we already have in the project. We might be able to leverage https://typedoc.org/ to do this. There's also @josemarluedke's https://github.com/josemarluedke/glimmer-docgen-typescript that we might be able to take inspiration from.

Summary

@pangratz and I have big things planned for this addon this year and are very excited to make it even easier to use statecharts in Ember.js applications 🚀. Please let us know your thoughts on the roadmap and questions if things are unclear or you want to jump into helping with ember-statecharts but don't really know where to start.

[SergeAstapov]

@LevelbossMike have you considered to make xstate lazy-loaded? not sure how it will play with XState being peerDependency

[LevelbossMike]

@SergeAstapov not sure how embroider would handle this. should probably work based on route splitting - are you making use of this already today?