DEV Community: Marco Ieni

RustShip: a new Rust podcast

Marco Ieni — Fri, 18 Aug 2023 00:00:00 +0000

I’m excited to announce that I started RustShip: a new podcast where I interview other Rust developers to learn from their experiences.

RustShip #1 — Creating successful open-source projects

In the first episode, I interviewed Orhun, Arch Linux package maintainer and author of tens of open-source projects used and loved by thousands of people, including myself.

Orhun shared what it’s like maintaining Rust code and his advice on increasing the adoption of our open-source projects.

You can find the full episode on YouTube or your favorite podcast client.

If you don’t have time to listen to the full episode, here are some clips:

Creativity and Open Source (25 minutes)
Open Source sustainability and burnout (37 minutes)
Packaging Rust binaries for Linux distributions (4 minutes)
Dogfooding: use your own tools (1 minute)

What’s next?

I will record the next episode live on YouTube on August 23, 2023. I will interview Predrag Gruevski about Trustfall and Cargo-semver-checks, two Rust projects he created:

Trustfall is a query engine for any combination of data sources, allowing to query files and APIs as if they were databases.
Cargo-semver-checks is a cargo plugin that scans Rust crates looking for semver violations. It uses Trustfall and Rustdoc to do its job.

I plan to do at least one episode every month. Follow me on YouTube, Twitter, LinkedIn and Mastodon to stay up to date with the latest news and join the next live episodes: I’m always happy to answer questions from the chat during the live stream.

Release-plz: release Rust packages from CI

Marco Ieni — Sun, 26 Jun 2022 00:00:00 +0000

Releasing Rust packages is tedious and error-prone, just like most IT manual tasks. For every package you want to release, you need to:

Increase the version in Cargo.toml.
Update the changelog.
Publish the package in the cargo registry (for example, crates.io).
Create and push a git tag.

Meet release-plz: a Rust open-source project that automates these tasks, allowing developers to release Rust packages without the command line.

Features

Version update based on conventional commits.
Changelog update with git-cliff.
Cargo workspaces support.
No configuration required.
Optional cargo update before releasing.
Git tag created for every released package.
Package published to any cargo registry.

How does it work

The recommended way to run release-plz is via the GitHub action.

By default, every time you merge a commit to the main branch, the GitHub action runs two commands: release-plz release-pr and release-plz release.

Creating a release pull request

The release-plz release-pr command opens a pull request that prepares the next release. The command:

Downloads the packages of the project from the cargo registry.
Compares the local packages with the downloaded ones to determine the new commits.
Updates the packages versions based on the messages of the new commits (based on conventional commits and semantic versioning).
Updates the packages changelogs with the messages of the new commits.
Updates all dependencies by running cargo update (disabled by default).
Raises a pull request with the above changes.

When the project maintainer merges the release pull request, the packages are ready to be published.

Here’s an example of a PR opened by release-plz in the release-plz GitHub project itself:

Releasing all updated packages

The release-plz release command releases all the packages with a new version.

For example, let’s say you have a workspace with two packages: pkg-a (version 0.3.1) and pkg-b (version 0.2.2). The crates.io registry contains pkg-a version 0.3.1, but it doesn’t contain pkg-b version 0.2.2 because you didn’t publish this version yet. In this case, release-plz would release pkg-b.

For every release, release-plz:

Creates a git tag named <package_name>-v<version> (e.g. tokio-v1.8.1).
Publishes the package to the cargo registry by running cargo publish.

Releases made easy

In short, release-plz makes releasing Rust packages child’s play:

For every change, release-plz creates a release pull request.
The release pull request reminds the maintainer about the unpublished changes.
When the maintainer reviews and merges the pull request, release-plz releases the updated packages.

Release-plz makes releasing Rust packages as easy as clicking the pull request “merge” button.

Why yet another release tool

New Rust apps and rewrites are mushrooming every day. Choosing which tools to add to your developer toolbox is becoming harder and harder.

I feel obliged to explain why I created this project and how it compares with similar tools.

Differences with release-please

I learned about the “pull request driven release flow” from the article My ideal Rust workflow by fasterthanlime, where he talks about release-please. I immediately felt like release-please could fit great with the way I work, so I decided to try it. Like release-plz, release-please is an open-source project that manages releases via pull requests. I tried release-please both with the GitHub action and the CLI, but it didn’t work for me:

I got a “not found” error, which wasn’t very descriptive.
Two configuration files were required: .release-please-manifest.json and release-please-config.json. Most of the fields I had to write in these two files were already in the Cargo.toml files. I thought it was a shame that Rust developers needed to duplicate these fields.
Release-please considers a package “published” when the relative git tag exists. Release-please doesn’t interact at all with cargo registries. However, some Rust projects don’t create git tags. Instead, they just publish the package to crates.io, which is the ultimate source of truth.

Most of the problems listed above mainly exist because release-please aims to support different programming languages. So I thought:

What if I write a tool specifically optimized for Rust that solves all the problems I have experienced? A tool that works out-of-the-box with nearly every Rust project, without any extra configuration.

It took six months of my spare time to write release-plz, but here we are!

Differences with other Rust release tools

These are the release tools in the Rust ecosystem I am aware of:

cargo-release:
- Bumps the version and publishes Rust packages from the CLI.
- Doesn’t support automatic releases from CI yet. See this open issue.
cargo-workspaces:
- It’s a set of commands to manage cargo workspaces and their crates.
- The publish command releases the packages from the CLI similarly to cargo-release.
cargo-smart-release:
- Updates and publishes packages from the CLI.
- It’s very similar to release-plz, but it is not meant to be run in CI (see this comment from the author).

To respect the “Unix philosophy”, I tried to delegate the release flow to cargo-release and cargo-workspaces. However, after discussing with the maintainers here and here, I decided to implement the release-plz release command by myself.

Overall, I wasn’t satisfied with the existing Rust release tools because:

They use git tags to determine if a package is already published — release-plz uses cargo registries instead.
They primarily focus on the CLI use case — release-plz focuses mainly on CI.

Conclusion

Using release-plz increased my productivity. Having an automated release pipeline helps you deliver at a faster pace, with a lower risk of manual mistakes.

If you try release-plz, please let me know on Twitter. Also, make sure to open issues for feature requests or bug reports!

CKAD: 2021 tips, vimrc, bashrc and cheatsheet

Marco Ieni — Mon, 06 Sep 2021 00:00:00 +0000

You are probably busy studying for you exam right now, so I will try to be brief.

In the following I will share the things that helped me the most in becoming a CKAD, while trying to avoid all generic tips you can find in all the other blog posts like this.

Tips

I only used kubectl apply -f when interacting with yaml files: ignore kubectl create and kubectl replace for simplicity.
The exam consists in 2 hours to score 66% on 19 questions, so make sure to flag the most difficult questions, so that you complete them at the end only if you still have time.
Make sure to use bookmarks during the exam to be quicker. I used these ones. You can use them in your additional browser tab.
Edit the namespace when you copy paste a resource from the docs if it is hardcoded. See network policy for example, which will be applied to the default namespace if you don’t edit it.
Learn how to use less. I find very useful to pipe k8s resources into it. For example:
- You can search by typing / (like vim).
- You can toggle case sensitive search by typing -i.

.bashrc

You can define aliases in your .bashrc, so that you don’t have to type long commands during the exam.

You can copy-paste the first lines from here at the beginning of your exam. You have to memorize the rest:

# enable autocompletion
source <(kubectl completion bash)

alias k=kubectl
complete -F __start_kubectl k # autocomplete k

# get yaml object instead of applying the changes
alias kd="kubectl --dry-run=client -o yaml"
complete -F __start_kubectl kd

alias ka="kubectl apply -f"

# delete resources immediately
alias kD="kubectl delete --grace-period=0 --force"
complete -F __start_kubectl kD

# delete resources immediately from file
alias kDf="kubectl delete --grace-period=0 --force -f"

# In the following, $1 is the filepath of a yaml k8s object.

# vim apply. edit a file and immediately apply it.
va() {
  vim $1
  ka $1
}

# kubectl edit. Delete the resource of a file, edit and apply it.
ke() {
  kDf $1
  va $1
}

# kubectl replace. Delete and recreate the same resource.
kr() {
  kDf $1
  ka $1
}

After you have edited your .bashrc run the command source ~/.bashrc to apply the changes in your current shell.

.vimrc

At the beginning of your exam, edit your ~/.vimrc file, in order to edit yaml files efficiently:

set nu # set numbers
set tabstop=2 shiftwidth=2 expandtab # use 2 spaces instead of tab
set ai # autoindent: when go to new line keep same indentation

Cheatsheet

Here is a very long list of imperative commands I found useful for the exam.

create a deployment:

k create deploy nginx
  --image nginx:1.16
  --replicas 4
  --port 8080 # container port
  -- ls /home # command

create a pod:

k run nginx
  --image=nginx
  --restart=Never
  -l="key1=value1,key2=value2" # multiple labels
  --env="COLOR=blue" --env="KEY3=val3" # multiple environment variables
  --port=5701 # container port
  --expose # create a ClusterIP service
  --rm -it # delete the pod after completed and open a terminal
  -- /bin/sh -c "while true; do date; sleep 10; done" # command

create a new Service to expose an existing Deployment:

k expose deploy test
  --port=80
  --target-port=8000
  --type NodePort # optional
  --name my-service

create a new service:

k create svc clusterip pod-name # service with app=pod-name as label
  --tcp=6379:6379 # <port>:<targetPort>

k create svc nodeport pod-name
  --tcp=80:80 # <port>:<targetPort>
  --node-port=30080

create job:

k create job nginx
  --image=nginx
  -- /bin/sh -c 'counter=0; \
     while [$counter -lt 3]; do counter=$((counter+1)); \
     sleep 3; done;'

create cronjob:

k create cj nginx
  --image=nginx
  --schedule="* * * * *"
  -- /bin/sh -c 'echo "current date: $(date)"'

create configmap:

k create cm app-config
  --from-literal=key123=value123

k create cm app-config
  --from-env-file=config.env # single file with environment variables

k create cm app-config
  --from-file=config.txt # single file or directory

create secret:

k create secret generic my-secret
  --from-literal=foo=bar

# you also have the other options as above for the configmap

decode a secret:echo "YmFy" | base64 --decode

create service account:

k create sa my-sa

override the image of a deployment:

k set image deploy my-deployment my-container-name=nginx:1.9.1
  --record # save the "CHANGE-CAUSE" in the deployment history

get pods:

k get po
  -l color=green,app!=my-app # label equality filter
  -l 'color in (green, red)' # label set filter
  -l 'color notin (green, red)' # notin filter
  -l 'color exists' # exists filter
  --show-labels # show all labels

rollouts:

k rollout status deploy nginx

k rollout history deploy nginx
  --revision=1 # specify revision (optional)

k rollout undo deploy nginx
  --to-revision=1 # optional

how to access a pod exposed by a ClusterIp with a timeout of 5 seconds:

k run busybox --image=busybox --restart=Never -it -- /bin/sh
# wget -O- 10.96.32.32:80 -T 5

open pod shell:

k exec -it my-pod -- /bin/sh

create resource quota:

kubectl create quota myrq --hard=cpu=1,memory=1G,pods=2

view docs:

k explain pods.spec

get all the events:

k get events --sort-by=.metadata.creationTimestamp

modify objects label:

k label nodes my-node color=blue # add a label to node
k label pod my-pod region=eu # add a label to pod
k label pod my-pod region=us --overwrite # edit a label
k label pod my-pod region- # remove a label

modify objects annotations:

k annotate ... # (same usage as k label)

edit namespace for all subsequent kubectl commands in the same context:

k config set-context --current --namespace=core-banking

horizontal pod autoscaler:

k autoscale deploy my-deploy
  --cpu-percent=70 # sum of the cpu percentages used by all the pods that needs to be reached for the hpa to start spinning other pods
  --min=2 # min number of pods
  --max=8 # max number of pods the HPA can scale

k get hpa

taints:

# apply taint
k taint nodes my-node my-key=my-value:NoSchedule

# remove taint
k taint nodes my-node my-key=my-value:NoSchedule-

Theory

I studied for the CKAD by watching the CKAD course by Mumshad Mannambeth, which is simply awesome and it contains very useful labs, too. I also read the CKAD book from O’Reilly, which I recommend if you want a written resource, too.

Practice

This is an hands-on exam, so of course you need to practice a lot. These are some useful resources:

Once you complete these and the labs of the CKAD course you will be probably ready for the exam.

Shortcuts

Time is precious! Use the corresponding shorcut of a k8s resource instead of its fullname.

Fullname	Shortcut
configmaps	cm
namespaces	ns
persistentvolumeclaims	pvc
persistentvolumes	pv
pods	po
serviceaccounts	sa
services	svc
deployments	deploy
replicasets	rs
horizontalpodautoscalers	hpa
cronjobs	cj
jobs
secrets
networkpolicies	netpol
resourcequotas	quota

Verify your work

After you are done (or when you are short of time) you should verify what you have done.

First of all run k get po --all-namespaces in every context to check that all pods are running.

After that, you can check if every resource was applied successfully:

configmaps and secret: k exec my-pod -- env
volumes: k exec my-pod -- ls /mount/volume/path
services: k get ep

Conclusion

Overall preparing for the certification was really helpful and the exam itself is really practical, so I highly recommend it! 🤓

The most important tip I can give is the following: I probably practiced too much for it, ending up scoring 99%. If the score is not important for you (the score is not written anywhere in the certification) just try it when you feel a little bit confident! Remember: you have two attempts!

Good luck with your exam: stay calm and focus ✌

My 2020 Recap: Open Source, talks, meetups and more!

Marco Ieni — Sat, 02 Jan 2021 21:30:44 +0000

I am not a huge fan of year recaps or new year's resolutions.
Mainly because I don't like thinking about the past in general or setting goals for the future.
I like to focus on the present, following my curiosity day by day and if I realize I want to accomplish
something I don't wait the new year to do it, but I try to start as soon as possible.

However, retrospectives are powerful, you can analyze what has gone wrong in order to try to improve it. Plus 2020 was..2020!
And together with all the tons of terrible stuff that happened to us, in the future I would like to
remember 2020 also for the nice things I accomplished this year. So let's start!

Open Source contributions

This year we had a lot of free time. The problem was that we had to spend it at home.
I used a big part of that to contribute to open source software. Why? Glad you asked!
Writing open source software is a really good opportunity to learn and to improve the world a little bit at the same time.

This was the year of Rust for me: most of the time at my laptop was spent on learning and working with programming language.
After reading the book and doing exercises and pet projects
you have to go in the wild and receive some code reviews, i.e. someone more experienced than you
has to tell you why your code sucks:
contributing to open source software is just the best way to achieve this goal!

Rust

Personal projects:

stm32f407 experiments: A bunch of personal experiments with STM32f407G-DISC1 and rust.
Rust GitHub Template: A template to create an amazing rust project hosted on GitHub in no time. (51 ⭐ on GitHub)
Poke Speare: Toy project to experiment with rust async, actix, reqwest and wiremock.
Poetry book builder: My first rust project, a pet project not worth checking out.

Contributions:

design patterns book: On december I started maintaining the design patterns repository. Me and simonsan just converted it into a lovely rust book. 📖
delta: Solved almost 100 clippy warnings, implemented CI and CD with GitHub actions, helped solving a really interesting bug which I plan to discuss in my YouTube channel. Plus there is this (thanks Dan 🙏):
wiremock-rs: improved error messages and documentation.
bat: fixed clippy warnings.
rofi-rs: fixed cippy warnings, added CI.
svd: implemented GitHub actions mainly.
svdtoold: worked too much on an issue which sadly was forgotten..This is part of open source, too. 😔 Silver lining: I learned a lot of rust by working on this! 🤓
fd: solved a very simple issue starting from a very complex solution that was over-engineered at best 😂
stm32-rs: Improved CI, documentation and fixed some devices. In this repo overall I added 95 lines and I removed 3451 lines..neat 😎

For obvious reasons I've excluded opened issues, support to users and little PRs like small documentation fixes (even if this one is special because it belongs to the rust repo 🧡).

VHDL

Learning a new language every year is really important.
If possible you should learn a language that belongs to a different programming paradigm
with respect to what you are used to.
Well, what's better than a language used to describe hardware for that? 🤩

If you want to experience the same feelings you had while learning your first programming language or
if you think you know everything about parallel programming you should really learn vhdl.
It's totally different from what I was used to and learning it was really really funny.

I published:

VUnit action: a GitHub action for VUnit that was moved to the official VUnit organization (yay 😁).
Vhdl examples: A bunch of personal Vhdl experiments tested in a CI with VUnit.

VSpaceCode

I love spacemacs, and I bring its key bindings into every editor I use.
In 2019 I already created spaceclipse and intellimacs (which counts 249 ⭐ on GitHub at the moment), but
what me, Steven and all the contributors are doing with VSpaceCode is amazing!
We have 726 ⭐ and 3963 installs! It really feels like it's the best of both worlds (full blown ready to use IDE vs spacemacs workflow).

Content

I posted 6 articles on my website and 5 videos in my YouTube channel. Oh, right, I opened a YouTube channel in September!
I have 40 subscribers right now so there is a lot of room for improvements there and next year I will upload other rust contents for sure!

Daily job

Even if it is only a small entry in this post, my daily job is of course what occupies most of my time.

This year I realized I want to work with rust full time, not only during weekends.
So, on November I joined True Layer, which is what I consider the best
decision I have ever made in my career (which honestly is not that long anyway 😂).

True Layer is amazing, both from a human and a technical perspective.
I am learning a lot of stuff about rust and the cloud native world and even if we are remote I feel very well connected
with my team (which is amazing by the way 😁).

Open Source Saturday Italy

Contributing to open source is funny, but doing it together it's better. That's why
starting from the idea of Open Source Saturday Milano I created
Open Source Saturday Italy, the online version, useful for people who lives in small cities with no meetups and compatible with
our beloved covid restrictions!

We meet on Saturday online on discord and we do some pair programming.
You cannot imagine how much I learned from these events and how many nice and talented people I've known.

If you like the idea you can create an Open Source Saturday for your own area! 😁

Talks

This year I gave two talks (remotely of course 🙃).
The first one was at the Italian Linux Day, where I talked about how to avoid using the mouse for the
sake of a better workflow.
The second one was at the Rust Milano Meetup and it was called How to create an awesome Rust project on GitHub.

If you are interested I recorded two YouTube videos that have almost the same content, you can find them here and here.

Mentorship

In September I joined the awesome rust mentors army. 🤠

I was contacted by almost 10 people (I should check old messages on all socials for the exact number).
They were really nice overall and I think I was able to help all of them in a way or another. 😀

Certifications

In July I attended the Computer Engineer Professional examination, which is what in Italy
we call "Esame di stato".

It was a good excuse to review old University notes and learn new concepts at the same time.
In particular, the ethical aspect of our profession is something it's always underestimated and it
was really pleasant to go through our formal codes of ethics.

Personal life

I like to keep most of my personal life offline.
Just wanted to say I've been really lucky, since all my family is doing well.

Also, I started playing guitar again after 5 years or so and it's a great way to switch context from programming and have some mental rest! 🎸

Conclusion

I am very glad my profession allows me to do all this amazing stuff from a 600€ laptop.
Other people like musicians, actors, etc. aren't so lucky, so we, as developers, should appreciate this possibility every day.

My 2021 resolutions are the same of 2020:

Have fun
Be curious
Make the world a better place (even a little bit!)

Maybe also "do better new year's resolutions?". The point is that 90% of what I have done this year
wasn't predictable at all in December 2019. I mean..starting a meetup, switching my full time job from
embedded to rust backend development..really? 🙂

Of course I have long term goals, like learning Haskell, improving my kubernetes skills, recording more YouTube videos or start watching Game of Thrones.
But I feel like seriously writing them down and assigning a deadline will prevent me from doing random stuff
that just came to my mind the day before while I was going to bed. 😅

So actually not having proper new year's resolutions is the way to go for me in 2021.
Let's see if I will change my mind in 2022. 😁

Rust makes cross compilation child's play

Marco Ieni — Sat, 05 Dec 2020 00:00:00 +0000

Why do I care about this

Recently I solved this delta issue, where the maintainer asked to switch from Travis CI to GitHub actions.

These are all the pull requests I’ve done if you want to have a look at this journey:#399, #400,#409, #411,#413, #417and finally #418.

And yes..As you can see I like small incremental work and early feedback instead of giant pull requests. 😁

Anyway, the delta project has a lot of compilation targets and the binaries are automatically released in the GitHub releases page every time the project is tagged. Sweet. 😌

From an x86_64 architecture (TLDR: common 64 bit Intel or AMD processors) it is really straightforward to compile for a different operating system with cargo if you are targeting the same architecture. For example if you want to compile for macOS you just need to run:

rustup target add x86_64-apple-darwin
cargo build --target x86_64-apple-darwin

The problems start to arise when you want to compile for a different architecture, such as i686 (32 bit) or ARM processors. In this case, you have to install some dependencies and set some environment variables, which may be painful. For example, in the old continuous integrations scripts of delta,this was the way dependencies were installed. Ugly, I know. As rust developers we are used to great tools, so there must be a better way right?

Meet Cross

“Zero setup” cross compilation and “cross testing” of Rust crates.

This is the description of the Cross tool.

The TLDR is that it let you compile and test rust projects for architectures other than i686 and x86_64.

Instead of doing cargo build --target <YOUR_TARGET> you simply do cross build --target <YOUR_TARGET>. Based on the target, in fact, cross will run a docker image that has all the right dependencies already installed and configured by the rust-embedded team itself. 😉 And that’s it..just run cargo install cross and you are ready to cross-compile for allthese targets in rust, no other dependency is required, except docker of course!

Obviously this was not an exhaustive overview about cross and I encourage you to have a look at the GitHub page if you are interested.

Cross in GitHub actions

Of course, after a whole morning getting mad trying to setup weird ubuntu dependencies for the delta issue, when I found out about cross I felt very stupid for not knowing it in advance and I tried to integrate it in the Continuous Deployment delta pipeline.

It turns out that this is like the easiest thing in the world! The action-rs/cargo action I was already using had built-in support for cross. Now I even felt more stupid, but anyway..you just need to set the use-cross variable to true and you are done!

This is the step that builds the whole delta project for all its different targets..easy, right? 😀

Cross in Rust GitHub template

You may or (probably) may not be aware of Rust GitHub Template.

Rust GitHub Template is a template for cargo generate that aims to be a starting point suitable for the vast majority of rust projects that will be hosted on GitHub.

Beyond all its nice goodies, this template will setup Continuous Deployment for you, therefore whenever you tag your project, it will be published on crates.io and the binaries will be released in the GitHub Releases page, just like in delta. 😁

Until today, Rust GitHub template only supported x86_64 windows, linux and mac, but after I found out Cross I couldn’t resist and I added support for i686 and aarch64 linux architectures, which are both two tier 1 rust targets. In practice, this means your “old thinkpad” and “raspberry pi” users will thank you a lot. 😛

This is an example of the resulting Continuous Deployment step.

And that was it, after I spent a lot of very useful time trying to setup compilation dependencies basically I just wanted to share my love for the crosstool with the rest of the world in order to avoid this pain to as many people as possible. 😅

Thanks for reading this far! You can find me on twitter or YouTube, bye! 👋

📽 2 videos about rust code coverage in VSCode

Marco Ieni — Sun, 11 Oct 2020 10:18:28 +0000

Useless personal stuff

It's several years now that I feel the need to share what I learn with other people.
I gained so much value from free online content that at this point I consider
immoral for me to not give back something to the community.

I started my sharing process one year ago with my personal website and it has
been great!
However, in general I prefer videos to text, because I can watch them on the
go, while I am eating something and so on.
Making videos is something I wanted to do for a long time and now finally I
declare procrastination over (at the moment, at least 😅).

Code coverage in VSCode

We will use the following three tools:

cargo tarpaulin: analyzes your rust code and gives you code coverage data
cargo watch: run =cargo tarpaulin= every time we save the file
coverage gutters: show covered lines on VSCode

First video: basics

In the first video I explain the basics that will allow you to display which
lines are covered by your tests in VSCode.

Second video: let's automatize the process

I shot the second one after some really helpful feedback by some reddit users.
I show how to automatize the process with cargo watch.

Give me feedback!

These are one of my first videos and as you can hear my English is far from
perfect, but I'm trying to improve.
Please give me feedback regarding any aspect of these videos that you think I
can improve.

Anyway, I was very happy to receive users feedback after my first video:
it looks like sharing what you know is a really good way to learn what you don't. 😉

I hope my two cents will be useful for someone, bye! 😀

Create an amazing Rust GitHub project in no time

Marco Ieni — Sat, 05 Sep 2020 00:00:00 +0000

Introduction

Expectations on open source projects are becoming higher and higher everyday.If a project is not well documented and it doesn't have a test suite and a continuousintegration environment, it is very unlikely that it will be taken seriously bythe community.

Luckily for us, the tools to create high quality projectsare becoming better and better at the same time, too.

For example, rust provides:

the cargo build system which includes built-in support for tests and documentation
clippy static code analyzer
rustfmt auto formatting tool

These tools are well established and they are used by all the relevant rust projects.The rust ecosystem, in fact, is really homogeneous, in the sense that the way youbuild, test, run and deploy a certain application/library is very standard.

Therefore, when you are creating a new project, it's really likely that you canrecycle documentation and CI steps from your older projects or other bigger rustprojects out there..which is great, but as my java professor taught me:

if you are copying and pasting several times, you are almost surely doing it wrong!

And that's exactly what I was doing..In fact, every time I had to create a new GitHub project, I was using the goodcopying and pasting technique on:

the set of markdownfiles that GitHub asks you to fill, such as CONTRIBUTING.md, CHANGELOG.md, CODE_OF_CONDUCT.md, issueand pull request templates, and most importantly the README.md!
files needed to setup the CI environment, most of the time GitHub actions, specifically.

