When I wrote that blog post, I was living in a rented house. At the end of last year, my wife and I decided to buy a house in Nova Lima, the city with the highest HDI in our state. It is an amazing city to live in — we are in a gated community with a lot of green areas, and we are close to the city center.

Since the start, I planned to make it 100% off-grid. Our condominium already provides the water, so electricity would be our main focus.

I invested in 9 solar panels of 550 W each, 10 smaller panels of 160 W each, 4 batteries of 100 Ah 48 V (LiFePO4), and 2 inverters in parallel of 5 kW (10 kW peak) each, as the main system.

I also had a few spare flexible panels, and I used them to set up my old 24 V system, where I have 4 12 V batteries (2 in series) and one extra 100 Ah 24 V battery. Today it works as a complementary system to my EcoFlow Delta Pro, which I use as a complementary battery system for my network.

With that, my setup has approximately 28 kWh of storage and approximately 3 days of autonomy with low usage, or 2 days with high usage.

I DIY’d the entire setup and it was a great learning experience. The next step will be to learn how to produce food at home, enough quality food to supply most of what my family needs. For that, I am planning to implement a framework called “Sisteminha Embrapa”, a circular system of food production where we will produce tilapia, eggs, and vegetables.

The self-sufficiency activities turn out to be very fun, and an amazing hobby to work on during off hours.

Ever since AI coding took off, I feel like I am working without any blockers, and it is very easy to code for 8, 9, or 10 hours nonstop. Having fixed activities away from the computer like this keeps me sane, and they turn out to be very useful and save money as a side effect. I have not had a power outage or internet outage (because of Starlink) in over a year, and it feels really good — not to mention the $100+ I save every month on the electricity bill. Maybe food is next; let’s see how it goes.

This is exactly what I asked a few of my team leaders a couple of weeks ago: “What would it take for you to merge a PR without even looking at the code?” We had a bunch of answers, and in the end the conclusion was that it’s not different from what it was prior to AI. Namely:

• small, well-tested changes
• all CI checks pass
• a clear goal
• the PR is sized to the problem, no bigger, no smaller

Those are the PRs that are easy to merge, and that shouldn’t change regardless of whether AI or a human wrote the code.

If your process wasn’t mature before AI arrived, you won’t be able to capture the speed benefits AI offers. AI will produce far more code than we can ever review, and we have to be able to move fast. That means we have to be able to verify quickly if the code is harmful or not. That can only be achieved by automation, checks that verify (among others checks):

• the code does not introduce new security problems (Dependabot, Snyk, etc.)
• the code does not add excessive cyclomatic complexity, duplication, or similar code-smell signals (SonarQube, CodeClimate, etc.)
• the code is not doing something it was not supposed to be doing (This point is trickier and still need a human reviewer to judge.)

For the first time in my career, a developer has zero excuse: not to write tests, not to write meaningful and succinct documentation, and not to ship an end-to-end test that proves the fix works across the stack without introducing regressions. We should leverage that.

We should use these tools not only to produce more code but also to produce safer code, that is better covered by tests than ever, and code that, even if humans aren’t reading all of it, is easy to replace when the time comes. I’ve said more than once on this blog that good design is easy to change. That remains the core of good architecture in my book. With AI, even more so. If something is hard to change, if a change is touching way too much code and moving way too many parts, you probably should step back and check if that’s the direction you want to go. The design principle hasn’t changed.

Conclusion

Your answer to “what would it take to merge a PR without reading every line?” shouldn’t depend on whether AI wrote it. With a mature process, tests, coverage, and a clear understanding of the change, the decision is easy. Without those criteria, it’s not a PR worth merging. There will always be PRs you want to review carefully because they are bigger, more impactful, or riskier.

But there will also be PRs that are small, incremental steps forward, and it should be easy to scan them, merge, and move on. With AI we should have those on steroids, many small, incremental changes moving forward. If your process or tools don’t allow that, go back and fix them; otherwise you’re going to miss the speed this thing can bring us.

