Versioning oriented at distribution-packaged VisiData versions

[koernepr]

It would be nice if the tutorial was (semi-)versioned; currently it would be helpful for example if the tutorial for VisiData 1.5.2 was still accessible via Read the Docs.

According to the Read the Docs documentation, it is possible to have different versions of the documentation based on tags or branches.

To make the 1.5.2 tutorial available, it might be sufficient for example to create a branch, e.g. v1.5.x or v1.5.2, at commit ed14f19 (parent commit of 8075174). Using branches instead of tags would probably have the advantage that you could improve old versions of the tutorial if needed. Regarding the 2.x tutorial, I don't know if any additional branches would be needed currently; a v2.2.x or v2.2.1 one might make sense in the future, given the packaged versions and depending on future VisiData and tutorial changes.

If you introduce this, it might also make sense to enable the version warning to prevent people from accidentally following the wrong tutorial.

Also: Thank you very much for the great tutorial :slightly_smiling_face:

[saulpw]

Since the interfaces aren't that different, is it better to version a tutorial by having a completely separate document? Or to add side notes like "The foo-bar command was added in v2.0" or "In v1.5.2 and earlier, the bar-baz command required an input"? The former is easier to implement, but may be more work to maintain.

[jsvine]

Thanks for the idea, @koernepr, and thanks for the input, @saulpw. I'm open to either proposal, though I'm somewhat hesitant to add complexity to this project. VisiData, to me, seems like the kind of software that's best kept updated, with little need to use earlier versions (or cost-prohibition to upgrading). I also feel like VisiData.org does a good job highlighting major changes / major releases.

So I'd be curious to know: What use-cases would versioning the tutorial solve?

[koernepr]

It would simply be helpful if

• a user of an older (distro-packaged) VisiData version could read the matching tutorial
• when recommending VisiData to such a user, one could refer to the matching tutorial without any disclaimers like "some parts might not match the version you're using"

Since 1.5.2 and 2.2.1 currently are the packaged VisiData versions in multiple Linux distributions (see the link above), it would probably make sense if currently the tutorial matching the 1.5.2 release was available in addition to the "rolling" version; as soon as there are bigger tutorial changes for versions newer than 2.2.1, you could then also make the tutorial version as of 2.2.1 available. Having a tutorial version for every VisiData version might even be better of course, but I don't think that's worth the effort :slightly_smiling_face:

Please note that I didn't want to suggest that you actively maintain these additional versions, but simply to make the best-matching tutorial versions for 1.5.2 and (in the future) 2.2.1 available on Read the Docs; this requires of course that you are happy with these "old" tutorial versions ... Using branches as suggested would nevertheless make it possible to fix bigger issues in older versions if needed. If I'm interpreting the RTD documentation correctly, the effort for creating the 1.5.2 version of the tutorial for example might simply be a git branch v1.5.2 ed14f19 followed by git push -u origin v1.5.2.

The alternative suggested by @saulpw would of course mean that all "versions" of the tutorial would benefit from improvements, but adding and also reading these version-specific notes might get cumbersome in case there are more than only a few (?)

[jsvine]

Thanks @koernepr! That's very helpful context, and I appreciate it.

One point of clarification: Although the tutorial uses RTD's Sphinx theme, it is not actually hosted on RTD, and so cannot currently take advantage of the feature you mention. (It does sound neat, though.)

One intermediate solution would be, as you suggest, to create the relevant git tags, allowing people to download the appropriate commit-state for a given version. Viewing the tutorial locally would then be as simple as make serve. Not as quick as being able to point someone to a version-specific tutorial URL, but hopefully still useful.

[jsvine]

Update: I've now created a couple of tags, pointing to the latest commits applicable to key prior versions VisiData (1.5.2 and 2.0.1): https://github.com/jsvine/intro-to-visidata/tags

Note: I haven't updated the tutorial for every published version of VisiData, so there won't be a tag for every VisiData release. Next update will probably/hopefully target VisiData 2.3.

[koernepr]

Heh, fooled by the theme (and RTD's custom domain support used by other projects) ...

Thanks for the tags; hosting the different tutorial versions directly would still be preferable as you also pointed out, but if that's too much effort, the tags are a good start already :slightly_smiling_face: