DEV Community: Santiago

The Ultimate Clipboard, period.

Santiago — Wed, 10 Apr 2024 13:00:00 +0000

It’s no secret that we, software workers, search on the bast internet sea for answers to our problems. And when we find them, we copy them, and paste them on our project. But some times we need to replicate the solution we implemented to fix an issue, to solve another issue somewhere else. And some other times, we just want to copy and past some stuff. And… some other other times, we may want to do all that at the same time.

If you’re like me, then the “regular” clipboard runs short pretty fast, and quite frequently as well. A few years ago someone recommended me to install this tool, and my life changed completely after that… at least my life from 9 to 5 from Mondays to Fridays…

Let me show your how to install and use the ultimate clipboard you’ll ever need. All aboard!

Clipy

I know, you thinking about that old pet from certain writing tool right?

Sorry, but no, is not that one (though you can have it back if you want it: here). The one I’m talking about is with a single P. Clipy is a Clipboard extension app for macOS.

Its idea is simple enough, add a history to your clipboard. Each time you press “Cmd+C”, it gets added first on the list of you clipboard history. “Cmd+V” paste what you have at the top of the clipboard history. And if you press “Cmd+Shift+V”, you get to pick what to paste from your history.

And it doesn’t stops there, this tool not only adds more room to your clipboard, but also allows you to create snippets to store your most commonly used “pastes”. You can even create “folders” to group them and have some useful code snippets, URLs, Ascii Emojies (¯_(ツ)_/¯) , or commands.

Get it

The installation is pretty straight forward.

Download the binary from their distribution site: https://clipy-app.com/.
Move it into your Applications folder.
There is no step 3.

How I use it

It has proven to be extremely handy in many occasions to me already. On my daily work I’m used to copy a lot of commands, some to replicate on different environments, or simply to run again later. Also, copying some values to add to my code or commands, and being able to reuse that data later on is really useful as well.

Regarding the snippets, I use them to keep at hand the commands and code sample I use the most. For instance, I work with many git repos and branches, and I like keep my workspace clean, that means, removing merged and deleted branches for instances. Of course, deleting them one by one not only is boring but also time consuming. So I have this git command to delete all branches on my local that have been removed from the remote repo:

git fetch -p && for branch in $(git branch -vv | grep ': gone]' | awk '{print $1}'); do git branch -D $branch; done

Feel free to add it to your snippets :D. I also have a commands to create a diff report between tags, another one to calculate the cadence of a branch, and even the LOCs (yeah, still use that one sometimes).

And since I’m an automation maniac, I also keep a template for any new script I create:

#!/usr/bin/env bash
set -o errexit

set -o nounset
set -o pipefail
if [["${TRACE-0}" == "1"]]; then
    set -o xtrace
fi

main() {
    # Add Code Here
}

main "$@"

This is the template I use to create a script with some of the best practices I like to have implemented on my scripts from the very start. Those are:

errexit : the script exist whenever any commands returns a non-zero code. So you don’t miss any execution errors
nounset : the script will fail if you try to use any environment variables that hasn’t been declared. So you don’t forget to initialize them or mistype any names.
pipefail : I use pipelines a lot ( i.e.: command 1 | command 2 | command3 ), by default only the exit code of the last command is returned. By enabling this option, if any of the commands fail, the script will return the error code instead. This has saved my hours of debugging time.
xtrace : If you run the script by adding “TRACE=1” in front of it, you’ll get a lot of extra logs to debug.
main function: the main login of the script encapsulated on a function.

Go For It

This is one of the very first tools I always get installed on new machines. It has proven it’s value to me, and I can’t conceive my daily work with out it nowadays.

Hope you find it as useful as I did, and feel free to copy my snippets as well

Enjoy! *Sails away….

Evolve your DevOps NOW! Starting Point

Santiago — Wed, 06 Mar 2024 13:00:00 +0000

