DEV Community: João Freitas

Scripts should be written using the project main language

João Freitas — Mon, 25 Mar 2024 19:43:54 +0000

This is an hot-take I've been feeling for a long time.

Almost all projects I've worked on have scripts we wrote to automate a repetitive process. Consecutively, the majority of the scripts became obsolete and unmaintainable after some weeks, because we either didn't need them anymore or they have become too complex to be looked at. Afterwards, these scripts are either refactored or they stay forever in the scripts graveyard.

Never forget to pay your respects for all the scripts we left to rot 🫡 (Source)

I think one of the major reasons that lead to this outcome is that we wrote the scripts in Bash or Python. Don't get me wrong, I'm a big fan of the two, but I feel like teams can win more if they write scripts using the main language their project is developed with. From the start, time and effort required to write them is reduced since:

The learning curve is minimal, since you already know the corners of the language
Internal language APIs can be leveraged, which drastically changes the mental model to write the script (for the better)
Scripts feel more natural and eventually maintainability increases. Team members are familirized with the language!
Development machines compatibility increases. Windows users can finally run all scripts. 🤭

The downside of going on this direction is the main language runtime support. Not every language is multi-paradigm or was designed to support scripting. For example, writing scripts on JVM languages would require additional effort to build a toolchain that compiles and runs files on the fly, with short start time. But if you work on a web frontend project (JavaScript), the power is in your hands.

At the end of the day, it is up to teams to talk and establish an agreement on which language fits best their needs and standardize their scripting language. If they can use the main language, awesome. If they can't, an higher level scripting language with native support (e.g., Python) should be adopted, since it provides the means to increase maintainability on the long run.

Why you should use a terminal editor to write a commit message

João Freitas — Wed, 20 Mar 2024 23:52:22 +0000

Ever since starting to only use Git in the command line, I've been writing commit messages through a terminal editor (nano), instead of passing the message (-m) flag. Some colleagues find it odd that I do it this way, so here are seven reasons in favor of using a terminal editor:

First of all, you need to pass the -m flag, and that alone is costing you time.
You need to wrap your message in quotes/ticks (""). Finding them on your keyboard can be somewhat hard.
You can't break lines in your message. Your brain is always under pressure to not click the enter key, otherwise, you will need to amend the commit message.
If the repository is configured with pre-commit hooks, they won't be executed until you click the enter key. This is particularly bad if commit messages need to follow a specific structure.
Oh, you managed to click the enter key and accidentally created a commit? You need to repeat the whole process to amend the commit message (this includes copying/writing the message and passing the --amend flag).
Your terminal shell interpreter (bash/zsh/csh...) is very sensitive to special characters. To include them, you will need to think of ways to either escape them or make sure the interpreter won't evaluate them. (e.g., imagine you need to write this message: fix: apply "$HOME" instead of using single ticks ('')))
Copy-pasting a message might give you a hard time. If the message includes Unicode characters that your terminal has issues to render, like emojis, it will be a pain to correct them.

All of these issues can be avoided if you learn the basics of a terminal editor (nano is really simple!) and type git commit (or even better, declare a shorthand alias like gc that will save you a ton of time).

Cross-Post: https://joaomagfreitas.link/why-you-should-use-a-terminal-editor-to-write-a-commit-message/

Background Image: https://cbea.ms/git-commit/

Ukoreh - Demo Flutter projects on the fly

João Freitas — Tue, 23 May 2023 21:19:06 +0000

What I built

Platform to demo Flutter apps by deploying them as web apps using GitHub actions

Category Submission:

DIY Deployments

App Link

https://ukoreh.github.io/ukoreh.fun

Screenshots

Loading	Initial page	Loading	Stepper

Description

Ukoreh is a tool for Flutter developers. It aims to increase the openness of open-source projects by allowing developers to easily demo Flutter projects as web apps since any project is most of the time cross-platform.

Link to Source Code

https://github.com/ukoreh (org)

https://github.com/ukoreh/gecgecgecgecgec (frontend)
https://github.com/ukoreh/fold (serverless functions)
https://github.com/ukoreh/actions (actions)

Permissive License

MIT

Background (What made you decide to build this particular app? What inspired you?)

We all love to view and research new projects on GitHub. Some of them have screenshots and videos, others don't. Well, wouldn't it be great if, at the distance of a click, you could get a demo of that particular project?

We made that possible for Flutter projects: since most Flutter apps are cross-compatible in different platforms (mobile, web, desktop), even if one built an app for iOS, I could test it as a web app.

