Go tutorial and reference

[javierdelapuente]

• Have you signed the CLA?

---

Adds a tutorial and reference docs for the Go extension

[jdkandersson]

Looked at the tutorial, I think it is a good start

[jdkandersson]

A lot of the other tutorials demonstrate how to update the application? I think this is fine to include perhaps as another step since we don't have the chisel anyway?

[javierdelapuente]

replied in the next comment.

[jdkandersson]

Hmm, I don't follow why we would suggest the user does this?

[javierdelapuente]

I did this because I think it is one of the pain points of the extension. Many Go projects have the binaries under cmd/, sometimes being one the server and the other ones could be for example command line tools.

I put this example to show how to use another binary, and at the same time how to "update" the application, put another version of the rock... Would you suggest another different example to update the app?

[jdkandersson]

Perhaps that can be a separate how to. I would suggest just showing perhaps adding another endpoint like the time endpoint on other tutorials

[jdkandersson]

I think the tutorial doesn’t flow, it doesn’t make sense at least to me that I would want to add another binary at this point, I probably would just want to add some features

[javierdelapuente]

sure, let me try that way (adding another endpoint) and I will leave that part for a how-to (I think it is important).

I will copy the flask endpoint in Go

[javierdelapuente]

Done!

[jdkandersson]

Could we caveat what we mean by this? E.g., for debugging it might be better to use but for production we recommend bare?

[javierdelapuente]

I have rephrased it a bit. I think it is a bit clearer now.

[jdkandersson]

perhaps rename this to main-time.go so that the editors recognise it as a go file?

[javierdelapuente]

I did not use the .go extension because otherwise it will be compiled (and will fail).

[jdkandersson]

Ah ok makes sense

[IronCore864]

As a relatively new user, I tried to follow the tutorial but failed (there isn't a go-framework profile). But I still read through the tutorial thoroughly. There are some nitpicking comments, but mostly are my thoughts on naming consistency and content organisation. See comments inline.

[IronCore864]

I know this is a piece of existing reusable content and not in the scope of this PR, but in reuse/tutorial/setup.rst, it says in the beginning that "We recommend starting from a clean Ubuntu 22.04", but in the command below when launching a multipass instance, it used 24.04. It's better to be consistent.

And, is 22.04 going to work or not? If I already have a 22.04 VM (maybe not multipass), will it work? Must rockcraft work together with multipass and LXD, or it can work alone? Do I have to create a new VM for this tutorial and do I have to use multipass for it?

Tutorials are for new users, who might not have a comprehensive understanding of the prerequisites: What is multipass? Why do I need a VM to build an OCI image, because Docker doesn't require a VM to build an image? These are the questions a new user (I am speaking from a new user's standpoint, in fact, I am a new user, and I have only used rockcraft once during my onboarding process) might have in mind when following the tutorial.

The sheer cognitive load would scare a new user away: They have to figure out what multipass is, what LXD is, why LXD has connection issues with Docker (which is a whole separate document linked in the tutorial), why I need Docker since rockcraft can build an OCI image, why would I use rockcraft to build an image since Docker is required anyway, etc.

I think if the setup is a whole lot easier (for example, brew install rockcraft on mac, apt install on Debian, then init, pack, done), it would attract more new users.

[jdkandersson]

I think it is a good point, we should remove the reference to which version of Ubuntu we start with from the shared setup

[javierdelapuente]

Yeah, I have removed the version of Ubuntu, now it is something like:

we recommend starting from a clean Ubuntu installation. If we don't have one available, we can create one using Multipass

so also it it a "bit" clearer than Multipass is not required, and the requirement is Ubuntu. By the way, one of the reasons for Multipass is to be able to run the tutorial in macOS/Windows operating systems (rockcraft requires a Linux distribution with snapd installed).

[rebornplusplus]

we recommend starting from a clean Ubuntu installation

Why do we need a clean installation though?

[javierdelapuente]

We recommend a clean installation (clearly, it is not a requirement). Frankly, while there are issues with docker, I think it is a good recommendation...

[IronCore864]

Nitpicking: "You may need a new terminal for this" -- you definitely need a new terminal for this since the go-hello-world is a long-running process and when starting it, we didn't put it in the background. Might need some rewording here.

Also: "if you are using Multipass" -- we are using multipass, as specified clearly in the setup section.

[jdkandersson]

I think the reason I originally chose may rather than will is because there are other ways a user could test this. I do agree we can probably just write will here, and can also fix up the rest of the tutorials

On Multipass, it is not guaranteed they are, we suggest using it

[IronCore864]

