executable tutorial: nixpgs for reproducible environments

[MateusMarinheiro]

Assignment Proposal

Title

Nixpkgs and its use for reproducible environments for better local testing.

Names and KTH ID

• Arber Limani (arberl@kth.se)
• Mateus Marinheiro (mateusma@kth.se)

Deadline

• Task 3

Category

• Executable Tutorial

Description

We will give a brief overview of the Nixpkgs syntax as well as its benefits while teaching how to apply it to real world scenarios. We will also provide a guide on how to change your environments to test your code locally before committing it to your repo.

Relevance

It is very important to test your code before you submit it, even if there are CI actions in place. As a team starts to grow, different developers with different machines with different environment states. It is therefore essential to ensure that even if machines have different configurations the result of testing should be the same.

[marcocampione]

Me and @t-sorger are interested in giving feedback on this executable tutorial. Do we have to wait until the pr is merged to open a feedback pr? Thank you in advance for the answer ✌🏻@algomaster99

[algomaster99]

@marcocampione Hi! I am not sure if the feedback comes after or before. I only know the point of feedback is to get incorporated later on.

@Deee92 do you know when is the feedback task proposed? Before or after this exec tutorial is merged?

[Deee92]

Hi @algomaster99, the feedback proposal comes after we merge the task proposal PR.

[marcocampione]

Hi @algomaster99, the feedback proposal comes after we merge the task proposal PR.

Thank you very much for the answer, I'll keep an eye on this pr and I'll open a new one when merged. ✌🏻

[algomaster99]

Hi! The proposal looks good to me. I have one question though

how to change your environments to test your code locally before committing it to your repo.

Are the tests for a specific ecosystem like Java, JS, or it could be any test?

[MateusMarinheiro]

It could be any environment. When we made the PR we were thinking more about Linux packages. But if Java or JS would be more fitting we can change it, of course!

[algomaster99]

But if Java or JS would be more fitting we can change it, of course!

No need to change it. I was just curious about the ecosystem, but Linux packages sound cooler. Please continue. :) I will merge.

[t-sorger]

Feedback from Marco Campione (campione@kth.se) and Tom Sorger (sorger@kth.se)

We certify that generative AI, incl. ChatGPT, has not been used to write this feedback. Using generative AI without permission is considered academic misconduct.

Firstly, we want to thank Mateus Marinheiro and Arber Limani for letting us provide feedback for their executable tutorial.

This feedback starts with listing high-level strengths and weaknesses: all of them are covered later on as well in more detail.

High-Level Strengths

 _________________________________________
/ NDcgNmYgNmYgNjQgMjAgNmEgNmYgNjIgNzMgMjA \
| gNDEgNjIgNjUgNzIgMjAgNjEgNmUgNjQgMjAgNG |
\ QgNjEgNzQgNjUgNzUgNzM=                  /
 -----------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

• Very well-written introduction: The introduction provides a very good explanation of the motivation behind why this executable tutorial is important. The learning outcomes are also stated in this introduction, so the user will know before the start of the tutorial what he is going to learn.
• Steps Overview: The steps structure is very organized, each step has a detailed explanation of what the user will do. Also if the user executes a command with multiple flags/options, all of them are explained in detail, e.g. in the step “Add nix-env and set it up”.
• Images: Thanks to images the user will be sure that the modifications he did to the files are correct and he won’t face any problems in the next steps. Also, the pictures increase the aesthetic and readability of the executable tutorial.
• Easter eggs: We like that you included easter eggs.

High-Level Weaknesses

• Missing Overview: An image at the end of each step that visually explains how many steps are still left and how many are already done could improve the overview of the tutorial. Also, adding numbers to each step for a better overview might be valuable.
• Consistency of Screenshots:
  • In the step “add packages to the flake file” the description text changes from “A very basic flake” to “We want Code Reviews!” back to “A very basic flake”. This is a bit confusing.
  • The tutorial also contains screenshots with different shells but the Killercoda shell. This might also be a bit confusing for the user as his shell doesn’t look the same as in the screenshot, e.g. in step “Locking your versioning”.
• Icons/Emojis: There are pictures which is good, but adding icons/emojis after some phrases would increase the aesthetic and readability even more.
• Documentation/Links: Adding some links to default documentation or recommended (future) guides would be extremely valuable for the user.

Content and Structure of the Tutorial

The topic of this executable tutorial is quite relevant to what we learned during the course. Starting from the introduction the user can get a quick overview of what he will learn during the tutorial, we suggest that you add some links that refer to the official documentation as well as other valuable links that you might have used to create the tutorial. Here you can find some suggestions from our side: Zero to Nix – Your guide to learning Nix and flakes and NixOS & Flakes Book – An unofficial book for beginners.

We really liked the way you are hiding the easter eggs. We hope we have found all of them that you included in the executable tutorial. Specifically, we found the following two:

• Step “Add nix-env and set it up”: “Have you heard about SPOON?”
• Step “Locking your versioning”: “I think Spoon is the best!” ← we kindly ask you to modify “think” with “know”😛

Let us know if there are more so we can search for them🙂

The tutorial you created contains multiple pictures letting the user know and see how things (file content and outputs) should look. This is very valuable especially when one doesn’t have much previous knowledge. One thing we recognized is that at certain times there is a bit of an inconsistency between those screenshots, e.g. in the step “Add packages to the flake file” the description of the nix flake changes without any description back and forth. This was a bit confusing when executing the tutorial for the first time. We understand that this description is just a (let’s say) meaningless string, but those small inconsistencies still disturb the flow when executing such a tutorial. Keeping track that all pictures and contents staying consistent would improve the flow of your tutorial and can easily be fixed.

The executable tutorial is indeed well structured. It provides a step-by-step guide on how to set up and use nix flakes. One thing that we found a bit missing was a graphic (maybe in the beginning) showing and explaining to us how many steps there are going to be, as well as which steps will be coming up in this tutorial. Also, we missed an enumeration of the steps which would help the user to better jump back and forth between steps in case one wants to look something up from a previous step. Adding such a graphic, as well as the enumeration of steps would highly increase the structure of the tutorial.
Talking about pictures we would also suggest adding some small icons/emojis here and there to break the text a bit, which also increases the amusement of the user.

Summary

In summary, we really enjoyed the way you designed and created this tutorial. As we all know Nix is a really powerful tool but on the other side, it is really hard to understand. We started the tutorial with little knowledge about nixos and flakes, but we can now affirm that we have a basic understanding of them thanks to this tutorial. We hope that your tutorial will often be executed on Killerkoda!