How I built it (How did you utilize GitHub Actions or GitHub Codespaces? Did you learn something new along the way? Pick up a new skill?)

Our stack is composed of four technologies: Svelte, Cloudflare Workers, GitHub Pages and GitHub Actions. Let's start with the last one:

We leveraged actions to establish a workflow starting from cloning the target repo, polishing it, building as a Flutter web app and publishing it to GitHub Pages.
We used Cloudflare Workers as the middleman between the platform you request a repo to be deployed and triggering an action via GitHub API.
Finally, we used Svelte to build the platform. It could have been React, Vue, some random JS framework I don't know, or even pure HTML. However, we chose Svelte because we are learning it as we believe it's the top-standing JS framework for building web apps.

We did find some issues along the way and learned a lot from them. One of these issues, is the fact that GitHub does not give you back the workflow run id when you start a new workflow for a given action.

To overcome this issue, we had to do some shenanigans in both the actions and workers code. In short, the action finds the most recent workflow run and then sets the identifier in the action local storage. Then, the worker patiently waits for this identifier to be set and get's it via GitHub API.

Additional Resources/Info

This project was thought about way back in 2020! Thankfully it got to see the daylight after 3 years, thanks to this hackathon.

Micro Libraries

João Freitas — Mon, 01 May 2023 10:00:00 +0000

Some weeks ago I stumble upon the concept of micro apps: apps that serve only one functionality/purpose, being minimal in most of the cases. And I question myself: if we have microservices and micro apps, it's only logical that we have micro libraries, right?

So, what do these libraries offer? You guessed it, one feature/functionality. The earliest moment I remember seeing one of these libraries, was the isX libraries drama, where people claimed that JavaScript projects were becoming bloated because of the over-dependence on predicate function libraries, such as "is-number", for something as simple as asserting if a value is a number (is-number).

While I agree that these type of libraries contribute to bloatiness, building them can be quite satisfying, because:

they are fast to build
they are easy to maintain
they integrate with ease
you are challenged to build without external dependencies and for optimization

There's an additional rule for micro-libraries: what you build must be shipped through a single function. For JS/TS libraries, you can achieve this by exporting only that function in the main module file.

One big advantage of using micro-libraries, is that you get what you pay for. For example, if you only need feature X from library Y, why should you also depend on feature Z, W, A, B and C that are bundled with Y?
This was my motivation for building github-upsert: a micro library for uploading/updating files in a GitHub repo.

I can now use this library on my Cloudflare Workers (that are limited to 1M bundle size) without depending on all the GitHub JS SDK features, just to update a file on my GitHub repo.

On Lindenmayer Systems

João Freitas — Sat, 29 Apr 2023 13:04:55 +0000

Yesterday I learned about Lindenmayer Systems (L-System) through Gil Durão talk at Flutter Talk Porto 2023. It's a formal specification of a grammar primarly used to model bacteria, algae, plants and tree growth, as originally proposed by Aristid Lindenmayer.

At its core there are three components (G=⟨V,ω,P⟩):

An alphabet, which is a list of symbols that can be combined to create strings (e.g., ABC, +-*/), denoted as V.
An axiom, which defines the starting point of the L-System (e.g., BC), denoted as ω.
A set of production rules, which determine how each symbol of the alphabet is transformed into other symbols (e.g., A -> AB, B -> AC, C -> CB), denoted as P.

The goal behind these systems is to specify finite or infinite strings, which are constructed iteratively by applying the production rules to the symbols from the previous iteration. Using the example above:

BC (Axiom - Iteration 0)
ACCB (Iteration 1)
ABCBCBAC (Iteration 2)
...

Production rules specify the class/type of L-Systems, with the simplest one being D0L-system (deterministic and context-free L-System), which are represented by functions that take symbols as input and deterministically map them to other symbols as output. You can learn more about different classes on this article.

Okay, but what exactly can we use L-Systems for?

While many people use them to generate fractals (because fractals are cool), you can also use L-Systems to leverage your procedural generation game:

Video-game Maps and Entities (objects)
Road Networks
Music
~~Maybe even creating pixel art as part of your NFT project?~~ Art

Gil prepared a demo of using L-Systems to generate fractals with Flutter. You can check it out here. Also, his presentation is free, so be sure to grab it!

When to create a GitHub organization

João Freitas — Fri, 21 Apr 2023 19:30:00 +0000