This is a widely accepted concept, as we can see in the following quotes:

“Refactoring improves the design. What is the business case of good design? To me, it’s that you can make changes to the software more easily in the future.” — Martin Fowler Ref

“Good Design Is Easier to Change Than Bad Design.” — The Pragmatic Programmer Ref

Therefore, to be a good architect, one must make things easier to change over time.

1. Learn to design change. Designing is not only about creating new things

Ninety-nine percent of what you do as an architect is designing change. Get used to learning existing architectures and seeing the emerging design. Most of your career will be about changing existing software. If you fail to learn the existing architecture or fail to recognize the design that emerges from existing projects, you’ll likely become the “let’s rewrite” person.

“Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure.” — Melvin Conway Ref

2. Avoid revolutions (No rewrites)

Revolutions may result in a better future, but frequently the revolutionary dies

By definition, rewrites are very risky. I like to call them revolutions. What you’re asking your organization or customer is to spend a lot of time, money, and energy to end up, months later, in roughly the same place and hopefully better. Revolutions sometimes result in a better future, but frequently the revolutionary dies in the process.

For that reason, rewrites must be avoided unless they are absolutely necessary. Small, continuous improvements are much better. The new always shines, and in the computer field there will always be new things fighting for a stake in the market. They will try to get your attention, read about them, run POCs, but don’t try to follow every new trend, which would inevitably lead to never-ending projects.

Assume that the person who wrote the old code might have known something you don’t

“ASSUME THAT THE PERSON YOU ARE LISTENING TO MIGHT KNOW SOMETHING YOU DON’T.” — Jordan Peterson

When writing the code that today is called legacy code, the person who wrote it had something in mind, and often this information is lost in the process. If you look at ugly code with arrogance, you will miss the opportunity to learn from it. Sometimes you’ll be lucky and they will still be around so you can talk to them and learn the reasons behind the code and why it was done the way it was. But most of the time, you have to act like an archaeologist and rebuild the context in which the code was created by looking at the final code and the commit history.

Don’t get me wrong: rewrites are necessary sometimes. I have led some big rewrites in my career as an architect; they often help solve problems the team is facing with the old codebase. On the other hand, most of the time they bring back old problems that the team didn’t even remember they had solved before; or the people who solved them are no longer around to explain why they did what they did.

In the book Built to Last, the authors have a chapter dedicated to the concept of “Preserve the core, stimulate progress.” This does not mean the team won’t make significant changes or try new solutions; rather, it means preserving what is well established and innovating around the core. Eventually, everything may change, but that should be the result of continuous progress rather than sudden, drastic revolutions.

Martin Fowler has an entire book on refactoring if you don’t feel comfortable changing a massive amount of code.

There are methods to change existing code and great references that would require more space than I can dedicate in this blog post. But if you are afraid of changing legacy code, you are most likely living in the “Edit and Pray” mode. You must change the mode to “Cover and Modify,” which is the correct way to deal with changing code. This is a reference to the book Working Effectively with Legacy Code, and I also talk about it in this very blog in the post How not to burn out when working on hard problems as a developer.

3. Code often and well (Code well)

Take on at least one coding task during each iteration (sprint, month, release, etc.). This is the only way to keep your skills sharp, understand the code, and ensure the things you are designing will fit well in the already running code.

Set an example for the other engineers by demonstrating the standards you want to uphold when writing code. Even the best design will fail if the implementation is a disaster.

4. Sync frequently (Biweekly Architectural Review)

Open a regular forum for people to bring design challenges. I run this every other week, and any person on the team can call an emergency meeting at any time if something has to be designed in advance.

At most, once every other week, run a meeting specifically to talk about architectural decisions and open space for people to bring architectural problems.

5. Document decisions (ADR)

“The only thing worse than failure is passing by accident.” — Everything in Its Place Ref

