Possibly wrong version in the tremor installation instructions- errors and potential fix also included

[devskillz47]

Problem
The current installation instructions (on https://www.tremor.rs/docs/0.12/getting-started/install) point to tremor 0.12.0-rc.2 and although "tremor run server" seems to work not all associated libraries seem to have been included which make at least the demo scenarios unrunnable (ie. error message: "Module tremor::connectors not found or not readable error")

Steps

1. $ wget https://github.com/tremor-rs/tremor-runtime/releases/download/v0.12.0-rc.2/tremor_0.12.0-rc.2_amd64.deb
2. $ sudo apt install libatomic1
3. $ sudo dpkg -i tremor_0.12.0-rc.2_amd64.deb
4. running the basic demo scenario from (https://www.tremor.rs/docs/0.12/guides/basics):

• tremor run passthrough/main.troy will fail with the above mentioned error (ie. Module tremor::connectors not found or not readable error)

Possible Solution(s)

1. change the installation instructions to download and install the 0.12.0 library version:

• $ wget https://github.com/tremor-rs/tremor-runtime/releases/download/v0.12.0/tremor_0.12.0_amd64.deb

2. $ sudo apt install libatomic1
3. $ sudo dpkg -i tremor_0.12.0_amd64.deb

Notes

1. The 0.12.0 tremor version will install correctly both using dpkg and by unpacking the .tar.gz library(tremor-0.12.0-x86_64-unknown-linux-gnu.tar.gz) and running "tremor" from within the folder
2. The 0.12.4 tremor version will install correctly using dpkg but unfortunately, the packaged version (tremor-0.12.4-x86_64-unknown-linux-gnu.tar.gz) is missing some dependencies or configuration and won't work correctly.
3. No executable or packaged library was found which would work directly in windows although the above commands do work in WSL

Output of rustup --version:
rustup 1.27.1 (54dd3d00f 2024-04-24)
info: This is the version for the rustup toolchain manager, not the rustc compiler.
info: The currently active rustc version is rustc 1.81.0 (eeb90cda1 2024-09-04)

Output of rustup show:
Default host: x86_64-unknown-linux-gnu
rustup home: /home/devskillz47/.rustup
stable-x86_64-unknown-linux-gnu (default)
rustc 1.81.0 (eeb90cda1 2024-09-04)

Output of tremor --version:
tremor 0.12.0

[darach]

Hi @devskillz47,

Well spotted and thank you for reporting - this is a indeed documentation bug.

In the edge versions we should always refer to the latest version. We currently refer
to a 0.12 release candidate.

In published versioned docs, we should refer to the version relevant for that published version.
This is also broken and not referring to the latest version in that release.

TL;DR We don't have automation around that so human error creeps in - and it tripped you up! Apologies!

A lot can change in tremor between release candidates and a release.

In rc.2 for example, it should actually be importing troy::connectors. Here's what I get with the docker image
which is a quick way of getting to a specific version:

 docker run -it --entrypoint=/bin/bash tremorproject/tremor:0.12.0-rc.2
Unable to find image 'tremorproject/tremor:0.12.0-rc.2' locally
0.12.0-rc.2: Pulling from tremorproject/tremor
1fe172e4850f: Pull complete
0f7a09356ab2: Pull complete
9ed9fd0da9cf: Pull complete
9f2b1af0c7af: Pull complete
f369d1d5546c: Pull complete
0a2e9637503d: Pull complete
773923c4a5cb: Pull complete
04d0ceeebaee: Pull complete
4ad7c67c1aed: Pull complete
5c80e7df2a62: Pull complete
Digest: sha256:54bae6b1f64c030086bbc1b083daedc8c5d1725093e76b1571744e1fa26505be
Status: Downloaded newer image for tremorproject/tremor:0.12.0-rc.2
root@b35f93c5d432:/# which tremor
root@b35f93c5d432:/# echo $TREMOR_PATH
/usr/local/share/tremor:/usr/share/tremor/lib
root@b35f93c5d432:/# cd /etc/tremor/
root@b35f93c5d432:/etc/tremor# ls
config	logger.yaml
root@b35f93c5d432:/etc/tremor# ls config
docker.troy
root@b35f93c5d432:/etc/tremor# /tremor run config/docker.troy
{"onramp":"metronome","ingest_ns":1732106045142393814,"id":0,"hostname":"b35f93c5d432"}
{"onramp":"metronome","ingest_ns":1732106046142596015,"id":1,"hostname":"b35f93c5d432"}
^C

And the interesting part:

 cat config/docker.troy
define flow docker
flow
    use troy::connectors; # Notice the different module namespace
    use troy::pipelines;
    use std::time::nanos;

Fixes in the docs would be of the form:

• Fix edge version to use latest - perhaps our release needs to have a rolling latest tag we can refer to
• Fix versioned docs so that each major version refers to its latest minor/patch release version
• Question - how do we automate this to remove human error ( we're human and we'll forget )?
• Check that TREMOR_PATH is introduced and set appropriately for the wget based install instructions

[devskillz47]

For fixing the documentation, I think we could use the 2nd option you mentioned- fixing the versioned docs so that each major refers to its latest minor/patch release. From a stability point of view, the latest minor/patch release of a major should always be correct and working so there shouldn't be any problems.
From an automation point of view, I am not sure. A rolling latest could be the easiest solution but I'll also have a look around maybe I can find some info on how other software projects have solved the problem (ie. java, scala, python, etc)