Decide what goes into Datasette 1.0

[simonw]

Datasette ASGI #272 is a big part of it... but 1.0 will generally be an indicator that Datasette is a stable platform for developers to write plugins and custom templates against. So lots to think about.

[simonw]

I've made a lot of progress towards this recently:

• Started internals documentation Documented internals API for use in plugins #576
• Improved design of the request object Documentation for the "request" object #706
• Redesigned register_output_renderer plugin hook Redesign register_output_renderer callback #581

[simonw]

Goals for Datasette 1.0:

• Generally signify confidence in the quality/stability of Datasette. I think I'm there already.
• Plugin authors can have confidence that their plugins will work for the whole 1.x release cycle
• Developers building against Datasette JSON APIs should have confidence in 1.x compatibility
• Template authors and CSS theme authors should have that confidence too

I think I'm very nearly there for the plugin API. The harder ones are JSON APIs and template authors.

For JSON APIs: The default JSON just isn't right. I find myself using ?_shape=array for almost everything I build.

The template part is harder. I think I need to fully document the template variables for every view - and add protective unit tests that match that documentation.

The CSS theme part is so hard it may not be possible. How do you guarantee stable HTML that won't break with custom CSS when you'll be adding new features during the 1.x release run? The pattern portfolio from #151 should hopefully help a lot there, but I still don't have a complete idea of what this entails or how feasible it is.

[simonw]

I think I've figured out what to do about stability of the HTML and the default templates with respect to semantic versioning.

I'm going to announce that the JSON API - including the variables made available to templates - should be considered stable according to semver. I will only break backwards compatibility at that level in a major version release.

The template HTML (and default CSS) will not be considered a stable interface. They won't change on bug fix releases but they may change (albeit described in the release notes) on minor version bumps.

Since the template inputs are stable, you can run your own copy of the previous version's templates if something breaks.

This means users (and plugin authors) who make changes to the default Datasette UI will have to test their changes against every minor release. I think that's OK.

If you write plugins that don't affect the Datasette HTML UI you will be able to expect stability across minor version releases.

[simonw]

I'm happy with this as the goals for 1.0. I'm going to close this issue and create three tracking tickets for the three key themes:

• Datasette 1.0 JSON API (and documentation) #1509
• Datasette 1.0 documented template context (maybe via API docs) #1510
• Review plugin hooks for Datasette 1.0 #1511