Reason: instructions in the link above are not clear for new users.
Validation: Tested on 2 new users, they got issues (failed to use the tool as a result) with following current instructions.
OS - SUSE Tumbleweed, Ubuntu.
Rationale:
1 - not obvious how to install/run nbe.
2 - as users are not aware of details of realization of nbe, they can easily miss the right order of installation/run steps.
Especially with info about Docker/Compose dependencies AFTER info about the tool itself.
E.g., missed installation of Docker Compose will lead to error with pull image. Compose is a separate package in many package managers, it is not proposed to install with docker.
Proposed text is below (feel free to adapt it, I used what tested with users and worked):
“When you want to actually execute the example code, you need:
Clone this repository.
Download the nbe CLI, extract binary to the root of the cloned repository.
Currently, the nbe CLI needs Docker and Compose (v2+) to work. It runs a set of containers hosting the CLI client and the NATS server. Other container runtimes would be considered if requested (such as Podman).
Install Docker and Compose (if you do not have them installed).
Make sure that docker is installed and up, with command:
$ sudo systemctl start docker
Run the command with an example you want to try at the root of the repo:
For example:
$ sudo nbe run messaging/pub-sub/cli
This will run the NATS CLI implementation of the core publish-subscribe example in a set of containers. If everything is ok, you will see this output in console (timestamp will be different):
09:17:59 Published 5 bytes to "greet.joe"
09:17:59 Subscribing on greet.*
09:18:00 Published 5 bytes to "greet.joe"
[#1] Received on "greet.joe"
hello
[#2] Received on "greet.pam"
The name of the example corresponds to the directory structure under examples/, specifically //.
Have questions, issues, or suggestions? Please open start a discussion or open an issue.”
With this instruction 2 users finished tasks for installation and run examples without errors with expected result.
Hello, I would like to propose to improve this block: https://github.com/ConnectEverything/nats-by-example/?tab=readme-ov-file#getting-started
Reason: instructions in the link above are not clear for new users. Validation: Tested on 2 new users, they got issues (failed to use the tool as a result) with following current instructions. OS - SUSE Tumbleweed, Ubuntu.
Rationale: 1 - not obvious how to install/run nbe. 2 - as users are not aware of details of realization of nbe, they can easily miss the right order of installation/run steps. Especially with info about Docker/Compose dependencies AFTER info about the tool itself. E.g., missed installation of Docker Compose will lead to error with pull image. Compose is a separate package in many package managers, it is not proposed to install with docker.
Proposed text is below (feel free to adapt it, I used what tested with users and worked):
“When you want to actually execute the example code, you need:
This will run the NATS CLI implementation of the core publish-subscribe example in a set of containers. If everything is ok, you will see this output in console (timestamp will be different):
09:17:59 Published 5 bytes to "greet.joe" 09:17:59 Subscribing on greet.* 09:18:00 Published 5 bytes to "greet.joe" [#1] Received on "greet.joe" hello
[#2] Received on "greet.pam"
The name of the example corresponds to the directory structure under examples/, specifically//.
Have questions, issues, or suggestions? Please open start a discussion or open an issue.”
With this instruction 2 users finished tasks for installation and run examples without errors with expected result.