In this section, all the docker commands run with sudo, which I think isn't the best idea. Maybe we can do this properly by creating a docker group and adding the current user into that group following this doc?

[jdkandersson]

Sounds reasonable, we can probably do that in the shared setup instructions

[javierdelapuente]

I have updated to use docker as a regular user. I have not updated the rest of tutorials (basically all of them). I would rather do it in another PR.

[IronCore864]

This is the very first occurrence of "pebble" in the whole rockcraft doc website: It doesn't show up on the home page, it doesn't show up in the first two tutorials, either.

Following the doc's structure, I would read the homepage, follow the first two tutorials, then follow the Go tutorial because other languages don't interest me, and bam, I met the term "pebble", and it's confusing: What is pebble?

Although there is a link, but again, this adds cognitive load for a tutorial that is supposed to be simple, as simple as building and running an OCI image.

Even if the user is already familiar with pebble or switched to the pebble doc and then back, they would still have a question mark: I already built an executable binary, why can't I just add it in the OCI image and run it, why would I need a service manager for a single executable?

[jdkandersson]

I think we can link to information about pebble, I don't think we should get into the details of explaining pebble here. We should update the rest of the tutorials as well

[javierdelapuente]

I updated the tutorial so the first reference to pebble has the link. I do not think pebble will be a hurdle for the user here, as the user can just gloss over it (and run the command and see the logs). It they want to have more information about it, there is no other options except reading the docs (and explaining it here will make the tutorial complex).

[IronCore864]

I find the cleanup section in the middle of a tutorial a little weird. I read "cleanup" then immediately "update go application" -- if I'm still working on the app, why do I need to clean it up now? The next step builds the image with a different tag anyway. I think it's better to keep everything that is cleanup together at the end, simply delete the multipass VM which is created in the setup section. And we can make the cleanup section as a reusable content and use it in other tutorials as well.

[jdkandersson]

The reason is that when we run the next image it will use the same port. I do agree we should just have this without necessarily a cleanup title and just stop the container and remove the image. We should update the rest of the tutorials as well

[javierdelapuente]

I have updated the title to be "stop the application" instead of "cleanup". We need a title as the previous one is "View the application logs". The alternative is to put it into the "update go application".

[IronCore864]

"If you created an instance using Multipass" -- I did create an instance with multipass, it's the only option provided in the setup section. Is there another option? If so, maybe we can enrich the setup part. If not, we can reword this, simply delete the VM is fine?

[jdkandersson]

I think it depends, some users don't want to use multipass

[javierdelapuente]

As a relatively new user, I tried to follow the tutorial but failed (there isn't a go-framework profile). But I still read through the tutorial thoroughly. There are some nitpicking comments, but mostly are my thoughts on naming consistency and content organisation. See comments inline.

Thank you very much for your review!. With respect to not being able to run it, it should be related to the need to refresh to the latest/edge channel (using for example sudo snap refresh rockcraft --channel latest/edge). The go-framework is not yet in rockcraft stable (it will be when the tutorial is in the stable readthedocs page).

[rebornplusplus]

Looks good to me, thank you!

Left only a minor nitpick. Feel free to ignore that. :)

[tigarmo]

Thanks! @medubelko can you please take a look at these new docs?

[tigarmo]

I feel like there's a jump here because 'hello world' code in Go does not typically start up an http server. Maybe some context like "The code in main.go starts up an HTTP server listening on port 8000, so we test it by using curl..."

[medubelko]

@javierdelapuente Thanks for providing this for us! I found the sequence of events quite easy to follow.

I've left quite a few suggestions because tutorials end up being very long documents. If we can close these quickly I can help merge the PR before the end of the week.

[medubelko]

For tutorials, it's important to communicate:

1. An estimated completion time.
2. What skills and knowledge the user ought to already have.
3. The new knowledge and skills the user will gain through completion.

It would be ideal if we could add such information here.

Here's the generic form I used in another product's main tutorial. Feel free to crib from it:

It should take [x] minutes for you to complete.

You won’t need to come prepared with intricate knowledge of software packaging, but familiarity with Linux paradigms, terminal operations, and [so on] is required.

Once you complete this tutorial, you’ll [accomplish x]. You’ll gain [skill or familiarity with y], and have the experience to [task or skill].

[medubelko]

Instead of linking here, I feel it would be better to simply instruct the user to run rockcraft clean prior to repacking the rock and remove this section. Even if clean isn't always required, it helps the reader build muscle memory of the commands they'll often need to reach for when iteratively building and testing.

[tigarmo]

thanks!