Executable Tutorial Proposal

[Jakebobs]

Assignment Proposal

Title

Using Github Actions in combination with GitHub Pages to launch your Vue web service

Names and KTH ID

• Jakob Ström ([email protected])
• Carl Lavö ([email protected])

Deadline

• Task 3

Category

• Executable tutorial

Description

In our tutorial we will show how to set up a demo for your Vue web service using the pages function of GitHub combined with how to set up a github Action workflow to deploy it. In this specific example we will be using Vue since we have used it in previous computer science courses at KTH. The tutorial is aimed to give you a working Vue bootstrap that is available for others to test online without having to find a hosting solution.

The technical changes needed compared to a regular Jekyll github pages page, is creating a .yml to build vue, changing the routing of your vue application to use hash routing instead and deploying a correct file structure to a separate branch.

Relevance

Being able to give others access is a very useful tool in the beginning of creating a web service. Not having to spend time on setting up back-end solutions and instead being able to focus on working out features. Using github pages is according to us one of the simplest solutions for doing this and unlike Canva Pro and Adobe XD also available for free.

[miljon3]

It only requires a github account, since that is a requirement for the course and where we submit pull requests. It feels a bit unreasonable to not allow github accounts.

[algomaster99]

@javierron the proposal is more specific now and it has technical details like configuring routing so I am merging it!

[JadedTuna]

Feedback

By: Wiktor Dobrosierdow ([email protected]) and Sofia Edvardsson ([email protected])

Code of Conduct

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

High-level strengths and positive comments

• The intended learning outcomes are clearly stated on the intro page which gives an overview of the content of the tutorial, as well as sets the users expectations. We also like that the recommended prerequisites are stated in the start page since this makes it possible for users to consider whether or not they need to read up on some topics before starting the tutorial.
• One aspect where the tutorial truly shines is that it tries to include all of the commands and steps that are necessary. This ensures that even those who are less confident with the tools and topics in the tutorial can follow along and perform the expected tasks.
• We like the idea of providing the complete code for the files that the user makes changes in, and that it can be found at the end of many of the steps. This makes it possible for the user to add one code component at a time and then compare it to the complete code at the end to ensure that it is correct. Like an IKEA manual which shows every assembly step and the finished parts!
• In the true nature of DevOps, many things are automated throughout the tutorial. The whole tutorial can be completed in the terminal after the initial GitHub authentication token is created, and there is no need for manual deployment to GitHub Pages.

Weaknesses & improvement suggestions

We've arranged the following list based on what we feel are the most important areas for improvement, with the more important points first.

• Step-by-step modification of “src/router/index.js” results in an incorrect file, which does not match the provided full source. This file defines the possible routes (Aboutview, Homeview, Testview) present on the final page. It needs to export a variable called “routes” which it does in the provided full source code, but the step-by-step modifications do not result in a variable “routes” being exported. This leads to an error in the GitHub Pages deployment. Since describing step-by-step how to get the “correct” file contents could become confusing and require several big steps, it may just be easier to only provide the expected full source code of the file. Just as some parts from IKEA come preassembled – less of a chance of the user ending up with a three-legged table!
• Copying in the provided source of App.vue results in broken CSS. To be fair, it is stated in the tutorial that the provided source should only replace parts of the file, but it is a bit confusing since in all the other instances, the full source code is provided. In cases where something doesn’t work, the first thing to try as a user is to go through the tutorial and copy-paste all the code fragments in, to fix any possible typos made. If that is done with App.vue the result is broken CSS for the navigation links.
• The tutorial does not provide many troubleshooting steps in case something goes wrong. It primarily tells the user to wait and reload the page if things don’t work, but it does not explain how to debug issues, by e.g. consulting the deployment workflow in GitHub Actions. It is not uncommon for users to make mistakes while following a tutorial, and having some guide for where to check for common issues could be beneficial. The tutorial could have a short description of how to use DevTools in Chrome/Firefox and how to view GitHub Action workflow results, or at least link to online references (See “Useful sources of information” below).
• One thing that we feel is missing in the tutorial is some background about the components that are implemented in the tutorial. We believe that it would be reasonable to introduce the users to GitHub Pages in the beginning of the tutorial and maybe include some images so that all users know what the finished product could look like. Although knowledge of Vue is stated as one of the prerequisites, a brief introduction of it could still benefit the user.

Minor nitpicks

• The flowcharts are great at helping the user visualise the processes, however they can easily become less readable since the text in the images get malformed when the size of the text area changes. We’re not sure if it’s possible, but ensuring that the image ratios are preserved when scaled could potentially help that problem. So that the text in your flowcharts does not become abstract art :D
• There are some instances where the text instructions don't exactly match the options shown in the terminal. This is very minor, but it could confuse users with less prior knowledge about the topic. An example of this would be that in step 1 the text mentions “Paste Personal Access Token” as an alternative, whereas the alternative shown in the terminal says “Paste an authentication token”. We understand that these small things are easy to overlook, and the best solution would probably be to ask someone from outside of the group to look at the tutorial (such as us :D).

Overall, it was a very easy tutorial to follow and quite illuminating how certain aspects of GitHub work. We certainly feel we learned something new from it!

Useful sources of information

• Chrome DevTools: https://developer.chrome.com/docs/devtools/overview
• GitHub Actions viewing workflow results: https://docs.github.com/en/actions/writing-workflows/quickstart#viewing-your-workflow-results
• Vue introduction: https://vuejs.org/guide/introduction.html

[sofiabobadilla]

HI @Jakebobs @miljon3 @JadedTuna @sofiaedv

I could use some help with the tutorial.
I follow it for already quite some time and can not manage to see the easter egg.
Could you have a look at the github repo and give me a hint? https://github.com/sofiabobadilla/tutorial.io

The webpage is: https://sofiabobadilla.github.io/tutorial.io/index.html

[sofiaedv]

Hi @sofiabobadilla

I think that you accidentally replaced some source code in App.vue (just like we mentioned under the second point under Weaknesses & improvement suggestions). Fixing this should hopefully fix your website.

[miljon3]

HI @Jakebobs @miljon3 @JadedTuna @sofiaedv

I could use some help with the tutorial.

I follow it for already quite some time and can not manage to see the easter egg.

Could you have a look at the github repo and give me a hint? https://github.com/sofiabobadilla/tutorial.io

The webpage is: https://sofiabobadilla.github.io/tutorial.io/index.html

Hi, like the other comment said you accidentally replaced some source code in app.vue, the Easter egg is pretty apparent once you get the last step shown on your page.

App.vue should look like this if you just want to copy it: https://github.com/miljon3/chainsaw-mannequin.io/blob/master/src/App.vue

[sofiabobadilla]

Thank you @sofiaedv and @miljon3