If you have been in a car accident, you know that when we make mistakes, we tend to rethink everything that happened, every second, and how we could have prevented it. We rarely, or never, do the same when we have success, and there are lessons to be learned in both cases. Documenting your decisions is crucial to evaluate why a plan did or did not work.

ADR — Architectural Decision Records

This is one of the most important points: use ADRs so future architects/developers working on your codebase understand the context in which decisions were made and what trade-offs you considered when they were made. As important as documenting what decision you took is documenting the context and what problems you foresaw and are willing to deal with the consequences that may come.

Every hard decision is controversial; otherwise it would be trivial and wouldn’t even be a decision. Therefore, it is important to document the controversy and why you took the decision you took.

ADRs are a simple yet powerful way to document decisions, with a template to capture the context, consequences, and alternative directions considered.

6. Use more than one architectural framework (Architecture style is not a religion)

I know many architects who focus on only one source for architectural style. Having only one tool for all problems rarely yields amazing solutions. To be a good architect, one must know more than one architectural framework.

• Hexagonal Architecture
• Clean Architecture
• Microservices architecture
• iDesign
• Event-Driven Architecture
• Microkernel Architecture
• etc.

Do not let architectural style become your religion. Read all of them, take the good parts, choose one that is close to your problems, and apply them in different contexts so you can learn where they fit and where they won’t.

7. Read and Write (Book club and internal blog, personal blog, notes)

Read the library documentation, good books (also the ones you don’t love but are well respected in the field), and argue from references and evidence.

Know the basics (Or at least have a good understanding of what they mean)

For each topic, I will provide a reference. Please do not feel obligated to read them all from beginning to end, and also do not limit yourself to the list I am providing here. Seek out other sources that will enhance your knowledge. (Check the reference links, some of them are old reads)

• Distributed systems Ref
• Design patterns Ref
• Database theory Ref
• Network theory Ref
• Formal verification Ref
• Automata theory Ref

Knowing the basics will help you to evaluate any technology, even if it is brand new and the problem it is trying to solve is not yet clear. For example, a web developer can still perform well without knowing much about TCP/IP or any other network theory or protocol. However, if they do know it, many problems can be avoided, such as preferring one request to bring more information rather than many requests bringing a small amount of information.

Notes

• Take notes and share them with the team. (I have way too many posts about this, check out the other posts about notes for more details)

8. Keep an eye on the future (Tech radar)

Research, experiment, and drive the future of the tech in your company. Things move fast and you, as the architect, have the responsibility to ensure the team and the company take advantage of new technologies that emerge in the market. That does not mean you need to rewrite your frontend in every framework that is released every other month (re-read my first rule if you need).

At leas once an year update the company’s tech radar, TW has a great template you can follow Tech radar example

9. Don’t take yourself too seriously (Be humble)

Interesting ideas come from everyone; even the most junior engineers on the team can bring the most interesting ideas. In fact, innovations often come from newcomers. Don’t get me wrong, specialists will have a view of the problems already documented in the literature and academia, but a new person may bring a perspective that by not limiting their imagination may lead to great solutions.

Listen to everyone’s ideas carefully, assess them, challenge them, and let them take shape no matter who they come from. Decide, document the decision, and move on.

10. (Bonus) Experiment

It takes time to become an architect, and it is not easy to train new architects. It may take years of formal training to get the academic background needed, and after that a couple of years experimenting in small and medium-size projects.

I struggle to see how any person could become a good architect without designing at least a handful of systems or making significant changes in big systems and dealing with the consequences of those decisions for at least five years.

That is why, when mentoring, I advise creating personal projects with paid users. This allows individuals to see how small problems progress and grow over time. Often, the trade-offs only prove to be good or bad after years. Sometimes this happens only after a new tech cycle (such as frameworks becoming obsolete or technological disruptions). Moreover, if you only design for your job, you may not be there to see all the consequences of your decisions.

Closing thoughts

This post focuses on the non-obvious things you need to do to become a great architect. Every architecture book will teach you how to design greenfield systems, and it’s not hard to find architects who don’t code (or even look at code) for years; in my opinion, that’s a clear mistake.

Use this as a guide for your journey. If you’re junior or just starting your career, don’t obsess over every detail. Take what you can remember, apply it, and come back in a few months or years to revisit what your next step could be.

In the city or in the neighborhood, it is normal to have issues from time to time. In this blog have wrote in the past about having a city blackout in the day of a very important meeting in 2022. Even having StarLink at that date did not save me from having a hard time to complete my working day as expected.

Not too long ago, there was a huge incident in Portugal and Spain where there was no energy.

How not to be impacted by these small or big incidents?

Off-grid energy is the solution. Like any other system, redundancy is necessary, and solar power is currently the most convenient option.

Today, it is inexpensive to purchase solar panels. In Brazil, you can buy panels for $100 that will generate approximately $1 of energy per day. You will also need a battery to store energy for use at night and when the sun is not shining.

After some research, I have learned that the best battery available today is a LifePo4 battery, which is already cost-effective to acquire.

If you do not want to make this a hobby, I advise you to buy an out-of-the-box solution like EcoFlow (my first one was an EcoFlow Delta 2 with an extra battery). These are extremely easy to set up. All you need is a solar panel (it does not need to be the expensive flexible ones they sell). Any panel in the same voltage range will work like a charm.

It was so easy to get it to work that I decided to learn more about this field. I put together a system myself using other components. Today, I have 2 MPPT charge controllers, 2 24v inverters, and 4 LifePo4 batteries on a second system connected to 2 strings of panels with 1.1K and 600w running +75% of my house. That is a conversation for a future post, by doing that you can save a lot of money and having a lot of fun to get it to work.

In conclusion, there is no magic in obtaining a secondary source of energy today. In future ports, I may bring my own setup and learn how to make it work technically. For now, if you need to search for Ecoflow or Bluetti and see how easy it is to set them up to work. I would advise buying one twice as big as the one you think you need. You will thank me later. Alternatively, take some time for a DIY project and save over $3,000 to get a project that can power 99% of your house.

I don’t think I will ever use only grid energy again. I am already planning to make my house completely off-grid in the next few years once I buy my “forever home.” It is a relief to see the whole city or neighborhood go dark and still be able to watch your favorite Netflix show with your wife before bed without worrying. That has happened twice since I start using Off-grid energy in the last 6 months. I am also paying 75% less to the grid energy company, even tho money was not the factor of this project.

The answer is almost always yes. But that is rarely the question you are really being asked. The real question is: Is it worth it?

Let me give you one concrete example. I will describe a conversation between me and my partner.

My partner: It is possible to reduce the image size of the images we store in our system? Compacting them during the upload? Or maybe we could use some service to remove it from the disk?

Me, if I were inexperienced: Yes, of course! There is this Scala lib that can do it. We can also migrate our storage to S3 and use cold storage for the images that are not being accessed.

Right there. I just created several hours of work to myself. And now we would need to worry about security of the new system, maybe new cloud bill to pay. Risk of waking up with a 10K bill from AWS. And so on.

Now, what did I really answer?

Me in reality: Yes, it is possible, but why would we do it now? How much is it costing us today? How much would cost us to grow it 10 times?

My partner: Today we have 160Gb and only 3 clients are using over 74G.

I went and checked the cost of disk in Linode (Our cloud storage) and it would cost 100 USD to increase 1T of disk.

Me: It is not worth it. I am not going to do it. With just two customers, we can pay for ten times that amount (Today, we have hundreds of customers).

My partner laughed and we changed subjects.

This conversation could have gone in many directions. If I were inexperienced, or had nothing better to do with my time (like writing this blog, LOL).

This is how I manage to run a side project with hundreds of customer for over 10 years, while having a full time job, family, my open source project and hobbies. I know how to choose my battles.

I love to give example with my own SaaS software because I will deal with the gains and losses of that decision, and if that means that I will have to get 1K USD less a year and have more time to work on the more interesting things so be it.

When working for someone else you not always have all the information to make the best decision. But you should always ask the questions and express exactly how much will something cost. Not only in time but also in infrastructure, money, and so on.

Next time someone asks you if something is possible, remember to ask yourself, “Is it worth it?” and go find the answer.

He had a great plan with many steps on how to implement a data warehouse and how they would clean the transactional tables every now and then to keep it “small”.

After hearing his plan, and giving him some architecture advice on the design and where it could go wrong, I proposed him to try something 100x simpler.

Analyze the queries and make sure every query gets to an index. Preferably a composite index that will meet the query fields. We talked about it for a while, I took some time to explain why that would work and how indexes work on databases (nerds).

And now I just got a message from him, “I just got a message from my customer Manager thanking me, one simple index improved the time to load one of the main pages from 30s to ~1s”.

Money saved, stress saved, and the simplicity wins for all. When trying to solve a problem, try to consider what would be a small change that could maybe solve this situation, that may be a great or even the best solution.

Source

Throw Less at the Problem

The new generation of programmers seems not to like software patterns, or Design Patterns for that matter, maybe because they are related to object orientation or bureaucracy. Yet, there is great value when we can all agree on a name for a problem, that means when I say let’s implement “Heartbeat” on this system, I don’t need to explain the entire problem before everyone in the conversation is thinking about the same thing, and it improves communication a lot.

Reading this book was great and gave me the opportunity to think about the solutions I implemented for the problems I found on the way while implementing NunDB. At first, I thought that there would be little to no match to my implementations, but I could find many of them in my code base: Segmented log, Leader and Follower, Replicated Log, Idempotent Receiver, and others. And a few that I am planning to implement for a while and now I have a name to give them, like “Majority Quorum” for writes.

The rest of this post may follow a different standard and are more like comments and bookmarks of where or how NunDB implemented the pattern, so there is no need to read them in order you can read the ones that may get your attention.

Segmented log (Chapter 4)

NunDB implements segmented log to divide oplog into 10 smaller files, making it simpler to manipulate and manage files. Also improving issues with disk space and performance. Here is where we implemented it.

Leader and Follower (Chapter 6)

NunDB implements leader election to ensure writes goes to a single central node, called primary. Here is the implementation. though NunDB started as a single primary node, there has been implementations to move it to a multi-primary database.

• Having multiple primaries will allow it to scale it horizontally in reads and writes.

The idea is to have one leader per shard? Or per database or key? This is yet to be defined. Or not to have leader at all the deal with conflicts just like our arbiter feature.

Heartbeat (Chapter 7)

• NunDB still not implemented this but it is on the plan, today we failed a replication connection from the replicas and it would be easy to implement it.

Today, we expect an event to try to access the other node. Only then will we disconnect it. It is being a while I want to implement this feature in NunDB so today I decided to create an issue to implement it, I will probably soon be working on it.

Majority Quorum (Chapter 8)

• NunDB does not implement majority quorum so to speak, we do have something pretty close Here, where we only remove the transaction from the pending list when it has been acknowledged by all replicas. This can be used to create similar logic to majority quorum transactions.

All the consensus algorithms are based on the majority quorum principle Raft, Zab, and Paxos.

Replicated Log (Chapter 12)

NunDB uses in it Here. This is a very common patter, we implemented it based on learning from databases like MongoDB but also using minor optimizations focused on performance. Worth reading the post about the implementation in A fast-to-sync/search and space-optimized replication algorithm written in rust, The Nun-db data replication model

Single Update Queue (Chapter 13)

NunDB uses with a single thread to replicate and one thread for each node coded here. Here we guarantee that there is only one thread per node using channels so many thread can send messages and only one thread can process them.

