Forwards compatibility (error handling)

[benjaoming]

The overall question is how do static websites work in 5-10 years and how many legacy APIs do we expect to be around by then.

The solutions are perhaps found in some sense of user-oriented error handling.

• Does the API respond? What if it doesn't?
• When were the docs generated (at what date)? Do we have a customized message in case docs are really old and the API isn't around?
• Can the version warning banner help?
• Are reasonable fallbacks possible? What reliable resources can help when others are failing? For instance, a link to the "latest version" or the project's page on Read the Docs?

readthedocs/readthedocs.org#8323 is an example of assumptions that may have broken after 5-10 years.

This is possibly pretty low priority, just wanted to post these thoughts somewhere :)

[humitos]

This is a great topic to talk about! In fact, @agjohnson and I talked about a "potential idea" yesterday that could work, but it needs more thinking:

1. there is one base javascript injected
2. this code hits the API endpoint (and other resources required for the js client to work)
3. based on those responses (data structure, etc), the base script decides which version is the supported one
4. it downloads that particular version
5. if the downloaded version fails to work for any reason (e.g. raise js exception); it fallback to the version of the js that was "the latest version at the time when the documentation was built" ¹

This allows us to do 2 things we want to do:

1. do not break old documentation
2. deploy new features to old documentation

Footnotes

1. we need to store this date in the database and expose it via the API response. ↩

[agjohnson]

Also another failure case here is if the user stores something like JS or an HTML template in the built documentation and then our library's implementation changes somehow. It does seem like we want some way to be explicit about the version of the library being requested somehow.

[humitos]

It seems we had an on-going conversation about versioning the flyout at https://github.com/readthedocs/meta/issues/96 as well. So, I'm linking it from here so we can find it again when we continue talking about these topics.

[humitos]

We are moving forward with this in some way. We added a HTTP header with the version of the client itself that all the js fetch functions send to the API server. The server will have all the scheme responses versioned and will decide, based on that HTTP header, what's the JSON structure that is compatible with the client making the request. This work is happening in readthedocs/readthedocs.org#10216