Versioning the docs per release

[flaki]

We should consider how to implement versioned docs (that is, release documentation in sync with Atmo / SCN releases). While making documentation versions for all (earlier) releases is certainly important and useful for many reasons, it comes with a couple important pitfalls that need to be mitigated. A few of these:

• Search engine index de-sync (people arriving at earlier versions of the docs when searching for something)
• Atmo + SCN versioning needs (what should be the version in e.g. the URL, sync version numbers across Atmo / SCN, how to refer to a specific release etc.)

[flaki]

Alternatively, we can consider tracking breaking changes to functionality (e.g. language support, Runnable API features etc.) in the docs until a consistent versioning is established (e.g. at 1.0).

[flaki]

Docusaurus's built in versioning support

[LauraLangdon]

At today's dev meeting, we decided to move forward with versioning the docs. I think I'd like pair with someone to get started on this since I don't have prior experience instantiating versioning, and I've added to this next week's docs meeting agenda.

[flaki]

I'm afraid the issue is less on the documentation side here, but more on the dev side (and particularly on Reactr's side).

The main issue is that we don't have a common agreed-upon and documented versioning strategy, afact! Such versioning strategy should talk about how are various things (such as Reactr, the Runnable APIs in Reactr, public facing interfaces and APIs of Atmo, Sat, SCN's APIs) are versioned, what dependencies exist in-between, how often are new versions released, what constitutes to breaking changes and more.

Once we have this information, we may start versioning the docs - either on their own, layering on a versioning scheme that then is linked to all these tool versions (e.g. Docs 1.0.3 - updates related to Reactr 15, SCN 3.4, dis and dat...). Or we can just pin the docs to a given tool version.

These cross-references and pinning is important because we want the docs - the APIs, the guides, the code snippets - to correlate with the actual tool versions and ensure that they work. Then, when (inevitably) a backwards-incompatible change is made to these tools, we:

1. want to be able to update the documentation, examples, code snippets etc. so that they work with the new version
2. if possible we want to keep the older documentation versions accessible so those, who are still using the older versions of these tools can still access them

[LauraLangdon]

From today's dev rel meeting notes:

• Oscar: lots of feelings
• Moving docs into into their own repo made tracking docs-up-to-date-ness harder
• Release cadence is going to be hard!
• Me & Connor has slightly different ideas
• Want to release early and often esp. for OSS
• Oscar: everything is, and will be semver!
• Connor:
  • maybe we will be able to release on schedule (OSS) but we are not there yet
  • we’ll try to do timeline estimates
• Being really transparent about the timeline, even if it can change
  • Jess: the planning should be visible
  • Oscar: we have a running log!
  • Flaki: using the running logs as fodder for content!
    • more comms between dev ↔ devrel here
• Flaki: do you have documentation on the versioning and interactions between the projects?
  • Oscar:
    • Planning to keep these fairly independent
    • Sometimes (e.g. security updates)
• Connor:
  • It’s not worth putting in the effort into versioning until General Availability
    • Hopefully this year for Reactr + Atmo