Idempotent Receiver (Chapter 15)

NunDB uses idempotent receiver in the acknowledged operation from replica sets. When sending back an ack message to the primary, the primary stores the state of the operations and will only change the count once, even if the server sends the message multiple times.

We could also implement this to any client, since we hold an instance of each client. One interesting aspect of this implementation is that if an server sends a message with an id all smaller ids can be ignored as if the newer id means the client is Ok with the previous messages (this is very important to performance and save memory, today we store all ids in memory to ensure it is safe).

Follower reads (Chapter 16)

NunDB implements this by allowing clients to read from any node but only writing to the Primary node. This is by design, we guarantee that if the client watches a key, it will eventually receive the last value state of the key.

Version Value (Chapter 17)

Implemented here. In NunDB we use value version to detect conflicts between nodes and clients (when operating offline). If there are some conflicts we must have an arbiter to solve it and the key will be on a -2 version state until this conflict is solved.

I like the way CouchDb solved this, creating kind of a tree, NunDB does not have that instead it go creating a list of conflicts that can later be solved by an arbiter client whenever needed.

Single Socket channel (Chapter 30)

To replicate from primary to secondary NunDB uses a single socket to ensure the ordering of the messages.

In the module replication_ops we create a socket that will later be used to send the messages from primary to secondary or from primary, we later use a channel (I mean the send receiver channel class) to ensure only one thread will be handing the socket send.

Request Pipeline (Chapter 32)

Requests do not need to wait for the response from one command to send others, this is made to ensure we can process all request in parallel, and we create an list of responses to send back to the user, in the WebSocket implementation for http requests for example has the protocol is made to be request response our trick to support multiple commands was to send all of them in the request body separated by ;, process one by one and send all the responses in one single response.

Conclusion

NunDB does not support data partition yet, that is why there are no mentions in the post about those chapters. I was surprised by the amount of patterns that I found in NunDB while reading this book, most of them I learned while exploring other source code or reading books about data processing but I did not have a name to give them. I would not say this book is a must read if you are implementing a distributed system, there are others that I think will help you more (Like for example Designing Data-Intensive Applications: The Big Ideas Behind Reliable, Scalable, and Maintainable Systems).

It may be a great start though, if I had read this book before writing NunDB I may have identified some of the problems I had in the implementation and giving it a proper name.

Where to find the book?

Amazon

A technically strong team; Working on a testable outcomes; With short feedback cycles is the recipe for success in software!

I truly believe in that; though I am not the original author, I heard Uncle Bob say that many times, too, and read it in good books in different forms.

@ThePrimeagen seems to agree with that statement as well partially. The only occasion we have chatted on Twitter seems to have resulted from the conversation.

Since this seems to be an settled matter, maybe the more interesting questions are how can we create strong team?

1. Can we build strong teams from scratch? In fact, I have done this at least once. Around 2013, I led and built a team of junior developers who are now principals, staff, and engineering managers in various companies worldwide.

At that time, we hired talented young people and would battle-test them in challenging situations at a large ERP company (Teknisa), which led to the formation of a great team.

It took three years to assemble that team, hiring about ten people per year and promoting the most passionate and talented individuals. Three characteristics stood out in those individuals other than technical excellence: Ownership, Accountability, and Communication.

Finding that level of patience in today’s industry is hard. There are few opportunities to train individuals, and today’s market (at least the USA market) is only looking to hire senior developers.

2. Can we hire only experienced developers and assemble a strong team? That could be an option; the problem here is the cost. To put part of my 2013 team together again today would cost over 1M USD (for a team of ~5 people) a year only in salary, and to keep all of them excited, the thing we are working at would have to be quite challenging. This is possible, but it does require a multi-million dollar problem to justify the cost.

3. Can we strengthen an existing team of talented individuals and help most of them become top engineers? This may be the way to go. It may be the perfect balance between cost and results. Since I started working for USA companies around 2016, I usually joined already-formed teams or hired senior developers and trained them to master their weaknesses.

Acting as a mentor and as an example, creating a writing culture, attacking the most critical problems documenting the solutions and the process, setting up the right patterns to attack any problem are my strategies for achieving that propose.

My intention in this post is more to document the questions than to propose answers. I documented 3 possibilities to create strong teams. I am always learning and researching new ways to improve my teams and myself You can be sure I will share in this blog what I have learned in the future, thanks!

During the last holiday (4th of July), I visited a coffee shop in Belo Horizonte, and I was planning to work for a couple of hours from there. I ended up going back to my house because I did not feel welcome to work from there. It does not seem like this is only happening in Brazil in Europe I have seen people complaining more than once.

The situation is quite different in small cities, though. When I lived in small cities like Luz-MG and Paraiso-MG, where business owners seemed to enjoy having people working there. We would spend 10 or 20 USD and work for 2 or 3 hours, usually very productive hours. People would often ask me about the work and what was I doing and show interest and even offer WIFI (most of the time I don’t ask for WIFI because I prefer to work from my 4G connections).

In big cities like Belo Horizonte, the owners don’t even make Wi-Fi available anymore, and I can only interpret that as not welcoming remote workers. I don’t blame them; in big cities, people often take advantage of these owners by buying coffee and working there for many hours, which ends up not being worth it for the coffee shops.

In small cities, it is common for coffee shops to be nearly empty for long periods of the day, so the owners are happy to have people working there, spending money, and keeping the places moving. In big cities, the problem is the opposite. They are usually full, and the owners want to keep the tables moving, so they don’t want people working using the tables that could be serving the next customer.

Where should we work from then?

The alternative is to work from co-working spaces made for that purpose, where remote workers will be much more welcome. In BH, there are many alternatives, such as WeWork, Regus, and Impact Hub. I have worked in all of those places, and they are great places to work from. The cost is not that high, usually between 10 and 20 USD per day, and more offer free coffee (An awful coffee, but it is free).

Conclusion

I love to change the place where I work and I think it improves my productivity when I move to different places. Nevertheless, I don’t want to be on a place where I am not welcome or that people think I am taking advantage of them. That is why I also choose to live in smaller cities where life it a calmer and where people doing business are more friendly and welcoming.

Most business happens in Big cities, and I understand why people want to live there if their jobs require going to the office multiple times a day. But for remote workers, we have options. Small cities sometimes offer a better quality of life, a cheaper cost of living, and fewer grampy coffee shop owners. Maybe try that the next time you visit a place.

