On how to index, serve and document latest versions of jslibs

[oleiade]

Problem definition

We recently had an internal discussion about a consistent issue that k6 engineers encounter over time when documenting jslibs. When writing the k6 documentation for jslib modules, we generally put together examples relying on specific versions. This means that for every new version, one must remember to update the examples to point to the newer version where relevant.

This is quite error-prone, and those errors could lead us to, in this event, document new features that the version used in the example doesn't offer yet.

Potential solutions

Some potential solutions for that have been discussed:

1. Having k6-docs (Gatsby) automatically fetch the latest version from this repo's supported.json file, and use it to replace any jslib module import's version.
2. Have the jslib repo automatically expose the latest published version of modules under a latest version:

import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/latest/s3.js';

Caveats

Some problems were, however, outlined with both these solutions:

• with 1. we would probably be able to replace it with the latest version on release. Moreover, we might want to have example keep using older versions under certain circumstances.
• with 2. if we expose a latest version, then users will allegedly always use that, which defeats the purpose of versioning
• with both and puts us at risk of breaking their scripts without realizing it.

Follow up

An alternative to the proposed solution could be to use same convention as Deno regarding dependency management.