Executable tutorial proposal

[arejula27]

Assignment Proposal

Title

Managing project dependencies with Devbox

Names and KTH ID

• Íñigo Aréjula Aísa ([email protected])
• Pere Mateu Raventós ([email protected])

Deadline

• Task 2

Category

• executable-tutorial

Description

Devbox is a command-line tool that lets you easily create isolated shells for development. You start by defining the list of packages required for your project, and Devbox creates an isolated, reproducible environment with those packages installed. We will create a tutorial that explains how to use Devbox to manage project dependencies. The tutorial will cover the following topics:

• Why devbox is useful
• How to install dependencies with devbox
• How to create scripts in devbox
• How to replicate the same environment in your CI/CD pipeline with GH Actions

Relevance

Devbox is relevant to DevOps as it simplifies creating reproducible development environments, ensuring consistency across local, testing, and production setups. This aligns with DevOps principles, improving collaboration, automation, and the reliability of CI/CD pipelines.

[sofiabobadilla]

The idea is original and interesting.
I'll merge :)

[peremateu]

We have finished the tutorial! The link to it was already in the initial commit, but we also leave it here so it is more accessible from everywhere:
https://killercoda.com/arejula27/scenario/devbox-tutorial

[Glassar]

Feedback

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

First off, this is a really well made tutorial. It starts off with a well argued relevance section highlighting the need for a tool like DevBox. You then have a well thought out red thread through the whole tutorial with one section nicely leading on to the next in a seamless way. I really like the story told through first trying to run your Python project in your normal development environment, and then moving to DevBox to manage said environment. The section where the user needs to write their own code is also really good, it is simple enough that I didn’t feel lost, and what you need to do has nicely been introduced just before with another example. Which was really good because I am not good at using a command line editor.

As to high level things that need some work: First up spelling, it is not a huge problem but it is noticeable and can make it harder to understand what you are trying to say when you discuss technical details. I would recommend just running your whole text through a spell checker just to iron them out as there are a bit too many to list them all manually. Secondly the first two pages of your actual tutorial have you receive a big wall of terminal output which is quite daunting. So it would be nice to first warn the user about it, and especially with your first example of why you might need DevBox, tell them to not try to and understand the output.

Intro

• It would be nice with a bit more of an introduction to what DevBox is. For example, what does creating isolated environments mean?
• The relevance section is quite long, so it might be nice to break it up into sections. Even though its content are very relevant.

First step

• As mentioned above, making it clear that this is just an example to prove why DevBox might be needed would be great, as I spent more time than necessary trying to understand what we were trying to do here.

Trying DevBox

• I really like that you are aware of the time the install will take and tell the user to continue to read while it is installing.
• The section about what is special with DevBox could do with some clarification. What is meant by “accelerating the processes inside your project”, can it speed up our project meetings?
• The overall section on trying DevBox could be clearer. Specifically, is the DevBox run py command intended to execute a script defined for installing dependencies? It was not clear from the beginning.
• I think that you should make it clearer that you can actually open the website, as this is a cool way to demonstrate DevBox working. It gets a bit hidden in the text and I first read it as a link to more details about the FastAPI.

Understanding json

• The section explains the content and functionality of the devbox.json file, allowing for better understanding. However, the clarity of the text needs improvement, as it can be challenging to parse and comprehend.

Create Your Own Script - Part 1:

• This part was very helpful. succeeding in creating our script independently was pretty easy, which greatly enhanced our understanding of the technology.

Create Your Own Script - Part 2:

• In the previous section, you mentioned including the init hook in the test script. However, in the provided code that was not present. Should it be added or do we miss something?

DevBox Integration with CI/CD:

• We appreciate the emphasis on maintaining consistency within the development environment. This section proved to be very insightful and useful to understand the concept of consistency across different environments in the software development stages.

General notes

• How can we effectively transition DevBox into the production environment? Further guidance on this would be valuable.
• The tone of the instructions is friendly while also having a smidge of humor making the tutorial more engaging.
• The tutorial took 26 minutes to complete.

All in all a very well done and informative tutorial.

Well done!