Now, because of the standard tooling that rust provides, copying and pasting worksreally well on these files, because as we said, what works for one project will almost workfor another one. But we can do better than this..

cargo generate

In order to avoid copying and pasting, there is the cargo generate tool, which isdescribed as:

a developer tool to help you get up and running quickly with a new Rust project by leveraging a pre-existing git repository as a template.

This means that you can setup a template repository, with all the files youneed and you ask cargo generate to create a project starting from thistemplate, by replacing project name and authors (and username soon?) with yours.

After using this tool to create some rust embedded projects with really littleeffort, I immediately appreciated its power and so during these days I decidedto use it to create a new template that makes me skip the copying and pasting phase ofcreating a new rust project hosted on github.

Rust GitHub Template

I have described the Rust GitHub Template on a website, where I describedits features and instructions onhow to use it to create a new rust project.

In short, it allows you to create a new rust project with documentation andGitHub actions such as automatic security checks, CI and CD already set up byonly specifying project name and GitHub username.You can see an example project generated by this template here.

As the Rust GitHub Template website states:

Stop copy pasting tons of markdown and yaml files each time you start a new rust project. Let’s write them only once, together!

Thanks, and I hope you enjoy using Rust GitHub Template!

Continuous integration with VHDL

Marco Ieni — Sun, 19 Apr 2020 00:00:00 +0000

Skippable introduction

During this lockdown (like almost everyone) I have a lot of free time, so I decidedto give a look at my to do list.In the looong term goals part where you can find impossible goals like "savethe world" or "learn haskell" there was "learn vhdl", too.

Now or never

That's what I thought. So here I am, reading the awesome free range vhdl bookand getting started with the first examples.I am debugging my nonsense signals produced by my nonsense code with VivadoWebPACK, which has some limitations, but it's free and it's a decent tool if you are learning.

Why writing tests

Anyway, getting the output right and going to the next exercise reminded me ofold dark ages when I was hacking my main and adding print everywhere to know ifmy code was working.Yes, your code might work now, when the sun is high and you haven't touched asingle comma of your codebase. But what if new requirements comes in or you have tofix a bug? You will unavoidably have to change your code. At that point how willyou be sure that you didn't break anything?

Yes, tests is the right answer. 💯And once you get used to them I can ensure you will never go back!In particular, I get used to repeatable tests and big green check marks thatensure you that your program does not work only on your computer and that youhaven't forget to git add some files.

So I thought: "why don't I try to setup Continuous integration for a VHDL project?" 😀

CI for VHDL

Easy, right? Unfortunately there was no GitHub actions that matched the word"vhdl" on the github actions marketplace. And there's a very good reason forthat. Hardware description languages like VHDL or Verilog are not like commonprogramming languages where nowadays everything is open source.Most of the people, uses whatever the FPGA makerprovides them, which includes proprietary libraries and so on and of course thisstuff is not intended to be used with docker and things like that.

Anyway, for my simple examples I didn't need vendor proprietary libraries,therefore I was free to explore open source solutions to run and tests my code 😀

I choose to use ghdl (an open-source simulator for the VHDL language)and vunit (an open source unit testing framework for VHDL/SystemVerilog).

It turns out that there is a really handy docker image hosted on the dockerhub, which provides both vunit and ghdl.

It was super easy to create a GitHub action based on this image, so meet VunitAction, a GitHub action that let you do CI with your VHDL projects!You can find how I used this action in my vhdl examples.

So yes, finally there is at least one match for the word "vhdl" in the Githubaction Marketplace 😅

Doc-org: org-mode + latex + docker = pdf

Marco Ieni — Wed, 26 Feb 2020 00:00:00 +0000

Why plain text is better than word processors

I was so tired of working with word processors like Microsoft Word that I created ~~yet another~~ a documentation system based on plain text.

With plain text you can:

use git
easily see differences between a version and another
use grep and other basic utilities
generate documents automatically with simple scripts
use my favorite editor

In short, with plain text I am free to do whatever I want.

Alternatives to word processors

The first thing you need in order to create a documentation system based on plain text is to choose a markup language.After many years of experiments with markdown, asciidoc and so on, I fell in love with org-mode.You can search for online demos if you don't believe me: if you are comfortable with emacs, there is nothingbetter than writing documents using org-mode.

Anyway, emacs does not reinvent the wheel and so there isn't a direct way to convert org-mode to pdf.What it does instead, is to translate org-mode into latex, which is the best language to create pdf files in my opinion.

So, by using emacs, you can export org-mode to latex in order to avoid writing directly in latex, which is too much verboseand it's not very readable until you export it.

This is how I have done my MSc thesis and overall I was happy of the final result.Anyway, when you try to mix your own latex customizations with latex automatically exported by emacs, it becomesa little bit difficult to achieve what you want.

That's why emacs has a body-only export option, which let you export only the body of your document.In this way you can have full control of your latex customizations.

Convincing your colleagues to migrate

So, given for granted that org-mode + latex is the best way to create pdf files you still need to convince your colleagues toinstall emacs and latex on their machines and to learn how to use emacs.Basically this is not possible. 😅

That's why I have created doc-org, a command line utility based on docker that generates pdf files starting from org mode and latex.The only installation requirement is docker, therefore you/your colleagues don't need to install and learn how to use emacs and latex.Of course you can edit org-mode documents with any editor, you are not forced to use emacs..it's just plain text! 😎