When I started working as a Configuration Manager back in my days at Motorola little did I know that I’d end up on a journey to find a proper path to make DevOps grow and evolve. But here I am, after a some really long years (13/14 months each… #BadJoke) of traveling on the high seas, researching, implementing and learning, finally reached to a good port, found a cool treasure map and I’m willing to share the treasure I found with you.

Lucky for us, the treasure chest is big, sadly, is too big to fit on a single post. So, since I’ll have to split it into multiple posts, I though I could do it iteratively as well. I’m going to start, in this post, talking about the general idea of the model, and how is structured. Then we’re gonna review the model again, going in deep on each level of it (more about this in a min), and finally we’ll do a third iteration to check the goals and practices of each levels.

Raise the anchor sailor!

The Map

How would you recognize a treasure map? I mean, we’ve all seen treasure maps on the movies, and games before. These pieces of old paper with drawings in them and a big red cross showing were to start digging right? But we’re on the information era, how does a treasure map looks nowadays? In this case, it takes the form of a Maturity Model. Cool, ok, but what’s that (you may ask)? A MM is a tool to evaluate the development and performance growth of a group (or individual). It places an individual’s performance against the established stages of growth and expertise.

Let’s put it in other words. Imagine you have a plant on your desk. A tiny plant you want to make it grow and get big. For that you have a ruler, but an special one. If you place the ruler next to the plant, you’ll be able to measure it. The ruler will tell you if it’s your plant is tiny, small, average, or huge, so you’ll know the size of your plant. But this ruler is special remember? Not only will tell you how big your plant is, but also will tell you how to make it grow to the next size.

A MM works the same way, it allows you to measure your DevOps Team or Area, to understand how matured and evolved it is, and at the same time gives your the steps to follow to make it move to the next stage of evolution, or maturity level.

Process Areas

These steps to go from level I to level II are specific goals that the team will have to accomplish in order to complete the maturity level, and be ready to sail to the next one. If you’re at level I, and wish to reach level III, you’ll have to complete level II first.

The steps are grouped by categories to make them easier to manage and understand. there are 5 categories, that we’re going to call Process Areas , they are:

Source Code
Testing
Environment
Monitoring
Templating

The practices grouped in Source Code area are related to code change management, like ensuring its integrity, detecting integration issues, continuous integration implementations, test results reports, code coverage and static analysis, and so on.

The Testing area brings together the practices related to the management of unit tests, functional tests and integration tests. Notice that functional and integration test suites require a running environment, those practices tho are not included in this process area but in Environment , which groups the practices involved in managing the software application execution environments. Specifically in identifying what environments will be necessary (production, test, development, staging, pre-production, etc.), the characteristics of each one, and the processes necessary to create them and ensure that they meet the stated requirements.

Monitoring groups together practices involved in real-time and statistical monitoring of software environments and applications so that erratic behavior can be identified and alerted when they occur (or sooner, if possible).

And finally, the Templating area contains practices to generate patterns and templates of processes and (software) projects to expedite both the start of a new project and the replication of changes and improvements in multiple projects that are based on the same templates. In other words, just as code reuse is encouraged in programming, this area promotes the reuse of solutions found in other processes and projects.

Sailing to the next port

The next stop on our journey are the Maturity Levels. The following post will introduce some of the specific practices and how are they organized into these levels that will eventually help you make your DevOps grow strong and evolve.

But tell me, what do you think about these process areas? Can you match the practices you follow into any of them?

How to document when you don’t like documenting

Santiago — Mon, 26 Feb 2024 11:00:00 +0000

I don’t really like writing documentation, and I can count with half a hand, the number of engineers I’ve worked with that truly and honestly liked to do it. But, if there is something I dislike even more, is having to answer the same questions over and over about how to use my app or script.

Due to that (in your face positive motivation) I’ve spent some time learning a few tricks on how to create documents easy to read, and easy to write, with out having to spent much time on them, and I’m willing to share them with you.

Set the Course Sailor

Just like when sailing in the middle of the sea, you need to know in which direction to point your boat. Or you could end up messing it up big, really big. When writing docs you need to know which is your target audience.

Your target audience will define how technical you can get on your explanations, and will give you a better idea of how people will interact with your project. For instance, if you’re writing for developers, you may want to include more technical details and even some insight of internal design, and expect them to make a more advance usage of it. On the other hand, when writing for people how “doesn’t speak dev” ( like a marketing team), you’ll have to reduce the number of technical words and expect a more basic usage of it.

Do not try to… let me emphasize that, DO NOT try to create a document for both, technical and non-technical audience. It’ll be boring for technical folks, and confusing for non-technical ones. If you need to target both, create separated documents.

Once you know who’s gonna be reading your doc, its time to sit down and start writing.

The IBM Pattern

No, this is not the “International Business Machines” pattern, its the “Intro-Basic-More” pattern, based on the KISS principle (Keep It Simple, Sailor). What is that IBM thing? Is a simple mnemotechnic I use to remember that any documentation (like a README file) should have the following:

An Introduction section, explaining what the tool/service/project is about. It has to be concise and brief. Don’t overthink it, one sentence or two at top, and that should be it. You can also include the (one-liner) install command here.
The Basic Usage section should show the users how to achieve the most probable reason why they want to use this tool/service/project, and only that. If you’re writing a doc for grep, the basic usage is grep 'skywalker', if you’re writing a doc for curl, the basic usage is curl starwars.com. Give them what they came to find right away.
Last but not least, More Questions. This section should present a way for the reader to find more information if the basic usage is not enough. It could be a list of FAQs¹, how to use the “help/usage” command, a link to a more detailed document (like a Swagger based site), or a way to contact you (not recommended).

By following this patter you’ll make sure that anyone who reads it will get a clear idea of what you project is for and what it does, how to make a basic usage of it, and how to get more info if needed.

VHS

Some of you may say “Sounds great Santi, but how can I document the basic usage if I don’t like documenting”. Argh! What a predicament, but I got you covered.

There is this tool I’ve been using for showing users how use my scripts and apps, with little to no effort from my side. It’s called VHS (yes, as in Video Home System ) and it allows you to create GIFs of commands running on a terminal, from the terminal. Is not a recording app (tho it can do that as well), it’s a GIF generator.

You can instruct VHS to create a GIF running your app. And update that GIF automatically on every release. So you’ll get your documentation up to date effortlessly.

For instance, this is a script I wrote for dev teams to create a couple of Kubernetes manifest files. It has many options to customize those manifests, but for most common usage, which is a new app for development, this is more than enough:

Get Your Own Boat

Let me show you how to use VHS by following the IBM pattern.

VHS Intro

This tool allows you to create terminal GIFs as code for integration testing and demoing your CLI tools.

Install it by simply running: brew install vhs. Check for more install options here.

Basic Usage

Create a new vhs_demo.tape file with the following content:

Output vhs_demo.gifRequire echoSet Shell "bash"Set FontSize 16Set Width 800Set Height 450Type "vhs vhs_demo.tape"Sleep 1sEnterSleep 5s

Change the “Type” command with your own.
Execute VHS to generate the GIF:

Get the vhs_demo.gif file generated on the same folder.

Raise the Sails

Following this pattern, and using VHS for adding examples and expected outputs has helped me a lot to reduce the number of times people needs to come to me for help for common tasks. Hope it helps you too.

What do you think about it? How do you write your docs? I really wanna know

Frequently Asked Questions

The Way You Need To Evolve DevOps

Santiago — Wed, 21 Feb 2024 07:07:00 +0000

Nowadays we have stoped measuring how many organizations have adopted DevOps practices to start measuring how advanced the implementation of those practices is. This is not really optional anymore but a standard. And yet we still find it hard to define exactly what DevOps is, or how to start from scratch.

We could agree on some general ideas, like that it’s a cultural change, that its main goal is to make the ops team to move at the same phase as devs, and that it helps empowering the dev teams/cells. But on the other hand, some would say it’s better to start from a dev team, others would say it’s better to start from an infra team. Some teams put their focus on pipelines automation, others on deployments and monitoring. And the list of differences goes on and on and on.

As an academic researcher and a DevOps team leader I’ve dedicated a couple of years researching, analyzing and applying DevOps practices trying to figure out which is the best way, if any, to do it. I found, of course, a lot of material to read, watch and listen to, but I decided to go the extra mile, and find the path my way.

Sailing to Unknown Port

The adventure started with some reading. A lot of reading actually. As I said, there are a lot of articles, books, courses, reddit threads, etc. where to look at. Used those as an input to create a list of the common practices, metrics used to measure success, and issues or problems that motivated teams to go the DevOps way.

Then, it was time to start talking to people. With those lists at hand, I started interviewing other DevOps leads and experienced software engineers to get their feedback and thoughts about them. Asked if they have implemented any of the practices listed there, if there was anyone missing, if they have used any of those metrics, or have had those issues. Interesting enough, they gave me pretty similar answers. Practices weren’t implemented the same way, or the metrics used weren’t exactly the same, but there was some sort of pattern to be discovered there. So, it was time for moving forward.

Next step was to create an online survey with similar questions to the interviews, and ask every software company and organization around my city to fill it. It took some time. The quarantine and curfew got in the middle so there wasn’t much to do but wait, but it was worth it. Once I got enough answers, a preliminar analysis started to show what I was expecting, a pattern, a path.

After closing the survey I went full researcher mode. I deep dived into the sea of data points and open answers, and emerged back to the surface (a few months later) with a treasure map.

The Treasure Map

I found that there is actually a possible path for a team or company to follow to go from zero to fully mature a DevOps area. Actually, I believe there are many, my treasure map is simply one of them. A clear and reproducible guide to follow to safety reach the wonderful DevOps bay.

With a map in my hands I was exited to see if it would take me where it was supposed to. So I followed it. Started with a single project, going step by step, slow but steady, cautious, double checking everything before taking the next step. Results were great, but it could’ve been a coincidence, those happen after all.

I tried next with a couple of projects at the same time, from different teams and technologies. Moved a bit faster in this occasion, and got great results as well, and excellent feedback from the dev teams. The map wasn’t lying.

And finally, I got the chance to test it once more, but this time, with the goal of building a DevOps area from scratch on a new company. It took much more time than the previous experiences, but it proved the path we were following was leading us in the right direction. By the time we were half way there, the devs and even the managers had already noticed some big changes for good.

Get the Gold

I don’t want this secret treasure map to remain, well, secret. Being the treasure a well implemented set of best practices related to development, testing, monitoring and automation, I want everyone to get a peace of it, or all of it.

The map ifself consists of a Maturity Levels Matrix, similar to CMMI levels. Each of which have a set of goals to help you achieve the implementation of the best practices related to it. By creating a roadmap based on this matrix, you’ll be able to create and grow a DevOps culture on any team, organization or company.

Explaining and properly teaching this tools and their processes will take me several posts for sure, so I’m inviting you to embark with me on this trip so you can also find and enjoy the gold of the DevOps treasure chest.

EDIT: Check the followup post here.

All Aboard!

Join me on this journey! On the follow up post I’ll start explaining the maturity model in detail.