Rust projects have great test tools that are out of the box, like `cargo test, ‘ but do not include a code coverage tool. In this post, I will show how I introduced it to my project NunDb.

The tarpaulin tool

Tarpaulin is the tool I chose; tarpaulin is not in a stable version yet, so make sure to make a version that works for your case. Read more about it in the tarpaulin repo.

Install tarpaulin

cargo install cargo-tarpaulin

In my case I had to install the nightly version of the tool, so I had to run the following:

cargo +nightly install cargo-tarpaulin

By the time I am writing this post, the latest version of tarpaulin is v0.30.0.

Running it locally

Starting from the simplest case, to run all the tests, run the next command in the base of your project:

cargo tarpaulin

That may work for your case, but it did not work in my case, I have many tests that are not well suited to run in parallel because they write to disk (NunDb is a database and all tests run in the default config saving to the same place), so I had to run the tests with only one thread, like this:

cargo tarpaulin -- --test-threads=1

Ignoring performance tests

It still did not run all tests successfully. As tarpaulin has to calculate the coverage, which slows down the tests quite a bit. Therefore, I had to skip some performance tests by adding #[cfg(not(tarpaulin))] in the tests I wanted to skip, like the following:

    #[test]
    #[cfg(not(tarpaulin))]
    fn restore_should_be_fast() {
    // ...
    }

Checking the e2e tests

That was progress, but my E2E tests were still not working because in order to run all tests for NunDb, I had to run multiple instances of the database and kill the process at the end of each test. To support that, You have to enable the ` –engine llvm` flag in the tarpaulin command since the default engine “relies on the sigtrap signal to catch when the instrumentation points are hit” read more here.

Additionally, to report the code coverage from the running process called in my E2E tests, I had to add the --follow-exec flag.

Here is the final command I used to run the tests:

cargo tarpaulin --engine llvm --follow-exec -- --test-threads=1

All tests were running locally as expected now \o/.

By default, tarpaulin will force you to clean the build, which is most likely what you want for CI, but it slows down quite a bit for testing locally, so you may want to add the flag --skip-clean to speed it up when running locally.

It would look like the following:

cargo tarpaulin --engine llvm --follow-exec --skip-clean -- --test-threads=1

Running it on GitHub Actions

At this point, I was happy locally. Let’s start the work to get it to run on GitHub Actions.

The first step is to create a .github/workflows/coverage.yml. That file will be used to run the tests and push the result to Codecov.

For that, you will need three steps:

1. Checkout the repository

This is the most straightforward step. You need to add the following lines to your workflow file:

      - name: Checkout repository
        uses: actions/checkout@v2

2. Run the tests with tarpaulin (where you can pass the flags you want)

This one is a little bit more complex, first I set the environment variables I need to run the tests, TIME_TO_START and NUN_ELECTION_TIMEOUT and I also use the command we came up with before:

      - name: Generate code coverage
        env:
          TIME_TO_START: 4
          NUN_ELECTION_TIMEOUT: 3000
        run: |
          mkdir dbs&&cargo +nightly tarpaulin --follow-exec --engine llvm --verbose --all-features --workspace --timeout 120 --out xml -- --test-threads=1

3. Upload the results to Codecov (Needs setup in the Codecov website prior)

Now we are close, it is time to upload the result to Codecov. For that you will need to add the following lines to your workflow file:

      - name: Upload to codecov.io
        uses: codecov/codecov-action@v2
        with:
          token: $ # not required for public repos
          fail_ci_if_error: true

To get the CODECOV_TOKEN, go to the Codecov website, authenticate with your GitHub account, find your repo in the list, and click on Configure; on the next page, you will see the token to be copy pasted into the GitHub Secrets.

To set up the secret in GitHub, go to your repository, click on Settings -> Secrets and variables -> Actions, and add a new secret.

The final file should look like this:

name: Code Coverage
on:
  push:
    branches:
      - master
  pull_request:
jobs:
  coverage:
    name: coverage
    runs-on: ubuntu-latest
    container:
      image: xd009642/tarpaulin:develop-nightly
      options: --security-opt seccomp=unconfined
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Generate code coverage
        env:
          TIME_TO_START: 4
          NUN_ELECTION_TIMEOUT: 3000
        run: |
          mkdir dbs&&cargo +nightly tarpaulin --follow-exec --engine llvm --verbose --all-features --workspace --timeout 120 --out xml -- --test-threads=1
      - name: Upload to codecov.io
        uses: codecov/codecov-action@v2
        with:
          token: $ # not required for public repos
          fail_ci_if_error: true

Now, when you push code, you should see the tests running and the coverage being uploaded to Codecov.

Adding the badge to the README

In your Codecov project page, you will find a link to Settings and then Badge; there, you will find the markdown to add to your README file.

Something like this:

[![codecov](https://codecov.io/YOUR_REPO/branch/master/graph/badge.svg?token=YOUR_TOKEN)](https://codecov.io/gh/YOUR_REPO)

Conclusion

Adding cover coverage to your project can help you monitor the modules your automated tests are neglecting. Keep in mind that a single number does not define the quality of your project. Enjoy the coding and use the tools for what they are good for.