Here there are tons of example documents that are automatically generated by using github actions.Yes, you can version your small plain text files with git and then automatically build the pdf after every git push! 💪

Conclusion

I am very happy I have started this project providing lots of toy examples.I hope that more companies leave behind the idea of word processors, becausethe best way to write documents together is the same of writing code together: plain text + version control systems like git.

Checkout doc-org on github. If you have problems/suggestions just open an issue. 🤓

Linux on my 32GB windows tablet is surprisingly good

Marco Ieni — Sat, 11 Jan 2020 00:00:00 +0000

Why I removed windows from my tablet

I have a HP Pavilion X2 10-n105nl: an hybrid laptop/tablet with detachable keyboard and touch screen display. I bought it in 2016 in order to take notes at university with its keyboard and a Dell active stylus. It did its job pretty well, and for 210 euro I cannot complain.

However, time passes and windows gets bigger apparently. Now when it tries to download windows updates it complains that I have not enough space on the hard drive. So, I removed everything I installed on it, I created a new user and removed the old one. And the problem is still there. Even if I follow windows instructions and I put an external storage (a 64GB usb stick), it still needs additional 8 GB of free internal storage,which simply cannot be obtained, since almost all the available space of this tablet is occupied by windows itself.

Of course, using a laptop without security updates is not an option, but even if you consider it, windowsbecame really slow on this device, even if you just browse the web.

Basically this tablet became obsolete only after a couple of years.

Let's try linux on a tablet

During these Christmas holidays I had a lot of free time, so I decided to try to bring back to life this "old" laptop by installing Linux on it. I have to be honest, I didn't have a lot of hopes because in my mind linux was not good on detachable tablets.

First I tried pop os 19.10 and ubuntu 19.10. Since on my main laptop I run arch linux, I wanted to have a debian based machine.Well, I tried Bluetooth, wifi, touch screen and.. They all worked great!I was really surprised and happy to see this out of the box experience with linux on a tablet. The only problem was the speakers: no sound at all 😞

I looked online in order to find a solution. I tried a couple of those on Pop os, but my laziness suddenly struck a critical hit,so I thought:

why don't we try manjaro and see if sound works out of the box?

So I downloaded Manjaro 18.1.5 KDE version, which is a DE I wanted to try. And yes! Sound worked out of the box, together with all the other things I tested before. If you are curious, I have 19,4GB of free storage even if manjaro KDE comes with ~~too much~~ a lot of software preinstalled like libreoffice and thunderbird.

Now I am comfortably writing this article on a plane, thanks to my small 12" manjaro linux tablet 😃

Is it perfect?

Of course I bet that linux on this device doesn't do everything right, expecially without further tweaks. For example, one thing I noticed is that after that I close the lid, the device suspends correctly, but when I reopen it the touchpadtap to click doesn't work anymore.

I am sure that there are other little things like this that I haven't encountered yet (this is not my main machine), but.. hey, at least it works!

Installation instructions

In the following I put a short overview of what I did. If you have more specific question, please leave a comment down below.

If you do not own this device you may not be interested in this chapter. In this case move to the end of the article for the conclusions.

Save your windows licence

