Provide versioned sub-URLs

[WardBrian]

This is really more of a potential solution to #25 than a feature request it its own right, but it seems to me like the frontend website is small enough that it wouldn't be too onerous to keep older versions around under versioned urls like

https://flatironinstitute.github.io/mcmc-monitor/0.1.11/

That way if I leave my server running for a very long time, I have a URL which would continue to work even if an update is pushed in the meantime.

[jsoules]

Okay, I was reading this wrong--you are already proposing that we keep prior client versions available (which I think is the only way we'd realistically be able to make backward compatibility work).

We can probably do something like this (although the relevant feature would be the protocol version rather than the server version). It would be similar to the way we deploy to dev, we'd just modify the production-deployment script so that it deploys both to the main location and to the location that matches $PROTOCOL_VERSION.

I'm going to back-burner this for the time being, but it's a good idea and we'll probably want to pursue it.

[magland]

I like this idea. I would vote to use the sub-paths as Brian describes. And yes, it would be the protocol version (which changes very infrequently) rather than the package version. I wonder if we should make the protocol versions go p1, p2, p3, ... so they don't get confused with package versions. It will also make the URLs more concise and attractive.

[magland]

Should we attempt to enumerate the pros and cons of switching to sub-URLs?

pros:

• old versions of npm package (with earlier protocol) will still function
• deploying the main version will not wipe out other versions (including dev version)

cons:

• larger (and growing) data size on gh-pages branch - although we could manually delete very old versions
• if user bookmarks the website, that bookmark could become invalid with new upgrade of npm package (although user should get a message telling them what to do - basically they should follow the link printed in the console output of the running service)
• user may never be prompted to upgrade

[WardBrian]

I'm not sure the level of added complexity here, but cons 2 and 3 listed above could be handled automatically

• if the service responds with protocol p3, and your current url is /p2/whatever, re-directing to /p3/whatever seems reasonable to do.
• The web UI could have a message letting you know this isn't the most up-to-date version. In the Stan documentation, we do this by editing in an extra element for the version N pages when we release version N + 1, but you could also ping https://www.npmjs.com/package/mcmc-monitor or do something more dynamic

[magland]

If we do those things then in my mind the only remaining con is the first one I mentioned, which shouldn't be a concern if the protocol version does not change very frequently.

@jsoules what do you think?

[jsoules]

I agree with the pros.

Re: the cons:

• I think our total build size is around 4.5 Mb, most of which is react-plotly. We should probably try to optimize that at some point for performance reasons, but I don't think the storage on github is a huge challenge, especially if we don't change the protocol that often.
• I agree with Brian that user bookmarks should be handled through instructions/redirects on the page. We're halfway there with the "protocol doesn't match" notice, but that could be extended a little bit for more user-friendliness.
• I'm a little less clear on how to prompt the user to upgrade. The trick is that we don't want to have to manually modify the protocol-version-specific deployments when a new one comes out, so whatever we do needs to work automatically based on inspecting its own URI. The easiest thing to do would be to drop in a big "check for an upgrade" banner if they're using a protocol-specific link (i.e. base URI doesn't end in /mcmc-monitor), but people may start tuning that out. The alternatives involve the client responding to that trigger by checking some other URI, which I'm not super thrilled about. Pinging NPM could work, but the trick is that the server version doesn't necessarily reflect an updated protocol version. So I'm almost more inclined to just probe our own github-pages URI space, but that just feels brittle.

In general, I think the advantages outweigh the drawbacks.

[magland]

@jsoules , what do you think about changing protocol versions to p1, p2, ... as I suggested?

I suggest that to ping for upgrades we put a single file on the gh-pages branch: latest-protocol-version.txt We could edit that manually when protocol version changes.

[jsoules]

Re: protocol version numbering, I don't have strong feelings, but I agree that full semantic versioning isn't really appropriate for the protocol version when the only changes are going to be breaking changes.

Checking a latest-protocol-version.txt (with a hard-coded location) could work. Might it trip up people who are developing on their own branches? I'm not super concerned about that at this point though.

[magland]

Checking a latest-protocol-version.txt (with a hard-coded location) could work. Might it trip up people who are developing on their own branches?

No because it would just be a single file on the gh-pages branch only

[jsoules]

No because it would just be a single file on the gh-pages branch only

I was thinking in the case that they might be developing a newer protocol or otherwise targeting something other than the current official protocol version. But I guess it's just displaying a warning anyway.