Updating Cerebral

Related to release we also have to decide on strategy of updating Cerebral after the release.

After a discussion with @reflog and his work on the debugger “self-update” functionality I realized that we are in a unique position to handle updates to Cerebral in a more predictable way.

The challenge with Cerebral, which we painfully experienced during alpha and beta is that packages depends on each other, also the debugger depends on specific version of Cerebral. When you update one package it might break because of a different package, the debugger does not display because Cerebral was updated, or the opposite.

I suggest we favor a strict and predictable approach to handling Cerebral updates, using the debugger as a “vessel for driving updates”. This is how it would work:

1. We have prepared a new release branch containing some fixes
2. We merge the release branch into master, which triggers the publishing flow
3. Absolutely all packages, including debugger, will be updated with the same version number. Even though they did not have any updates
4. When developers fires up the debugger it will notice there is a new version of it, which we display as: “Cerebral has been updated, please follow these instructions and click here to update the debugger. Or we can remind you about this later”

“…please follow these instructions…” is a link to the website. It basically explains how you bring your current Cerebral dependencies up to date, using npm update and whatever.

With this approach we are in a unique position to nudge developers into having their dependencies up to date and not running incompatible versions of packages.

And a final note. Cerebral will pass its current version to the debugger when connecting, meaning that debugger can match that with its own version, giving a warning that the connected Cerebral app is “out of date” and debugger functionality can not be guaranteed.

[christianalfoni]

Okay, so to try out a conclusion summary here 😃

This is required for release:

1. Merge in “self update” feature to debugger (@reflog has done really amazing work here)
2. Implement Cerebral and Function-Tree sending their version numbers to the debugger
3. Move debugger to own repo

After release:

1. Debugger protocol is really just websocket messages with these props, as example: {version: '1.0.0', source: 'c', type: 'execution', data: {}} This is unlikely to change, but if it does a completely new build of debugger will be required

2. Changes to messages sent from Cerebral/FT to debugger all contain version, meaning that we can feature check when necessary inside Debugger, making it backwards compatible

3. We depend on NPM/Yarn peerDependency information, but if developers starts getting into trouble or we have problems giving support, we need to take some measures. I might be colored by our experiences running alpha, cause NPM had a hard time understanding the versions there

4. At any time the latest set of packages should be compatible with each other

5. To help moving people to latest version of Cerebral we can use current fallback update implementation to rather check Cerebral for new version and give a “Hey, did you know Cerebral has been updated?” type of thing

[christianalfoni]

Hm, so to summarize:

1. We want to publish packages independently
2. We do not want developers to be confused by what package versions belongs to what version of Cerebral
3. We want developers to be notified about new updates by the Debugger to encourage running on latest versions
4. We want developers to have multiple versions of Cerebral, that is not necessarily compatible with the same version of the debugger… but running in the same debugger experience

This is a tough order 😃

Individual version bumping

This has the benefit of fixes related to one package does not affect the versions of other packages, meaning developers will not need to unnecessarily update all packages if just one package had a breaking change. The problem though is that package versions will most likely not make sense as a whole, making it harder to do support and as a developer understand what versions of packages correlate to your Cerebral version.

Major version bumping

This has the benefit of being explicit about what versions of related packages fits with your current Cerebral version. 2.x.x packages fits with 2.x.x Cerebral. The problem though is that if one package has a breaking change, all packages, including Cerebral will need a major bump.

Notifying updates from debugger

The benefit of this is helping developers work on latest versions. Personally I have never been able to keep up with versions… not written npm update once in my life. With “major version” bumping we would be able to notify about breaking changes to any package, including Cerebral itself. With “individual version” we can only notify update to the debugger itself.

Handling multiple Cerebral version in same debugger

So this one is very difficult to handle. We did handle this in Cerebral 1 debugger, but we only handled one app at a time. Now we handle multiple apps, meaning that we can not reload the entire debugger when some Cerebral app connects that requires a different version.

The fact that the debugger is used by function-tree in isolation as well does not make things easier. Because some functionality is Cerebral specific, while other is function-tree specific.

My reasoning

I am just pushing hard on the developer experience and I do not think “independent mode” makes Cerebral a better developer experience. It makes it harder to do support and understand how packages relate to each other for the users. I totally see that bumping major on a related package causing bump on Cerebral itself and debugger is unnecessary from a technical standpoint, but from a developer experience standpoint I think it makes a lot of sense. Because we drive updates from debugger that way and major numbers always fit.

The debugger has a general API for sending and receiving messages now. Making changes to these messages and the UI of the debugger can be handled with feature checking, rather than lazy loading complete instances of the debugger. Basically what I means is:

Cerebral sends its version to debugger. The debugger evaluates what features are available for that version and activates components. We could state the version number on TAB and you would know also there what version all the other packages should be.

I understand the argument of independent mode, but I do not see the gain in developer experience? Or is there something I am missing here? 😃