Open windows prompt with admin priviledges and type ```

wmic path SoftwareLicensingService get OA3xOriginalProductKey

- Write down your windows license because you never know.

## Backup your data

They will be erased, together with your windows install.

## Update your bios

Go to the [hp support page](https://support.hp.com/us-en/drivers/selfservice/HP-Pavillion-10-x2-PC/8499312/model/9788451) of this tablet and download and install the latest bios version. At the time of writing it's the `F.18 Rev.A` version. I installed it through their windows program without problems.

## Flash manjaro ISO

Put manjaro image on a USB stick. I used etcher to flash it. Plug the USB stick in.

## Disable secure boot

Reboot your laptop and press `Esc` repeatedly before the HP logo appears.

- Press `F10` to go to `BIOS Setup`

- Go to `System Configutation` tab

- Select `Boot Options`

- Select `Secure Boot` and disable it

- Press `F10` to save and exit

Congratulations, you are now free to install whatever operating system you like on your machine 😄

## Change boot order

Reboot your laptop and press `Esc` repeatedly before the HP logo appears.

- Press F9 to go to `Boot Device Options`

- Change boot order in order to place USB disk first.

Reboot the machine to boot into your USB stick, which contains the manjaro image.

## Install manjaro

Once you have booted into manjaro try if everything works and if you are happy install it!I choose the option to completely remove all the data on the hard disk and install manjaro on it.Furthermore, I didn't created a swap partition in order to save space on the hard drive.

# Conclusion

If you like me tought that linux was not ready for hybrid tablet/laptop devices, I hope you changed your mind at this point.If you have a device of this type that is not working as expected with windows, you can give linux a chance by trying it without installing it with a live distro on a USB stick.

_Check out my other blog posts at_ https://www.marcoieni.com/ 🤓

Keep a changelog!

Marco Ieni — Sun, 29 Dec 2019 22:42:22 +0000

In this article I will show you a changelog format and a convention for assigning numbers to your software versions.

The boring introduction

During these holidays I renamed one of my side projects, because I was so smart toname it like a registered trademark. 😓
I had to find a way to communicate this to the users, because manual interventionwas required in order to update.

The first thing that came to my mind was to place a big announcement at the beginning of the READMEin which I say that the project was renamed and the instructions required to update it. But then I thought: how much should I leave the message there?

For 1 month? Users could update also after this time.
For 1 year? Too many new users will be really annoyed by this big section.

The project we are talking about is intellimacs. Tldr: it is just a bunch of vim configuration files. Since the project is really simple, for a long time I thought that commit messages were enough to documentthe changes to the project. Turns out it is not, because since commit messages has to be small, there aretoo many commits with messages like "fixed typo" that create a lot of noise.

After this terrible idea I thought to build a full website with a blog were people can get updatesfor the project. This would not be so bad, but it is something that requires time to be built and that I'll have to maintain. Furthermore, for the user would be a pain to first read all the github documentation and then go through the websitewhere there will be inevitably duplicated info. For a project of this size, I think that keeping everything inside the github repository is enough for now.

Anyway, now the project counts 130 stars on GitHub, so all these people deserves to get comprehensive and coincise news about the project.

The best solution I have found for my problem is to keep a changelog. The user, before updating, can see on which version they are by running git tag and they can see what changedby reading this nice plain text file, which contains all the notable changes of the project.

It's something I always knew it was necessary, but that I continued to postpone with excuses like "my project is not too big yet" or "the project is very simple, commit messages are enough".

Well, turns out that now I added a changelog to my project and I found a really nice and efficientway to do it! 💪

Keeping a changelog

After some online research I found this really nice website called, in fact, keep a changelog. This website proposes a common format for changelogs which in my opinion is really nice.

This is an example of this changelog format:

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0] - 2017-06-20
### Added
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.

### Changed
- Start using "changelog" over "change log" since it's the common usage.
- Fix phrasing and spelling in German translation.

### Removed
- Section about "changelog" vs "CHANGELOG".

## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".

### Changed
- Improve argument against commit logs.
- Start following [SemVer](https://semver.org) properly.

## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.

## [0.0.1] - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a
  standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"

The changelog starts with a brief introduction and then it lists all the versions of the software.

Basically, when you make a change to your software, you add this change to the Unreleased section,in one of the following subsections:

Added: For new features.
Changed: For changes in existing functionality.
Deprecated: For soon-to-be removed features.
Removed: For now removed features.
Fixed: For any bug fixes.
Security: In case of vulnerabilities.

When a new release is ready, rename the Unreleased section with the new version number and the current date. And you are done! You have your changelog. The Unreleased section will be empty again, ready to be filled with your new awesome changes! 😃

Version numbers

Now..how to choose version numbers?

Well, for that the Keep a Changelog website indicates Semantic Versioning. This standard indicates that the software version should be in the format MAJOR.MINOR.PATCH. The initial version is 0.0.1. When a new version is released increment the:

MAJOR version: When you make incompatible API changes.
MINOR version: When you add functionality in a backwards compatible manner.
PATCH version: When you make backwards compatible bug fixes.

When you increase the MAJOR version, MINOR and PATCH go to zero, while when you increase the MINOR version, PATCH goes to zero.

A pre-release version may be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version.
Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

Even if this method is mainly indicated for public APIs, I decided to apply it even if my project has not public APIs. Of course, I started with version 0.0.1, but since my project is now stable and a manual intervention was requiredfor the update, I directly went to version 1.0.0.

For my project, when a new version is released I tag the git repository, for example:

git tag -a v1.0.0

Then I go to releases, and I create a new release for the current tag, where I copy the content of the changelog. I don't know if this is a best practice, but keeping the changelog only on github releases for me it's dangerous, since (as stated on keep a changelog website) it's not portable and I like the concept of having a plain text file with all the changes versioned together with the software.

Coderetreat is the funniest coding event I've ever attended

Marco Ieni — Mon, 18 Nov 2019 17:46:23 +0000

November 16th is the Global Day of Coderetreat and this was the first time I partecipated.

The subtitle of the website describe it as

a day-long, intensive practice event, focusing on the fundamentals of software development and design, away from the pressures of 'getting things done'.

Basically you pair program with strangers and instead of thinking about deadlines or legacy code that you have no time to refactor, you focus on best practices such as test driven development or some tricky challenges took from object calisthenics. The proposed problem is always the same every year: Conway's Game of Life.

BUT! 😱 There is one rule: every 45 minutes you have to change buddy, delete all your code and start over!

At the beginning you feel a bit of frustration, because you know that by the end of the day you will never finish that damn game, but everytime you start again you notice that you master the problem a little bit more: This means that iteration by iteration, you see your code getting simpler and cleaner!

In fact, one of my takeaways from this day is this one: if you have a portion of code that makes you struggle everytime the debugger goes into it, maybe instead of trying to refactor it you could try to rewrite it from scratch! I can ensure you that a lot of great ideas will pop into your mind if you have a blank editor buffer instead of old ugly code in front of you.

And what about 3 hours meetings just to decide if an option is better than the other? Maybe in less time you could have implemented small prototypes of both the solutions in order to see which one looks better and you can have something concrete to discuss on with your team. 😌

In conclusion, if you missed the coderetreat I strongly advise you to partecipate next year (you can check locations on the website) or if you can, try this exercise with a friend, it's really funny and you learn a lot.

Check out my other blog posts at https://www.marcoieni.com/ 🤓