Whenever I'm starting to work on a new (side) project, I end up facing myself at creating a new GitHub organization to work on it. But why is this the case?

I've sat down and compiled a list of reasons for why creating a new org makes sense:

You will need to create multiple repositories for different codebases
You want to segregate development areas across multiple repositories (e.g., backend, frontend, infrastructure, business, documentation)
You want to use the organization GitHub profile as the frontpage of your project
Multiple people are working on the same project
The project you're working on will eventually become a viable product, so you want to brand it
You want to market your product as built by an entity (your organization) and not by yourself
You want a cool little square logo in your GitHub profile (swag) 😎

(this list may be updated from time to time whenever I discover more reasons)

Why your GitHub action is not triggered by other actions

João Freitas — Sat, 18 Mar 2023 09:42:56 +0000

In this blog post I explain why GitHub actions don’t trigger each other by default, helping you how to achieve it.

Last week I wrote about how I configured a GitHub action to change this blog theme every day. Today I will explain you why I lost some time trying to understand why that action was not triggering my deploy to GitHub Pages action.

Before

Let's first do a side by side comparison on how each action is triggered:

name: publish

on:
  push:
    branches:
      - master

Deploy is based on commits made to master

name: update-theme-color

on:
  schedule:
    - cron: "0 0 * * *"

Change blog theme color is based on a cron job

Intuitively you would think that once the update-theme-color action runs, which creates a new commit in master, triggers the publish action, since it reacts to master branch updates.

However...

That is not the case! By default GitHub Actions don't trigger each other to prevent recursive runs. For an action X to be triggered by action Y, then action X needs to observe action Y execution.

How

To observe actions execution, the workflow_run reaction needs to be included. Here's how I reconfigured the publish action:

name: publish

on:
  push:
    branches:
      - master
  workflow_run:
    workflows: ["update-theme-color"]
    types: 
      - completed

This blog changes its theme every day

João Freitas — Sun, 12 Mar 2023 12:01:56 +0000

Minimalistic blogs may get boring sometimes. We want to reduce visual polution, but our brain needs some visual sugar from time to time! That's why I configured a workflow for this blog that changes its theme color every day. Today you're seeing this color (yellow), but tomorrow you might see this color (red).

How

If you have read my about page, you know that this blog is built with the following stack: Hugo, Bear Blog Theme and GitHub Pages. Content is published to the web whenever my pages GitHub repository is updated, triggered by a GitHub Action.

The process to update theme color is seemingly the same: have a GitHub Action that is triggered every day by midnight.

name: update-theme-color

on:
  schedule:
    - cron: "0 0 * * *"

jobs:
  cron:
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod

      - name: Change color
        run: bash scripts/update_theme_color.bash

      - name: Commit and push
        run: bash scripts/action_repo_commit_and_push_all.bash "Update theme color"

But how is each color chosen? Initially I thought that randomizing a color using the updating date as a seed (e.g., 2023-03-12), but then I remembered that could lead to undesirable situations such as:

(#FFFFFF) "really light" text on light theme
(#000000) "really dark" text on dark theme
(#4A412A) or even this! (light theme users, can you point the differences?)

To overcome this issue, I decided that the best option is to handfully pick a set of colors and then choose at random one of them. All I needed to do is create a source of great colors

#F94144
#F3722C
#F8961E
...
#A9DEF9
#E4C1F9

and then use bash scripting commands to chose one from the source and updated it in my blog config.toml file.

#!/usr/bin/env bash
script_dir_path=$(dirname "$(realpath $0)")

colors_file_path="$script_dir_path/good_colors.lst"

random_color=$(shuf -n 1 $colors_file_path)

config=$(awk '{sub(/link_color.*/, "link_color = \"'$random_color'\"")}1' config.toml)

echo "$config" > config.toml

DEV on Jekyll Now

João Freitas — Sat, 26 Sep 2020 14:28:58 +0000

You may have heard of Jekyll. It is a simple static site generator that you can use to create blogs and websites in general to expose your thoughts and content. Most of people use Jekyll as it is a ready to use solution for Github Pages, a free place on the Internet where you can host a website.

Jekyll Now is a Jekyll theme that integrates already most of the features that you need for your blog, such as adding content using Markdown or YAML, styling using SASS and mobile responsive support. Although the coolness of Jekyll Now, it has a downside which is that it hasn't been updated for more than two years now (last commit on April, 2018). The lack of updates scars some of the features it provides. One of these scar features is social media referring on the footer of your blog.
Jekyll Now has a main configuration file name _config.yml. When you stumble upon it, you notice that you can refer your social media profile, which will later be shown as an icon that upon clicking will redirect to your profile. For example you can reference your Github page, Twitter profile or even LinkedIn. However you can't reference your dev.to or even Medium profile. To enable we need to dig deep in Jekyll Now "engine" and perform some updates.

Heading over to _includes folder we notice a file with references for the available footer links: svg-icons.html. This is the first step to include our custom footer social media link, the HTML. By copying one of the lines and replacing the website name with dev.to, we create a reference link for DEV.

{% if site.footer-links.dev-to %}<a href="https://dev.to/{{ site.footer-links.dev-to }}"><i class="svg-icon dev-to"></i></a>{% endif %}

Code Snippet 1 - dev.to footer link included in svg-icons.html

Once having the HTML defined, we need to customize it, by adding some CSS. You may have noticed that the footer element is composed by an <i> element that refers a CSS class: svg-icon. If it is referring some CSS class, then this class must be also living on the engine. As referred before, Jekyll Now uses SASS for styling. A folder named _sass can be found, which includes the styling for svg-icon. Similar to what has been done before on svg-icons.html, by opening _svg-icons.scss we can extend the class to support the dev.to icon. Copying a line and replacing previous references with what was defined in the <i> element will style the HTML element that we just created. Just make sure to correctly refer the base64 string of the icon SVG icon and adopt the icon size (otherwise SVG layers may be displayed duplicated).

&.dev-to{ background-image: url(data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgdmlld0JveD0iMCAwIDQ0OCA1MTIiPjxwYXRoICBmaWxsPSIjMDAwMDAwIiBkPSJNMTIwLjEyIDIwOC4yOWMtMy44OC0yLjktNy43Ny00LjM1LTExLjY1LTQuMzVIOTEuMDN2MTA0LjQ3aDE3LjQ1YzMuODggMCA3Ljc3LTEuNDUgMTEuNjUtNC4zNSAzLjg4LTIuOSA1LjgyLTcuMjUgNS44Mi0xMy4wNnYtNjkuNjVjLS4wMS01LjgtMS45Ni0xMC4xNi01LjgzLTEzLjA2ek00MDQuMSAzMkg0My45QzE5LjcgMzIgLjA2IDUxLjU5IDAgNzUuOHYzNjAuNEMuMDYgNDYwLjQxIDE5LjcgNDgwIDQzLjkgNDgwaDM2MC4yYzI0LjIxIDAgNDMuODQtMTkuNTkgNDMuOS00My44Vjc1LjhjLS4wNi0yNC4yMS0xOS43LTQzLjgtNDMuOS00My44ek0xNTQuMiAyOTEuMTljMCAxOC44MS0xMS42MSA0Ny4zMS00OC4zNiA0Ny4yNWgtNDYuNFYxNzIuOThoNDcuMzhjMzUuNDQgMCA0Ny4zNiAyOC40NiA0Ny4zNyA0Ny4yOGwuMDEgNzAuOTN6bTEwMC42OC04OC42NkgyMDEuNnYzOC40MmgzMi41N3YyOS41N0gyMDEuNnYzOC40MWg1My4yOXYyOS41N2gtNjIuMThjLTExLjE2LjI5LTIwLjQ0LTguNTMtMjAuNzItMTkuNjlWMTkzLjdjLS4yNy0xMS4xNSA4LjU2LTIwLjQxIDE5LjcxLTIwLjY5aDYzLjE5bC0uMDEgMjkuNTJ6bTEwMy42NCAxMTUuMjljLTEzLjIgMzAuNzUtMzYuODUgMjQuNjMtNDcuNDQgMGwtMzguNTMtMTQ0LjhoMzIuNTdsMjkuNzEgMTEzLjcyIDI5LjU3LTExMy43MmgzMi41OGwtMzguNDYgMTQ0Ljh6Ij48L3BhdGg+PC9zdmc+);}

Code Snippet 2 - Custom styling for dev-to HTML element

The final step is to edit the _config.yml file to include our dev-to profile display. Under the footer-links collection, add the following tag:

dev-to: <your_dev.to_username>

Code Snippet 3 - YAML tag for displaying dev.to profile

That's it. If everything went well, you should see the dev.to icon on the footer of your blog and when clicking on it, it should redirect to your profile!

Continuous Deployment for Flutter Web with Travis CI and Github Pages

João Freitas — Fri, 31 Jan 2020 18:09:52 +0000

Some brief notes about this guide

Flutter Web, also known as the the Hummingbird project, was recently released on the beta channel of Flutter for developers to test and try the build of Flutter applications as web applications. This guide aims to help developers agilize their deployment processes in a free and reliable solution, as well as to spread the word and love of Flutter Web.

I hope this guide helps you out :)

Requirements

Github account and a repository to host the built web application files
Travis CI account
Flutter SDK (beta channel)

Setup

Workflow

Before setting up the pipeline on Travis and creating the Flutter Web application, it is necessary to decide which branching model is to be adopted as this decision influences the pipeline design. As this example serves as a guide on how to integrate Flutter Web and Travis CI, a single branch model (Trunk Based Development) will be used.

Flutter Web

Once the workflow is decided, we need to setup Flutter in order to be able to run and "compile" for the web. As the time that this guide is being written (2020/01/30), Flutter Web is still in its early stages and it is necessary to use the SDK provided in the beta channel. If your Flutter version is still not pointing to the beta channel, you can switch to it by running the following commands:

flutter channel beta
flutter upgrade

Once on the beta channel you need to enable support for Flutter web. To do such run the following command:

flutter config --enable-web

If everything went well flutter doctor should now also print the following message:

[✓] Chrome - develop for the web

We can now initialize our application. Just like any other Flutter project you perform such with the following command:

flutter create <name_of_my_app>

Once created, you can now run it on a Chrome browser (As the time this guide is being written, Flutter Web debug is only available on Chrome), with the typical flutter run command (add -d chrome if other devices such as simulators are detected by Flutter Doctor)

Thats it! You are done with the Flutter Web setup.

Travis CI

For Travis to detect changes in your repository, you need to first register it in the dashboard. Head over to https://travis-ci.org/ if your repository is public, or https://travis-ci.com/ if it is private.

In Travis you implement the pipeline under the YAML schema, defined on a file named .travis.yml. For a clean setup create this file on the root of your repository.

Pipeline Machine Configuration

The first lines of .travis.yml normally identify the configuration of the machine to be used to run the pipeline. As Flutter uses dart2js, a tool to transpile Dart code in Javascript code, there is no constraint related to the operating system environment in order to build the application so you can choose whathever operating system that you desire to build for the web. In this example it is used the Ubuntu Bionic (18.04) distribution:

os: linux
distro: bionic

Build Phase

Before building the application, Travis needs to have Flutter setup in the machine. One of the ways this can be performed is by defining this setup as steps to be run before the build script:

before_script:
  - git clone https://github.com/flutter/flutter.git -b beta
  - export PATH=`pwd`/flutter/bin:`pwd`/flutter/bin/cache/dart-sdk/bin:$PATH
  - flutter config --enable-web

Now for the build of the application, declare it under script:

script:
    - flutter build web

This command creates all necessary files to represent a Flutter application as a single-page application, and stores them on build/web folder inside of your application folder.

Deploy Phase

Travis already provides support to deploy to Github Pages, using the deploy job, and we only need to configure it for our workflow. The essential configuration is the following:

provider in deploy job as pages. By doing so, Travis will recognize that a deploy in Github Pages needs to be done.
skip_cleanup must be true, or else Travis will delete all files created in the build, which prevents the deploy of the static files generated in the application build.
github_token a personal access token with read and write permissions of the repository which will serve the Github Pages static files. Once you obtain the token, define it as an environment variable in Travis pipeline settings.
keep_history decides to keep the history of the branch in which the files will be pushed to (if set to true, history is kept, otherwise Travis performs a force push).
local_dir the relative path from the pipeline build workspace to the directory in which the static files to be deployed are located.

deploy:
  provider: pages
  skip_cleanup: true
  github_token: $GITHUB_TOKEN
  keep_history: true
  local_dir: build/web

By default Travis pushes the files to gh-pages branch of the repository that triggered the pipeline build. You can configure the deploy to other branch or repository using the repo and target_branch keys. Take in consideration that if your want to modify the repository to be deployed, you need to include the username of the repository owner (<repo_owner>/<repo_to_deploy>). Another cool feature which Travis provides is the set of the custom domain to be used on Github Pages. This is done by modifying the value of fqdn. See all the other cool features that Travis provides here.

Thats all, trigger a push/pull request on the build branch and Travis will deploy your Flutter application! Best part? It's all free!

You can see the live version of the classic Flutter Counter here.

References and Acknowledgments

The write of this guide was possible and inspired by the following guides / documentation: