I tried the transcription apps. The ones that record your calls, generate summaries, extract action items. I believed in them for a while.

Then I stopped — not because the tools got worse, but because the entire problem they solve stopped mattering.

If you still believe recording your team meetings and processing them “somehow with AI” is the move, I have bad news: you are a couple of steps behind.

The action problem

Think about what happens after a typical meeting. Someone says “I added that to my notes.” Someone else says “I’ll schedule a follow-up.” You nod. The call ends.

Sometimes you return to those notes. Often you don’t. When you do, the context is gone — you remember the words but not the energy behind the decision, not the nuance that made it feel urgent in the moment. The organizational machinery stutters, but everyone accepts it because that is just how meetings work.

Every time, action is postponed. Postponed means delayed. Delayed means something is lost.

Transcription does not fix this. It makes the record more accurate, but the gap between “we discussed it” and “it is done” stays wide open.

Now compare that to what happens when your team works with AI agents in real time. You do not say “I will update the spec” — you say “I am currently updating the spec.” You do not say “I added that to my notes” — you say “I have already launched the change; as soon as it is implemented, you will be notified.”

The meeting itself becomes the execution environment. Not a better transcript -- a fundamentally different kind of meeting.

Subscribe now

The privacy problem

There is a second reason transcription was always fragile, and most people avoid saying it out loud: recording changes how people behave.

When a meeting is recorded by default, everything someone says can be used as evidence later. People know this. Some are fine being wrong in front of others — they say something half-formed, get corrected, and move on. But others start filtering themselves. They feel exposed. Less professional. And you will never fully fix that dynamic, because leaders are not personal therapists. You work with humans as they are, not as you wish they were.

Now push it further. Even if your team is comfortable with group recordings — would they accept you transcribing one-on-one meetings? Every phrase. Every word. Would they truly be comfortable sharing something private, something vulnerable, knowing it is captured forever?

I asked managers about this directly. About nine months ago I posted in r/managers asking if people struggle with 1-on-1s. The responses confirmed what I suspected: the managers who cared the most about building trust were the ones most opposed to transcription. One put it simply — 1-on-1s are for talking to the person, not the title, not the role. That space only works when it feels safe. Another described action items from 1-on-1s sitting in shared docs going nowhere: “Nothing moves forward. It feels like a broken process, with missing pieces in the puzzle”. The community was fragmented across dozens of note-taking tools, all solving the wrong problem. Nobody had solved action-closing.

This is a problem you cannot fix with better transcription tools. And honestly, you probably should not try.

As AI-native collaboration reshapes how teams work together, this tension dissolves on its own. When agents handle execution during the meeting, there is less need to capture what was said — because what was said has already become what was done.

The shift

I have started paying attention to something small that changed how I think about all of this. Every time I get the automatic feeling “I need to note this down”, I pause — because I now recognize that instinct as a failure signal. It means something should have been acted on and was not. So instead of writing it down, I ask myself: why do I want to record this? Why is there no simple action to fix this right now? That one question, applied consistently, has gradually shifted how my team communicates. Less note-taking. More architecting. From people who document intentions to people who execute them.

The collaboration changes happening right now are enormous. Human-agent-human interactions bring challenges no one has playbooks for yet — and they make the old ones, like “how do we extract value from a meeting recording,” irrelevant.

That transformation deserves its own post. For today, one takeaway:

You have to finish meetings with ready-to-use results. Planned meetings. Launched changes. Not notes about what to do.

The shift we’re living through is not “use AI to do your work faster.” It’s “teach systems to do the work on your behalf.” That sounds like a small distinction. It’s not. It’s the difference between running harder and building something that runs without you.

We used to write code. We used to test it. We used to deploy it, monitor it, fix it, repeat. That was the job. Now the job is different — not in degree, but in kind. The people and companies who figure out how to teach programs to do this work, who find more efficient ways to drive value through their systems, win. Those who don’t lose the competition. And when systems lose, the people who depend on them lose with them.

So why isn’t everyone sprinting toward this? Because it triggers something primal.

The Fear Underneath

Our deep fear of becoming redundant shifts our focus from the productive path — teaching, architecting, designing systems of work — to the unproductive one: clinging to manual control. We don’t adopt AI poorly because we lack intelligence. We adopt it poorly because we’re terrified of what full adoption implies about our role.

If you’ve ever watched a brilliant individual contributor get promoted to manager, you’ve seen this movie before. The best ICs often make the worst new managers, and the reason is always the same: they can’t stop doing the work themselves. They micro-manage. They rewrite their reports’ code. They hover. Not because micro-management is effective — anyone with experience knows its scope of application is vanishingly small — but because letting go of the work feels like letting go of their identity. Their value was in *doing*. Now their value is in *enabling*. Yes, it’s a process change — but the identity impact is what makes it so hard.

This is exactly the struggle we’re seeing now, but at civilizational scale. Millions of knowledge workers built their professional identity around execution — writing, coding, analyzing, designing. AI doesn’t just offer to help with that execution. It offers to *replace* it. And our instinct, predictably, is to grab the wheel tighter.

The Squirrel in the Wheel

We even invented a term that reveals the dysfunction: **human-in-the-loop**. Think about what that phrase actually means. You are the squirrel in the wheel, and you’ve committed to running at whatever speed the wheel spins. As AI accelerates, you accelerate — or you fall. That’s not a collaboration model. That’s a treadmill with no off switch.

Human-in-the-loop sounds responsible. It sounds like oversight. But in practice, it means you’ve embedded yourself inside a system that will only get faster, and you’ve made yourself the bottleneck. Every output waits for your review. Every decision routes through your judgment. You feel essential — and you are, in the worst possible way. You’re essential the way a toll booth is essential on a highway: everything still flows, just slower, because of you.

The reframe I keep coming back to is this: **move from human-in-the-loop to human-at-the-boundary.**

Human at the Boundary

The difference is fundamental. A human in the loop operates inside the system — reviewing, approving, correcting, running alongside the machine at machine speed. A human at the boundary operates outside the system — defining what it should do, setting the constraints it must respect, architecting how value flows through it, and intervening only when the system encounters something beyond its boundaries.

The human at the boundary doesn’t review every pull request. They design the testing framework, the guardrails, the acceptance criteria — and then they let the system run. They don’t approve every marketing email. They define the voice, the rules, the audience parameters — and then they audit outcomes at the edges, where the interesting failures happen.

This is what it means to build systems of autonomous value delivery. Not “AI does everything unsupervised.” Not recklessness. But a fundamentally different relationship with work, where your job is to architect the system’s intelligence rather than substitute for it.

Those who build these systems — who design their work as autonomous pipelines with human judgment at the boundaries, not embedded in every step — are the cohort that will survive and succeed. Everyone else will eventually learn from them. But that learning will come with a collision with ground truth: the single certainty right now is uncertainty, and the people who build adaptive systems will navigate it better than the people white-knuckling their way through every task.

Subscribe now

Redundancy Is the Point

Here’s the part nobody wants to hear: redundancy is not the threat. Redundancy is the goal.

Every time you make yourself redundant in one area of work, you free yourself to operate at a higher level. The IC who becomes redundant as a coder becomes available as an architect. The manager who becomes redundant as a task-assigner becomes available as a strategist. This has always been how careers advance — you outgrow the work, hand it off, and move to the harder, more leveraged problem above it.

AI just compressed the timeline. What used to take years of gradual delegation now happens in months. The IC doesn’t slowly hand off coding to junior developers over a decade. They hand it to AI next quarter. That speed is disorienting. It feels like loss. But the opportunity on the other side is enormous — not despite the redundancy, but because of it.

As soon as you stop fighting redundancy and start embracing it, the opportunity space explodes. There is more work to do than ever before — it’s just different work. Higher-leverage work. The work of teaching, designing, architecting, and steering systems that deliver value at a scale no individual human ever could.

The belief system shift is simple to state and brutal to internalize: your value is no longer in what you do. It’s in what you enable. The sooner you make peace with that, the sooner you start building.

Wrong and naive idea of transformation

The frictionless way to transform one business process to another is by giving AI “superpowers” to every employee. It is exactly what we see around: “everyone uses AI,” “ask ChatGPT about this problem!,” “there is a new AI tool that solves your problem.” We empower employees with AI while expecting them to perform better — otherwise they will be “not good enough,” “not adaptive enough,” and eventually fired. Meanwhile, these are quite challenging times for every regular worker. Most “knowledge workers” (those who usually do knowledge in -> knowledge out kind of work) are scared about their jobs or at least feel uncertain. Those who cope with the emotions eventually get overwhelmed and exhausted by the permanent bombing of new tools and “AIs.” A massive pandemic of burnout is coming just because people try to do their best, but the maximum they can achieve is a 3x result compared to others — in exchange for overloaded context in their minds. 3x does not come for free. It gradually burns everyone.

The right way of transformation

We needed systems and processes to organize different people and design businesses to deliver value despite circumstances. Now those people have to move out of the value delivery chain and start looking from the outside of the value stream by designing it — actually doing proper piping instead of managing water inside the tube.

Take a software engineer as an example. The wrong transformation: give them GitHub Copilot and expect twice the output. What actually happens — they write more code, review more code, ship more bugs, and burn out faster. The intensity just went up. The right transformation: the engineer stops writing code manually altogether. Instead, every time a new task arrives, their job is to help AI understand the context, navigate the codebase, and produce better output than last time. They become the architect of AI’s understanding — not a faster AI tools orchestrator. The pipe gets smarter. The engineer gets leverage.

Subscribe now

Founder, AI, and other human relations

This same principle — designing the pipe instead of pushing water through it — applies way beyond engineering. It applies to everyone steering a company.

In earlier times, the speed of change was slower; light steering brought you to the right result. Now times are different. With great power comes great responsibility. If you harness AI properly, your speed will be significantly higher — and it comes with higher risk because wrong steering will hit hard (think leaked data only because AI generated your MVP and security was not one of your concerns).

Take a founder as an example. The wrong transformation: use AI to ship everything faster — landing pages, pitch decks, product MVPs, legal docs — all generated in a weekend. Feels like a superpower. What actually happens — you ship fast with zero guardrails. AI hallucinates a privacy policy that doesn’t cover your actual data flows. Your MVP stores user credentials in plain text because nobody reviewed the architecture. You move at 10x speed straight into a wall. The right transformation: the founder doesn’t just use AI — they surround themselves with the right people who know where AI cuts corners. A security-minded engineer who reviews what AI generates. An advisor who flags regulatory blind spots before they become lawsuits. The founder’s job is not to do everything with AI. It is to build the team and the structure that makes AI safe to use at speed. The harness matters more than the horsepower.

Having the right people who help you build a good harness is the key. Speed without structure is just a faster way to fail.

Subscribe now

Especially for subscribers <3 I also attach the version for printing

8 Essential Laws Of Systems (for Printing)

684KB ∙ PDF file

Download

Download

In professional jargon, this is often called technical debt. But how would you name it in everyday life? A loose electrical outlet that’s dangerous to plug a laptop charger into but seems to work for now; a broken lock on a door through which family or neighbours frequently enter and distract you just when you’ve achieved flow state; dim lighting from a lamp that gradually strains your eyes and accelerates fatigue—the list could go on. Is that already a good moment of time to fix something or not yet?

Subscribe now

To find an answer, let’s ask another question first. How does one assess the importance of a developer not having a laptop? It sounds quite critical; they cannot perform the function that the team, as a cohesive unit producing software applications, is supposed to include.

What about an uncomfortable chair? It doesn’t seem as obvious. But if a bad chair leads to a person’s irritability, worsens communication, makes the team less effective as a unified group, and slows down the delivery of results to the client, it becomes significant.

One might say, “Ignore that. The impact is negligible. Even if a developer loses 0.05% of productivity due to a bad chair or a faulty office lock, it’s nothing—they take longer to drink coffee.” To this, one could respond that, firstly, this figure can be multiplied by the number of developers, and secondly, by the average number of everyday problems. Thus, because no one fixes "not important problems” (even in personal life), everyone else indirectly suffers, resulting in lost productivity.

Here is just one of billions of stories.

Today, I fixed the lock in my home office. It was initially installed by someone else as a placeholder for another lock (presumably by previous occupants). We didn’t have any keys for it, and it didn’t function properly. I purchased a rim cylinder with keys (the component where you insert the key to turn the locking mechanism), a metal hacksaw, and a chisel (I needed to move the lock lower to have both parts on the wall and on the door aligned horizontally to make it functioning)—all just to be able to close the door when necessary (value by itself or an opportunity to make some other value, for example, keep important communications focused). I spent about 5-6 hours over several days (cost), but I was not only pleased with the result but also inspired (side value).

Perhaps there are tasks YOU have been meaning to tackle for a long time—issues lingering in your daily life. Consider what those tasks are and what value (and to whom) will be gained once you finally address them.

Subscribe now

So, OpenAI has released O1 preview and mini, and in short, I’m thrilled. The model "thinks" before responding and solves complex tasks significantly better than previous models.

Subscribe now

Last night, I decided to test it by writing a service in Go with its help, which collects statistical metrics from GitLab. The model succeeded. More precisely, it first built the project structure, filled in the files with content it suggested, and left placeholders where it couldn't write. Then, I iteratively asked it to handle each metric individually. No issues at all. Some work had to be done manually (like copying content between files), but it was very straightforward.

I specifically chose Go, a language I know little about, so I wouldn’t interfere with the model’s process using my own experience on how things should be written, focusing purely on "I can read the code in any language," while the model should write it itself.

How does it work? According to the documentation, OpenAI first trained an internal reasoning model using reinforcement learning (where the model succeeds or makes mistakes, receives feedback, and adjusts its weights). The internal model is designed to output reasoning tokens based on input tokens (essentially a preliminary response in the form of reasoning about the query, an embedded chain of thoughts). Then, the input plus reasoning generate output tokens. Tokens from previous reasoning aren’t involved in further communication to avoid overcomplicating things.

It’s already available for those with a subscription, and I highly recommend giving it a try. There are limits, but mini should be enough for writing code (limit of 50 messages), while preview has a limit of 30.

For general users: https://openai.com/index/introducing-openai-o1-preview/

For tech enthusiasts: https://platform.openai.com/docs/guides/reasoning

Today I celebrate the first decade of my career. On this path, I've been exploring more and more, diving deeper and deeper, getting wider and wider perspectives, and here are 10 of the most impactful insights I've got.

1. The team is the driver. A strong team can make everything you can imagine but a strong team is not just a set of strong individuals, it is also strong relationships and a healthy atmosphere of cooperation.

2. Sustainable development is a result of evolution. Over this decade I've seen many examples when people (including me) overthink a problem, trying to find a silver bullet via creating a complex solution expecting that a simple task will transform into a much more complex one but this does not happen. This statement is not only about coding but also about every area where you can apply an engineering approach (including development process improvement).

3. Success is a result of meeting expectations. The single definition of success that makes sense to me is meeting the expectations of those who are interested in the result. If you create a boat that should be perfect from a transferring perspective for those who want to cross the river, they won't care that you forgot a figurehead.

4. A consistent model of the world in your head is truth. If you have a consistent model in your mind that explains why you should do X but not Y and nobody can break it, you must trust yourself.

5. Inclusivity brings efficiency. Practically speaking, all people have good ideas that help to identify alternative POVs on the problem. But not everyone is bold enough to speak loudly. You might have a diverse team but if you do not help them to be included in discussions you lose all the benefits.

6. Feedback Cycles is a source of improvements. Do you want to improve something? Create a feedback cycle. Period. And don't forget to measure to verify the progress. Period Period.

7. Creative ideation requires freedom. If you apply too many constraints and limitations, if you create too tough processes, this might damage creativity because when people strictly follow rules it is harder to apply critical thinking and identify alternatives

8. Listen, not speak. Rapid reaction to something you hear often will bring wrong outcomes because to solve a problem you have to understand it, to understand it, especially, the root cause of it you have to listen. Listen a lot.

9. Startup needs speed, enterprise needs quality. Speed vs Quality is one of the most dramatic trade-offs I have ever seen. Those who spend too much on quality on early stages just don't survive because speed is not enough to achieve results and get first clients, those who ignore quality because of high pace start loosing their clients.

10. Purpose brings motivation. Not money, not impressive speeches, not authority but answer on the question "why" brings long-term motivation

11. You are able.

Subscribe now

As you might know, I’m from software engineering, so my hourly rate is relatively higher than many other jobs. A conjunction of that with the rule “pay if someone’s time is cheaper than yours” brings many issues and eventually brings unhappiness. Let me explain

After the first 20 issues and ~4.5 months of doing this weekly I see that to growth a list of subscribers it is still the requirement to actively promote the weekly on other platforms. At the same time it is a pretty strong commitment for volantaury activity. So I decided to not put it on schedule but rather publish on demand and use rather as a platform for long posts.

I also invite you to join DevTower telegram channel for more frequent updates and collaboration. See you there

Logical consequence “Do it by yourself if your time is cheaper” does not work

Plenty of different areas like legal, medicine, and accounting are nearly impossible to do by yourself, even if your time is cheaper. So, it requires a ton of extra education, so we have a steep learning curve. These exclusions highlight that the rule does not work perfectly well.

One-time job activities

Sometimes, deep extra expertise is not required, or there is a shallow learning curve, but the job has to be done only once. It is impossible to reuse the experience and accumulated knowledge. For example, if you have a good public profile, you could try to apply for UK’s Global Talent Visa. That will require highlighting the most critical aspects of your work relevant to this particular type of visa. This is a one-time job. You won’t apply for GTV after success again because it does not make sense. At the same time, building your submission properly will require 2-3+ months.

On the other hand, some services lead you by the hand through this submission, but the cost is 5 000 GBP (~6 000 USD). You might have a relatively smaller income, so self-submission of documents sounds fine. Or not?

Do not underestimate lost opportunities and knowledge because you were busy for long months deep-diving into processes that will never repeat.

Correlation between rest and hour rate

Usually, you get paid with an implicit contract that the other part of your time you should get recovery to produce the same result predictably.

Using your hourly rate to make decisions regarding personal activities assumes that you work all your non-sleeping time. But if you spread your hourly rate on all your time, you would also see that your recovery time is paid, not extra work time.

So, if there is no recovery, what will happen to your efficiency and results? How does your focus keep strong? How long will you keep the same hourly rate, at least?

Satisfaction impacts motivation

You likely prefer doing something you like rather than something you don’t. That is obvious. I believe that doing your favorite things gives you a much higher probability of success than otherwise. So why should you base your decisions on short-term money profit but not long-term success?

Conclusion

The hourly rate does not work as a criterion for personal decisions. Here are a few arguments that I rely on. Are there any doubts? I invite you to join our community and discuss or subscribe to the channel

The main idea behind CDN is that to make our system more reliable and performant for distributed loading, we introduce a distributed proxy & cache that hides the original application. In doing that, we add a DNS record that points to the IP addresses of CDN. Under the hood, a CDN proxy node requests to our origin server and caches results. If an origin server outage is in place, our static data might still work due to edge-caching. So the next question how to find the best CDN edge node?

Round-robin DNS

Thanks to round-robin DNS and redundancy, we distribute loading between IP adresses of CDN (not necessarily evenly), but those IP addresses are the same for every region. Does not seem distributed? That is because round-robin DNS does not care about geographical distance. Anycast comes to our aid here.

Subscribe now

Anycast

Anycast DNS is a traffic routing algorithm that allows to assign one IP address to many nodes. The approach has helpful advantages:

• high availability thanks to multiple nodes with redundancy sharing the same IP address

• lower latency because traffic is routed to the geographically nearest server

• scaling via adding of new nodes

As an alternative for finding the closest destination for a request, it is worth mentioning GeoDNS, but it is out of the scope of today's issue.

This is still unclear how does this guarantee we do not go across the world to find the closest node? IXP will help us to answer how to avoid The Trombone Effect (inefficient network path of queries).

IXP

Internet Exchange Point (IXP) is a physical location. Internet Service Providers and CDN providers share infrastructure there to establish the most efficient cross-network communication. IXP is presented as one or more physical buildings and depending on a particular demand it is helpful to connect networks either for free or some members might charge for their service. So, clients ISP has its edge node in the closest to a particular client IXP which is well-connected with other networks and especially with CDN providers. A map of IXP can be found right there.

Batumi meetup

One week ago, I had a chance to speak at IT Meetup Batumi about “Practical Evolution of a Distributed System”. Watch the recording on their channel (click on the picture)

1. Understanding your mission and long-term goals simplifies most of your choices

2. The younger your children, the more they need you

3. Give preference to those decisions that keep more opportunities and flexibility

4. Give preference to experience and opportunities instead of money

5. Raise yourself, not your children. They will learn from you

6. Responsibilities come before the reward

7. The well-known reward is limited

8. Understanding your and others' needs is the key to strong relationships

9. Compound interest works for your public activities (and other investments into yourself) in the same way as for regular investments

10. An emergency fund can save your nerves and mental health in critical moments

11. If high-risk investments are made, and there is a profit, take the size of the investments + 30% and play with the rest

12. Any risk (high/low) is acceptable but depends on % of capital under this risk

13. Make investments for the long term if this is not your day-to-day work (otherwise, name it trading and do not deceive yourself)

14. The more time you have, the more risk you can accept

15. Geopolitical risks exist

16. Work at places where you can impact the direction of movement in a certain amount at least relevant to your role

17. Even not accurate long-term planning makes more realistic short-term achievements

18. Think about Products, not Projects

19. Openness is the key to communication

20. Complex solutions must require motivation behind the complexity. Otherwise, prefer simple ones (even if they are not so beautiful)

21. All people have those who would like to read them

22. Before investments in the public market, try to find opportunities for investments in knowledge or skills to extend your space of opportunities

23. Build processes, hire, and delegate

24. As soon as you create an ad-hoc solution, start thinking about a systematic solution

25. IT does not exist without business behind

26. Soft skills are much harder to develop than hard skills

27. Make decisions on time but not too early, especially if they introduce limitations for you

28. Happiness can be felt only if you try unhappiness

29. Altercation is not as scary as ignoring needs

30. Life is not only about the past and future but also about the moment

A generic algorithm is one of the metaheuristics evolutionary algorithms that mainly simulate generic NP-complex problem-solving in the form of evolution and tries to find quasi-optimal solutions. Possible solutions are individuals. Their properties are abstracted as chromosomes and genes. All the surviving solutions in each generation constitute the population. Individuals are comparable via fitness function (objective function). On every iteration, the algorithm performs selection, mutation, and crossover. Amazing! Isn’t it?

The more tech progress moves forward, the more I come across options to leverage the idea of evolution. So, evolution moves from nature to digital in the context where our technologies evolve more quickly than we do. Can you imagine how I rejoiced when I realized that the same idea is applied in software architecture? Look at this evolutionaryarchitecture.com.

Evolutionary architecture has some perfect matching with reality and common sense as well as with my feeling that an iterative approach is the key. Neal Ford, Rebecca Parsons, and Patrick Kua wrote a book about that.

Your fitness function includes technical and business parameters. Automation is crucial here to control the level of fitness. Architecture incrementally moves forward alongside context updates.

I have not read the book yet, but it is already on my reading list.

Learn with me

Whenever I hear about NP-hardness, I google it because I cannot remember the meaning. Seems I found a good video that explains the concept.

Just renamed From Junior to CTO Weekly Thoughts to DevTower Weekly

fjtc.substack.com → devtower.substack.com

The Ultimate Software Engineering requires us to follow some rules, and leaving their maintenance without control will lead to increasing entropy. The more rules we define, the more difficult it is to support them manually. In this issue, we will summarize the configuration to maintain already known pieces of the ultimate software engineering and automation of that maintenance.

As before, my experience mainly relates to Gitlab, so some things might not work on other platforms.

Subscribe now

How Gitlab helps to configure

The Ultimate Commit, The Ultimate Contribution, and The Ultimate Code Review require you to form your commit messages according to Conventional Commits spec. Additionally, branches should be named after tickets, approvals must be given before merging, etc. So many rules. Let’s check what opportunities we have to manage these constraints.

It is highly recommended to read the mentioned posts before this one.

Push rules

It is important to say that even though push rules are amazing, they are available only on the Premium Gitlab subscription. I won’t sell GitLab here, but this advantage makes sense.

I’ve already described push rules usage before in The Ultimate Contribution post. So, read it there. You can also review the docs available here.

Approval Process

An approval process is available in all versions of GitLab, but for the free one, it is not flexible. Greater plans provide the opportunity to use code owners or manually configure approvers.

Another important setting available for approvals is Settings > Merge requests > Merge request approvals > Approval settings > [Unset] Remove all approvals. In The Ultimate Code Review I described why it is important to improve collaboration.

Additionally, you could disable emojis because the approval process is in place, but it is not necessary (Settings / General / Visibility, project features, permissions)

Repository Restrictions

Protected branches do not allow you to push changes directly. That is a great constraint that simplifies the process and does not allow unexpected changes to be delivered. The default branch is used as a default target for Merge Requests. Use the following sections to manage:

Settings / Respository / Branch defaults

Settings / Respository / Protected branches

Merge Requests

To get a properly working git history, it is important to configure merge requests. You can find settings at:

Settings / Merge Requests

Configure the merge method. We discussed that merge commit gives you more flexibility than fast-forward or semi-linear. There is a property in place.

Thanks to conventional commits spec, every commit matters, so you should disable squashing as a possible action via UI. If developers decide to squash some commits because of the wrong decomposition, they should do it manually.

Threads help to control how many open questions there are. You can have an agreement with your team that a developer resolves threads only if a reviewer explicitly asks them on the last comments. Otherwise, merge requests cannot be finished. Something similar we have for pipelines. If your pipeline doesn’t work, it likely won’t work on the default branch. So, protect yourself and do not allow merge unsuccessful pipelines.

Share

Configuration as a Code

Maintenance of all these configurations is pretty hard everywhere. Otherwise, it is not guaranteed that these rules are satisfied. In my practice, I saw how teams created their own job that ensures configuration according to the committed config, but instead of writing your custom job that works with GitLab API, you could try:

https://gitlabform.github.io/gitlabform/

I did not use this tool, but it looks similar to our in-house solution.

Conclusion

Simple rules should be satisfied to make the development process solid and reliable. Modern VCS hosting helps to control these rules, but that might require advanced plans. You can avoid manually maintaining these options by using configuration as a code solution.

The Ultimate Software Engineering Series

The Ultimate Software Engineering topic is not exhausted yet. I need to summarise some ideas to accurately deliver them as well as publish already described ones wider. So, the next issue won’t be dedicated to another topic inside the idea but rather some other considerations, practices, and practical advice. Subscribe so as not to miss

Learn with me (ex. The Video of The Week)

As before, my experience is mainly related to Git, so you can try to map some ideas to another VCS, but I didn’t have the intention to make it compatible.

Overview

There are no best or worst options, but there are more appropriate ones for your case.

First of all, let’s name what options are widely used:

• Git Flow

• Trunk-based Flow + Feature Flags

• GitHub Flow

• Gitlab Flow

• One Flow

You might find other strategies, but I want to show you a framework for choosing the best from the available options.

We will compare and find the right place for these strategies, but first, let’s formulate properties for atoms of these approaches: Commit, Branch, Tag.

Subscribe now

Atoms

Commit

An immutable state of the repository. The key properties of any commit:

• uniquely identifies a change and state of the repository since the change is applied

• immutable state

Branch

Dynamic pointer to a commit that isolates and tracks a set of changes. The key properties of any branch:

• dynamically identifies a set of changes

• simplifies work with an isolated set of changes

Tag

Static pointer to a commit that simplifies the detection of a particular state. The key properties of any tag:

• names a state

• manage static identification. For example, 1.0.0 statically identifies sources for a particular version of the component.

Before diving deep into strategies, let’s understand what properties will impact choosing the most appropriate one.

Properties that impact strategy choice

The branching strategy is a living organism that should adapt to your current context.

Team size

Adaptation means starting from the simplest option for a single developer (if that is your case) and, evolutionary, coming to the best option for a team.

Team skills

Your team's skill level impacts the choice because some strategies protect you more from beginner’s mistakes than others.

Code organization strategy

The more projects are stored inside the same repository, the more people collaborate and resolve conflicts - the more important it is to consider options that minimize conflict rate and improve continuous integration. At the same time, if you can avoid complexity because there is no collaboration, why not?

Desired frequency of delivery

Do you want to deliver every single feature available immediately and turn them on/off via feature flags, or you do mostly not care about granular feature tuning? This matters.

Subscribe now

Strategies

Common practice is that a feature branch is short-living, so since the feature is merged, you should remove a feature branch, but at the same time, if release branches exist, they should be removed only if your context allows that.

Git Flow

There is a chance that the quantity of articles about Git Flow is more than the quantity of atoms in the Universe. The strategy is pretty mature, but the disadvantages of it are well-discovered as well.

This approach is generally good, but there is a place for some redundancy and potential inconsistency.

• Every next merge will require a run of the CI Pipeline, which means that if you checked something manually, it is not guaranteed to have the same on production because, after your check, the artifact will be rebuilt again (on release → main merge) so something might go wrong.

• You have two long-living branches main & develop. That potentially might introduce inconsistency, for example, because you might forget to merge back your fixes from the release branch

Team size: works for any team size, but it is overkill for a team of one

Team skills: if you have fewer QA resources than needed, a low level of QA automation, and some developers have junior-level

Code Organization Strategy: a single main branch might sound uncomfortable for mono repositories with many teams

Desired frequency of delivery: at max once a few weeks

Trunk-based Flow + Feature Flags

The trunk is your main branch (whatever you name it), a place of Continuous Integration. Developers commit their changes as early as possible and create not feature branches but branches by abstractions, using feature flags to manage what is enabled in production. Merges should happen every day to guarantee a high level of continuous integration. Watch the video of the week at the end of the issue to get more details.

The approach is super simple but requires more effort and cost to implement. Feature flags require extra infrastructure, feature flags need to be maintained, feature flag cleanup process should be in place. At the same time, you get an opportunity to perform A/B testing for free.

Team size: works for any team size (the simplest option for one developer)

Team skills: a highly skilled team and a high level of QA automation. Developers have a strong understanding of how to manage abstractions with feature flags

Code Organization Strategy: You get the most profits from mono repositories because all the code is integrated as quickly as possible. But in general both ways are fine.

Desired frequency of delivery: as soon as abstraction is available in the main branch, it should be delivered. This is the fastest strategy of delivery.

GitHub Flow

This flow looks pretty similar to trunk-based approach. But the difference is that it doesn’t require daily merges.

Team size: works for any team size (the simplest option for one developer)

Team skills: mixed team with different levels, QA resources are enough to guarantee feature quality

Code Organization Strategy: you get the most profits from mono repositories because all the code is integrated as quickly as possible.

Desired frequency of delivery: as soon as a feature is available in the main branch, it is deployable.

GitLab Flow

GitLab transforms the idea of branches into subsequent pipelines of changes. You merge feature branches to the main branch (for GitLab Flow it is the main long-living development branch), but you can also introduce any other branches you need, like “production”, “pre-production”, etc. The problem of inconsistency here is presented as well but in another form because you have long living branches for main and production.

Team size: works for any team size (but overkill for a team of one)

Team skills: mixed team with different levels, QA resources are enough to guarantee feature quality

Code Organization Strategy: does not work if many projects stored in the same repository

Desired frequency of delivery: at max once a few weeks, not more often

One Flow

This approach has some variations, and I really recommend you spend some time on the original article. The main idea is that you still have only one long-living branch and use another one only if you want to simplify navigation for bug fixes. The approach is pretty flexible and can be constructed according to your requirements

Team size: works for any team size (moderate complexity for one developer)

Team skills: mixed team with different levels, QA resources are enough to guarantee feature quality

Code Organization Strategy: appropriate for both mono/micro repositories

Desired frequency of delivery: release complexity is not high, but I’d say that it is designed for at max once a few weeks

Conclusion

Let’s review a few cases:

The best for one developer and moderate QA automation: GitHub Flow

The best for skilled teams and high QA automation: Trunk-based Flow

The best for moderately skilled teams, low QA automation, and complex release acceptance process: GitLab Flow

The best for moderately skilled teams, low QA automation, and simple release acceptance process: One Flow

There is no “the best strategy” because the most appropriate depends on your case. GitFlow is generally outdated because there are other simpler options to achieve the same results. Since you have this knowledge, you can choose or even design the most appropriate one. In the next issue, we will talk about The Ultimate Repository Configuration and get a better understanding of how to manage all these guides.

The Video Of The Week

Resources

Trunk-based development

https://trunkbaseddevelopment.com/

GitHub Flow

https://githubflow.github.io/

GitLab Flow

https://about.gitlab.com/topics/version-control/what-is-gitlab-flow/

One Flow

https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow

From time to time, we put different aspects at the forefront. For some businesses, functional requirements are more critical than non-functional ones (they just need to get results asap, ignoring security/performance/maintenance and other stuff). For others, balance is important. For some of them approval process is overkill for others it is a crucial point of control. So let’s first clarify why we need The Ultimate Approval Process.

Motivation

Any process consists of steps that should be done to complete the entire process. The quality of every step impacts the final result. Software development is not an exclusion. Here we have the same rules that external quality control (by another actor) helps to improve the quality of results and reduce risks significantly. 4 eyes principle says that at least 2 people should review results. But why is this not a cargo cult? Why should we keep it as a part of The Ultimate Software Engineering? The essence of the answer is failure.

We live in a world where people make mistakes. It is impossible to avoid them fully, but we can minimize the risk in the places where it is important. I have already mentioned in The Ultimate Code Review you SHOULD NOT review and comment on stylistic mistakes, and it is more important to focus on such hard things to change later. For example, a badly designed API will keep client dependencies and limit your move forward, or wrong business logic can break data that might have a cost-sensitive impact on your business and waste your time on careful bug fixes in already working functionality. The cost of failure is the key motivation to set up your approval process. Applying the right people at the right time in your approval process makes your business less error-prone and more efficient. Let’s clarify who are “the right people”

Subscribe now

Who

First of all, let’s clarify the features of the right approver. He or she:

• must be in the context of the change or at least must have access to the requirements

• has expertise in the area of change or is going to get this expertise

The right choice makes any review meaningful for approvers and brings motivation. Approvers might be not only other engineers, tech-lead, or qa. The Ultimate Approval Process reflects your business needs so this might include lawyers, security engineers, and even clients in some cases.

What

An approval process is not only about pure code reviews. It validates all different aspects of functional and non-functional requirements. Try to answer the following questions to find the best defaults for your approval process:

• does this change require a state update and zero-downtime at the same time? Does this make sense to request reviews from well-experienced teammates?

• does this change have infrastructure changes and request review by infrastructure engineers?

• does this change require compliance review and validation with lawyers? (GDPR, CCPA, etc.)

• should we document changes in any form and validate them with an architect? (technical documentation, ADRs, etc.)

• should we revalidate that we have a budget for this change run because we know the implementation details?

• should performance engineers have a closer look at that change?

Some of these practices can require activities from time to time but not by default. It means that someone needs to decide when to request extra approval. If you want to answer YES everywhere, please remember that you have to balance between time/money and scope of work.

Subscribe now

When

Now we know the right people to approve, but it still might not be clear when they could control the results. Some practices like Shift Left move the review stage early, but they might be overkill in the beginning. So I recommend just starting reviewing incrementally do the left shift as much as possible. The bigger your team's scale and your product's complexity, the more important to move all such activities to the earliest possible time. For example, you should review and approve architecture before implementation, but you can approve the final implementation only when dedicated merge requests appear.

Where

This is one of the challenging questions because, due to the diversity of roles needed for the approval process, just a regular gitlab/github might not work. It depends on your company culture. Lawyers usually do not have gitlab accounts. So I’d say that if you are a small startup with a few components or bigger but do not have any approval process, start with approval process management embedded into your VCS hosting. Iteratively, retrospective-based, while your team/company is growing, consider what other approvals might be required and try to find common ground. For example, Jira has approval process management as well.

How

All good. People know what they should review and approve, where to do it, and when exactly, but how to organize the right people in the right place? The simpler system, the better, so formal approvals will be required not immediately from the beginning. When it is time to set approval rules, consider the following options:

• semi-automated approvers choice

  • define code owners

  • manually choose others who will positively impact change confidence

  • manual reassignment - assign a lead software engineer / qa engineer / … by default to guarantee either own review and informed choice

  • I’d not recommend assigning random people and explaining it in “Who” section above

  • you also might apply predefined approval rules, but they are less flexible than code owners

• the full intersection of expertise must cover the entire change. For example, if you had a review from QA and the security team but no other developers looked at the change - this breaks the process

• on the first iteration

  • send a message to a chat because notifications might not work as you expected for some people

  • grow a culture of proactive reviews

• every next iteration

  • should happen until approvals obtained

  • use the “reviewers” section to resend for the next iteration (at least GitLab supports that)

• every chosen reviewer

  • must approve

  • approval means that the reviewer thinks that even if you introduce another change, it doesn’t require another review (it depends on your business and the criticality of changes, so that might be replaced with the necessity of repeated review)

These rules might look like reviewers will be a bottleneck, so I recommend reading The Ultimate Code Review to understand how to focus code reviewers only on essential things.

Conclusion

The approval process setup might look boring, but it protects your business from human factors. This unnecessary moderation will slow down the process in your earliest days, so be careful and choose the implementation time. In the next issue, we will discuss The Ultimate Branching Model that will help developers collaborate efficiently and ship your product without issues. Subscribe to not miss

The Video Of The Week

To help you assess the complexity of zero-downtime updates, look the video (primarily the first part)

Share

Code Review might include manual practices as well as automated ones. So we will talk about both. But before we start, let’s understand our motivation to think about ultimacy.

I provide a few examples of tools in the post, motivation is just my awareness about them and this is not sponsored. Despite of this fact analyse how suitable they are for you before using.

Motivation

Despite the rationale behind many of our decisions in IT, we still have cargo cults for some practices. So to start here, I would suggest discussing the real quantifiable answer to “Why do we need code review at all?”.

A few factors bring motivation for code review:

• There are a few actors in code writing collaboration. Those who write some particular code, other ones who do not know anything about this code or at max partially know, those who wrote this code 6 months before, and others who will maintain this code.

• Developer tenure in a company might be long, but high likely ~2 years on average.

• Program comprehension takes about 50% of developer work.

Those three factors above tell us that we must collaborate and exchange knowledge to avoid expertise loss and team performance impact on time. The more people understand a particular code, the more sustainable it is.

Properties of The Ultimate Code Review

The Ultimate Code Review:

• is based on The Ultimate Commit

• is a part of The Ultimate Contribution

• keeps a history of communication to share knowledge

• guides a reviewer

• focuses on business-logic and automates other aspects of the review

• maintains a culture of collaboration and learning

Subscribe now

Benefits of The Ultimate Code Review

The Ultimate Code review is a part of the Ultimate Contribution. It means that atomic commits come to the code review stage. So, one of the important benefits is the opportunity to review commits individually. Imagine you separate your feature development to feature / refactoring / ci changes. Three different commits can be reviewed separately or together depending on the size of the changed code base. That drastically simplifies the review process, but at the same time, separated commits review is an optional thing.

Another important aspect is that The Ultimate Artifact is built for commits in merge requests (a.k.a. pull requests). It means that reviewers see the results of the Ultimate CI pipeline and have a wider picture of code quality metrics. Seeing not covered code lines, a reviewer can recommend changes or detect potential bugs easier. We should remember that the presence of code coverage guarantees bug detection.

Every comment of the Ultimate Code Review is an opportunity to learn and share knowledge. The fact that we store all discussion results will help developers in many years to understand the logical path of how a particular change was introduced.

The Ultimate Code Review reduces navigation complexity and repeated activities by guiding a reviewer. So the reviewer can focus on the most important 400 LOC at a time. According to research at the end of the article, this should drastically improve the defect density rate.

The right mood in code review makes relationships in the team better and creates a space for collaboration and peer support.

Some practices that help to improve code are already automated, some of them can be automated, but others are purely manual. Let’s sort through them.

Automated practices

I believe Software Engineering must be more creative than routine. So we must automate all the things that we can be automated.

Code Quality

One of the important parts of code review that requires a ton of attention is code quality checks. Modern static code analysis tools help to understand what problems exist, let’s mention a few of them:

• Language-specific linters will check guidelines compliance, for example, ktlint will help to check kotlin best practices, yamllint will validate the same way of indentation everywhere.

• Static analysis tools like SonarQube will help to detect code smells and bugs, and others like Snyk will automate static security checks against known security issues.

• Test coverage tools like JaCoCo in collaboration with Gitlab Code Coverage reports (via Cobertura adapters) embedded into your Merge Requests or comprehensive tools like Codecov will emphasize lines that might be important to review carefully (but not necessary)

• Local git hooks will format your code before committing to minimize remote code updates. Technically, it is not a part of the review process but helps to avoid misunderstanding why proper formatting was not applied

AI Reviewer

I have not applied modern AI reviewers in practice yet and do not consider them a comprehensive replacement for reviewers, but at the same time, they should be great reviewer assistants. The reason is pretty simple, if you can detect a problem without human attention, do that! But you have to keep in mind two risk factors:

• the most of AI review tools are cloud-based, which means that they upload your code somewhere, sometimes, models learn from your code to provide better results, so this is a potential attack vector and security breach.

• the accuracy of outcomes <100% so you might see “false positives”.

The key difference between AI analyzers and code structure analyzers is accuracy. The modern AI models cannot guarantee 100% accuracy of their outcomes but can find things that are impossible to find with old-school code structure analyzers.

I heard about CodiumAI and CodeGuru (by AWS), it is just an example, not a recommendation, and you definitely will find more.

Subscribe now

Review Tools

Can we send the code via email to review in the form of the archive? For sure! The key question is what is the effectiveness of this process. I saw a lot of tools that help you review your code, but the best foundation is IDE, with all the well-known tools you use for program comprehension. Fortunately, in the latest releases, Intellij IDEA team informed us about their native integration with gitlab which sounds like the first great step to simplify code review.

Manual practices

Strive to follow 4 eye principle

Even if you have all possible automation, ask someone to review your code. 4 eyes principle comes from risk management and means any important decision must be reviewed by someone else. There are possible automations to ensure that rule, for example, Gitlab allows to set a minimal set of reviewers.

The single reason to comment on style issues

If you comment on things like redundant blank lines, it means that you have wrongly configured / not configured the linter. Never spend your time on such things. It is extremely inefficient. But there is an exclusion - misconfiguration. Just ask the developer to update the linter config instead of fixing every occurrence of the issue

Choose the relevant reviewers

There are at least three options to chose relevant reviewers

• reviewers are identified as code owners

• you know that the change will implicitly impact someone

• you need someone with expertise

Code Owners can be automatically assigned according to a dedicated file in the repository (Gitlab example)

Depending on the developer's experience in the project, reviewers should be chosen by their lead engineer or by them. The less experience developer has, the more important to help to choose the right people to review.

Resolve reviewer comments only with their permission

Three actions that a reviewer does:

• leaves a comment

• resolves their comment

• approves

Sometimes comments might not be perfect, and misunderstandings might happen. So, I’d recommend using “Approval” as a sign that the reviewer is fine with the current state and any other changes, but if a developer understands that the MR (a.k.a. PR) should be reviewed again, they should request it explicitly. If a reviewer didn’t set an approval, you might consider that the reviewer wants to double-check some changes. If comments do not require a second review and are marked as optional, the developer can mark them as “resolved” themselves.

The Ultimate Approval Process is out of the scope of this post, so we discuss that topic in the next issue. Subscribe not to miss

Subscribe now

Avoid long discussions

Sometimes people might start debates in code review format because of different opinions. If there are no objective reasons to change code immediately, postpone the discussion, schedule a meeting, or use your tech syncups to discuss in a wider quorum.

Focus on things that are hard to change

Some changes are pretty cheap to introduce (like code style), and others are really hard (API with external users). If you understand that it is not too expensive to change the decision later, consider postponing the discussion if it takes too much time. Try to follow “Delay Design Decisions until they are absolutely necessary” practice. But keep in mind that some decisions are important to discuss early (for example, API design, db schema, etc.)

Include a checklist for reviewers for routine activities

Reviewers should not care about routine activities. Just use a checklist that defines what is important to check in the context of your project. Review documentation for libraries? Exposed interfaces? Configured authorization? All the typical things that can be met in any feature should be formulated as a checklist. This is the only thing, except for automation, that can help almost to guarantee team rules satisfaction.

Create a template for MR description (a.k.a. PR)

A checklist is one of the other typical things for code review, so it is useful to preconfigure a template for MR that helps fill in all the details and contains everything you prefer not to forget.

Annotate code in places where you want to get more focus

If a developer invites someone with specific expertise to review, they should not forget to annotate important pieces (for example, with comments) to align the focus of a reviewer.

Breakdown and order pieces of code review

The Ultimate Commit includes Conventional Commits that define atomic commits. This is one of the most powerful tools to make reviews simpler. Depending on code review size, a reviewer can review all commits at once or slip through refactorings, style changes, and other things that might be considered unimportant. When a reviewer has a relatively small commit to review, they might simplify it even more and follow the right order, for example, following the recommendations of a developer or common sense.

Focus on business

This is pretty obvious, but the reviewer has to focus on the business side of changes and help to validate that the requirements were satisfied. If not, neither API nor db schema does make sense. One of the options to validate requirements is to start with tests that assert behaviors. BDD might be valuable for such things.

Focus on things that are hard to change

When requirements are satisfied, you can focus on the things that are hardest to change, for example:

• Sync & Async APIs

• DB schema

• Integrations

Formulate a backlog for automation

Sometimes you detect something that might be checked automatically, but at the same time, implementation is too complex for the timings of a particular feature development. So, create a backlog for automation and solve it one by one, don’t waste your time commenting if the automation is presented in the backlog. Once the automation is implemented, all occurrences will be fixed.

A recommendation is not a dictation

Recommend changes, not dictate. Rules, not people, manage the best systems, so if you prefer to do something in a particular way and believe it is the best one, discuss it with the team outside the MR, and formulate rules. Otherwise, it will require explaining motivation in every new MR.

Explain motivation

Sometimes the motivation behind your proposal for changes might not be clear. A discipline of explanation makes your opinion argumented.

Propose options to solve

Suppose there are a few ways to introduce some changes. Formulate and propose them. Your comparison of variants will help a developer choose the most appropriate one or even propose a better one on top of your options. If you do not know how to improve and this requires investigation, inform the developer.

Discussions must be recorded in the form of a comment

Sometimes changes require verbal discussions. We usually do it in person or via tools like Zoom. Results of those discussions must be saved in text in the particular merge request to share results with others.

Conclusion

The described practices will help your team to reach the properties of The Ultimate Code Review. Subsequently, this will introduce the mood of a collaborative and support-focused vibe. The process will become simpler, and quality will be increased.

In the next issue, we will discuss The Ultimate Approval Process as a part of The Ultimate Contribution. Subscribe not to miss.

Other useful resources

Instead of the video of the week, I’d recommend looking at the following papers:

Expectations, Outcomes, and Challenges of Modern Code Review

Best Kept Secrets of Peer Code Review

Best practices for peer code review

Share

As before, most part of my experience is based on Gitlab, so I’ll show Gitlab-based examples, but you will probably easily find replacements for your specific scenario.

Let’s clarify what the Definitions of Done for The Ultimate Contribution are.

Definitions of Done

Let’s formulate rules on how The Ultimate Contribution should look like:

• every new commit should be The Ultimate Commit

• every contribution made with corporate’s email (if applicable)

• every new branch

  • should be named after the ticket code

  • should be merged only with The Ultimate Merge Request (a.k.a. Pull Request)

  • should follow The Ultimate Branching Model

• every new Merge Request

  • should follow The Ultimate Approval Process

  • should pass The Ultimate Code Review (we will discuss this in the next issue)

  • should pass The Ultimate Quality Review

  • should contain all relevant information

  • should preferably be refreshed via rebase before the merge

  • should be merged either with fast-forward or merge commit

  • as a part of a bigger feature should be merged in the right order

  • should trigger The Ultimate CI Pipeline

• squash is prohibited with exclusions

• every repo configuration should follow The Ultimate Repository Configuration

• every contribution policy should be documented

Subscribe now

Rules are defined. Let’s see how to ensure compliance with them.

Automation of DoD Compiance Check

every new commit should be The Ultimate Commit

In The Ultimate Commit post, I mentioned that to guarantee The Ultimate Commit structure (especially Conventional Commits), we can use githooks. Technically, it is not a strict constraint because githook could be either disabled or occasionally not enabled. So local git hooks help avoid push errors and prevent them early but do not guarantee restriction. If we want to perform strict checks we have to enable push rules (gitlab naming).

Currently, this functionality of Gitlab is located in Group → Repository Settings → Pre-defined push rules or Repository → Repository Settings → Push rules

Pattern:
^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test){1}(\([\w\-\.]+\))?(!)?: ([\w ])+([\s\S]*)

Some issues with Semantic Release require Gitlab 15.10+, but generally, this functionality helps guarantee the check.

Subscribe now

every contribution made with corporate’s email (if applicable)

The same story as for the commit format. Sometimes people might contribute from personal email with a random name config. Eventually, git history looks like a coven of daemons but not real people. To protect your team from this kind of mistake, you can just set a pattern to allow only corporate emails

every new branch should be named after the ticket

Fortunately, this part is also manageable in the same place, so if you use Jira, probably, your ticket codes look like XX-1234, it means that branches should follow the same format:

^[A-Z]+-[0-9]+$

every new branch should be merged only with The Ultimate Merge Request (a.k.a. Pull Request)

The Ultimate Merge Request is a regular MR that must be implemented according to the rules below but it is important that contribution never should come directly to the default branch. You could reasonably argue: “There should be exclusions when you urgently need to push a fix directly to the default branch!”. Making this constraint weaker only because once per 1-2 quarters you see a use case doesn’t make sense because, at the same time you make your pushes error-prone, and occasionally, people will push directly even if they don’t want. I’d say that the negative impact of this situation is much heavier than the profits you get making the constraint weaker.

every new Merge Request should follow The Ultimate Approval Process

First of all, approvals must be a part of your development process. Period.

Approvals management is located in Settings / General / Merge request approvals (Gitlab, but not available for some plans, you also might use emojis).

Code Owners is another important practice, so you must get approval from the most experienced people in a particular module/package/file. Except for Code Owners, approvals must be obtained from the most relevant people, so the team or a developer should choose if there is uncertainty.

The Ultimate Approval Process is out of the scope of this issue but will be covered soon.

every new Merge Request should pass The Ultimate Code Review

Code Review is a vital part of contribution quality assessment. If you compare code review with feature testing, you see that developers should help to find bugs that are harder to find from outside because other developers see how the code works. Like testing, it is easy to perform Code Review badly, focusing on the wrong things. I’m going to cover this topic in the issue the next week, so subscribe not to miss

Subscribe now

every new Merge Request should pass The Ultimate Quality Review

Quality review is another part of quality assessment. It is a comprehensive quality check for built artifacts rather than static sources. A quality review should include a run of automated e2e testing as well as manual feature testing, security check, etc.

every new Merge Request should contain all relevant information

Merge Request is an important point of documented collaboration between engineers. The better Merge Request is formulated, the better collaboration becomes. If this doesn’t become overcomplicated and relevant for your process, MR should contain a copy of ticket requirements not to confuse reviewers if something is changed in Jira but not in the MR yet. MR must describe the motivation for the change (context). MR description must guide a reviewer not to miss key things and contain a checklist for routine things like “permissions for new feature are configured”, “documentation is updated”, and also playing the role of reminder for the change author. Added Code Quality metrics (absolute values & diff) will help display what is going on with code quality and introduce the opportunity to configure code quality gateways.

Use templates to unify MR creation:

Sometimes commits in Merge Requests could be discussed on calls, but the results of discussions must be documented inside a commit message body or comments in the MR.

every new Merge Request should preferably be refreshed via rebase before the merge

Before we merge changes, we have to review and test them refreshed with the latest state from the default branch. There are two most popular options: rebase and back-merge. Let’s shortly compare

                        | Rebase  | Back-merge
-----------------------------------------------
Clear history           |   +     |     -
No history rewrite      |   -     |     +
Confl. resolution once  |   -     |     +

Do you think the best option is obvious? Not really. Weight might differ depending on your context.

Clear history?

Mostly about aesthetics, but if it doesn’t require extra effort and your team enjoys it, why not prefer this way? Commit graph review use case is also an argument, but honestly, ask yourself how often you look at graph? Were you really interested in graph connections or commit order after all? Can a simple search in the history (via IDE plugin) cover your use cases?

No history rewrite?

If we are talking about one developer per one feature branch - the weight here is zero, so this condition doesn’t impact because history rewrite does not introduce issues of concurrent work on the same branch. Nobody pushes changes directly to the master branch. Everyone primarily pushes changes to their feature branches.

Conflict resolution once?

If you rebase and more than one of your atomic commits might conflict with the target branch, that is the time to think about back-merge for this particular case.

Modern IDEs that drastically simplify the process must be used in any way.

What approach is the best?

You could prefer to rebase from an aesthetics and graph simplification point of view. If you see potential conflicts and back-merge will save you decades of minutes - good motivation to stop rebasing for this particular feature (branch) and start back-merging because aesthetics should not impact business.

every new Merge Request should be merged either with fast-forward merge or merge commit

This is pretty clear that fast-forward merges are the ultimate way of merging. No synthetic merge commits, and absolutely clear history (only one branch, finally). But! Fast-forward merges require you to rebase history, which is a strict constraint. So, that might be the main pain point if you apply The Ultimate Commit approach. At the same time, your team might be fine with this inconvenience. Choose either fast-forward forward merge or merge commit, get an agreement with your team, and follow only one approach, do not use two approaches simultaneously because that will confuse everyone and make your collaboration more unpredictable.

You could also apply merge commit with semi-linear history to guarantee that you merge only those changes that consider the default branch's latest state. That might work perfectly in tandem with the “approval reset on a new commit” option and approval by QA Engineer and fully automated regression testing, but you introduce more bureaucracy, and that definitely will slow down your delivery (of course, quality might keep better at the same time). Choose one depending on your particular business needs.

Do not forget to reconfigure your repositories

every new Merge Request as a part of a bigger feature should be merged in the right order

Sometimes features consist of more than one Merge Request, and the order might be important. For example, if you implement CD practices, you must merge the backend before the frontend that uses the backend. The backend should be delivered first.

The latest Gitlab version supports Merge Trains to automate the order of merge.

squash is prohibited with exclusions

In the Ultimate Contribution, squash is prohibited because your commits follow The Ultimate Commit practices, and the history is a source of extremely meaningful insides. After a while since a commit was introduced, you will review why this line looks like it is. The answer will be there.

Of course, there are no strict rules without exclusions. Dummy commits that were useful when you triggered CI especially to check that CI works fine must be squashed because they are meaningless (actually, they must be eliminated). This is relevant for feature branches that have only one responsible engineer but not for shared branches like your default one.

You also can hide “squash commits” option for MR in project settings.

every repo configuration should follow The Ultimate Repository Configuration

The more repos you have, the more complex to manage their settings manually. Especially if someone could change and forget to return them. The Ultimate Repository Configuration is out of the scope of this issue, but I’d like to emphasize that the configuration should be synced automatically and defined in a dedicated repository.

every contribution policy should be documented

I’m not an expert in open source, but more than once, I saw that popular open-source projects define their policies. I apply similar practices and maintain a few internal how-tos for my team that help people to align and onboard new teammates. It is important to simplify the onboarding process, create contribution guidelines considering agreed rules, and mention automation that helps inside the document. Team changes become seamless.

Conclusion

The Ultimate Contributions defines how to introduce new changes and not forget anything; how to form merge requests, branches, and commits.

One of the crucial parts of The Ultimate Contribution is code review. In the next issue, we will discuss The Ultimate Code Review and how to make the most of it.

Subscribe now

Share

The Video Of The Week

`

My experience is primarily based on Gitlab CI, so I might miss some new useful concepts in other CI tools as well as I might use unfamiliar wording for you, but I believe the key things are 100% transferable.

Overview

As described in The Ultimate Artifact post, I distinguish 3 types of artifacts: Library, Application, and Template (if you missed that post, I strongly recommend you to review it first). They all need different types of CI pipelines. Let’s declare the critical stages of continuous integration presented for almost every type:

• analyzing - check the code statically: run linters (eslint, ktlint, yamllint, etc.), run code analysis tools like sonar qube

• compiling - compile sources to their final form, for example, .java (source code in java) files to .class files (bytecode to run on JVM). Transpilation (source code→ source code) is a form of compilation, so ts → js is here as well. Documentation generation is here as well (.adoc → .pdf).

• testing - test compiled code (unit and integration tests, for example, with db)

• building - pack compiled code (.class → .jar, .js → .tar.gz), pack documentation, etc.

• releasing - mark sources as “released” with a tag if the pipeline is running on the default branch, also publishes built artifacts to their artifact storage (if there is something to publish).

The Ultimate CI Pipeline defines these stages are strongly sequential. This strictness gives you the following guarantees:

• you never compile poor quality sources accidentally because they are statically analyzed first

• you never test not analyzed sources, so you don’t see not existing errors related to wrongly formatted code (for example, indentations in python)

• all builds have acceptable quality (it means that if it is acceptable for development to skip tests for a particular case, the Ultimate CI Pipeline doesn’t block you)

• you never make accessible (publish) artifacts that were not built because of poor quality

• all your artifacts satisfy your requirements formulated with tests (if you do not manually ignore ones as an exclusion)

Subscribe now

Different types of artifacts have some diversities among their pipelines. Different stages might also have a variety of steps/jobs/tasks.

Pipeline Types

I would like to logically classify ci pipelines because even if, in general, they look similar, some details might differ. The classification is based on The Ultimate Artifact classification presented in the last issue.

Template Pipeline

This might be obvious, but templates usually do not have testing, building, publishing stages because sources provide all the needed value. So, practically, they only need the following:

• analyzing - check that a template is following common practices, style is correct, etc.

• releasing - mark a template as released (with tag)

In some cases, if it is necessary from a delivery perspective, the template might be packed, for example, to a tarball (in the building stage) and delivered to template storage (as an extended “releasing” stage). For such cases, it is better to consider the library pipeline.

Another example - Gitlab CI templates. They don’t need to be published somewhere; only tagging is needed to point to a predictable template state.

The notification about the newly released template version might be sent on releasing stage as an extra step.

Library Pipeline

The library pipeline fully leverages described pipeline stages. If many libraries are built in a mono repo, they all might be published. Let’s review the stages from the Library Pipeline perspective.

All the stages described above are relevant, but what is important: here, we have to consider where to publish the artifacts. It often makes sense to separate production and development storages. For example, Maven separates release repositories (static artifact versions for production) and snapshot repositories (dynamic & overridable versions for development).

Another important point is that sometimes, we cannot assign aliases to libraries (technical constraint). We expect the library to be republished with the release version even if the code is unchanged.

Application Pipeline

The application pipeline does also require all stages. We also should analyze sources, compile them. For interpreted language, this step is not necessary, but some sources might be used for code generation. For example, request handler stubs might be generated from API schemas. Testing might include integration testing because apps might have connections with other components, unlike most libraries.

Building depends on the option of how the app will launch. If this is an old-fashioned application server, the building might look like Library. If it is an Android mobile app, you build apk file. If the app will run on OS you build native binaries. But if we are talking about modern could native development, we build docker containers, and packaging is not just packing compiled sources to a form of archive, it is about layered image building, optimized by layer change frequency (though this is a matter of another post).

In the perfect world, I’d say that we should be able to create aliases for any kind of artifacts, but the most advanced approach here is to use docker tags. We mark sources on the release stage that triggers artifact building that will help access and identify the artifact. This Ultimate Artifact should be additionally tagged with the version that docker does seamlessly.

The most important difference here in respect to libraries is that a successfully finished CI process should do something to motivate CD to do its work. For example, the final CI step might be to update the app's current version in the repo responsible for the integration environment.

Considerations about Stages

Analyzing

Analysis helps you to identify source issues early. Because The Ultimate Commit motivates you to commit smaller logical pieces, it becomes hard to go too far from project conventions.

Security scanners are also a part of the analysis step, so you can block any pipeline with potential security issues if you desire.

The Ultimate Commits are already published at this stage, so it is relatively late to validate how they formed. I will describe how to establish The Ultimate Contribution in the next issue. Subscribe not to miss.

Subscribe now

Compiling

It only makes sense to separate compilation if your build system supports output caching. It means that if you can run compilation and, after that, separately run tests without recompilation, the separated compilation (as an individual step) works.

Testing

Should we be able to disable this stage for the sake of development speed? In the perfect world - we shouldn’t, but the reality is not perfect. The Ultimate Development Experience is another topic but briefly. Testing is crucial, the longer we don’t have testing, the more unpredictable quality we have. If we are completely sure in every commit we minimize our stress. Why do we want to disable tests? The single reason I can imagine to make deployment in development faster and avoid test fixes until the end of the feature development. We might exchange better quality for development/maintenance experience, but testing & security will be impacted. I think it is better to look at solutions that just improve development experience. For cloud-native apps, you can consider the following options: local deployments, scaffold, telepresence.

Building

Here we have a similar story as for the compiling stage. We must reuse the results of the previous stages to pack in the form of artifact(s). Building performance might usually be improved with different caching strategies. We pack what we already compiled, if we properly slice docker images we might reuse layers with your framework and library. We might pack only changed parts of compiled code (relevant for monorepos, but I’m not a big fan of ones for microservices)

Releasing

Depending on a pipeline type Releasing might include both publishing and tagging or only tagging. The same story for notification. For example, if you want to release gitlab ci template, you don’t need to publish anything but rather only tag sources.

Auto-tagging with a version is another interesting advantage of The Ultimate CI Pipeline. Because The Ultimate Commit is a foundation for the pipeline, we could compute the next artifact version from git history. For example, tools like Semantic Release. and Commitizen will help you to compute the next version and publish it to your VCS server in the form of a tag or updated file. Let me briefly explain how it works:

Conclusion

The Ultimate CI Pipeline defines how to transform The Ultimate Commit to The Ultimate Artifact, at the same time, they are prerequisites for The Ultimate CI Pipeline. The unified approach with some benefits helps you to not care about CI at all. It is important to answer on the question: How to guarantee compliance with conventions on The Ultimate Commits because otherwise auto-versioning won’t work?

In the next issue, we define how to make The Ultimate Contribution, which includes The Ultimate Branch, The Ultimate Merge Request and The Ultimate Commit Push that help ensure conventions compliance. Subscribe not to miss

Subscribe now

The Video of The Week

Subscribe now

The same as for The Ultimate Commit all my practice is based on Git as the most popular VCS, but if you do not use Git but understand how to map Git practices to your VCS, the issue might be valuable for you as well.

Classification of The Ultimate Artifacts

Unfortunately, we cannot define a single artifact type by saying, “Docker image is the single thing you need in any scenario,” so let’s classify artifacts first. That might be obvious, but we have to align here.

Library

The main motivation for this kind of artifact is to provide out-of-the-box logic for other artifacts.

The key properties:

• not executable - we cannot execute provided logic without calling code

• reusable in other artifacts - there should be a way to include provided logic to another artifact

Examples:

• .jar file

• npm package

• DLL file

Application

Application as a term might have different meanings in different contexts. In the context of this article, we are talking about a single executable that might run as a part of a distributed system or be self-sufficient.

The topic of Application typology (wider meaning) is out of the scope of this article. I will cover this in one of the next issues. Subscribe not to miss.

Subscribe now

The key properties:

• executable - can be directly executed

• might be reusable as a part of a bigger distributed system

• has a single entry point or convention how to run

Examples:

• a docker image

• .jar file

• .war file

• grep

Templates

Templates look similar to libraries, but the key difference is that users fully control them. Everyone can potentially override any piece of provided logic. Because of that property, they are distributed in the form of sources.

The key properties:

• not executable - you could create an application from a template and execute but it is impossible to execute a template directly

• overridable - any piece of a template can be modified

• a form of sources - usually, we can use source form only to communicate with a template user in the same language

• reusable in other artifacts - the same template helps to create different artifacts

• depending on implementation, it removes boilerplate or at least simplifies its creation

• the way of implementation defines how complex refreshing will be

Examples:

• website templates

• CI/CD templates

We classified artifacts, so let’s keep this in mind and proceed with the properties of the Ultimate Artifact. The first one is the Single Kind.

Properties of the Ultimate Artifact

The Single Kind, The Single Use Case

The Ultimate Artifact will never mix more than one kind (Library/Application/Template). Even if it looks useful because we have one executable to run a few different things, do not mix them. Even if we ignore the fact that this approach breaks the single responsibility principle, it introduces a big confusion for a user who has a particular use case to cover. The fact that a user gets a new entry point without awareness might introduce new problems and implicitly increases the attack surface.

Identifiable

The Ultimate Artifact is based on The Ultimate Commit. Any Ultimate Commit might produce zero or more artifacts for different reasons:

• an artifact was not provided because logic was not changed, for example, documentation was updated only

• provided separated kinds of artifacts from the same code base (API schema + server app; a few apps in monorepo)

So we can say that desired artifact’s name, in conjunction with commit’s hash should uniquely identify the artifact (being primary identification) among others provided from the same source repository. Commit’s hash only is not enough because of potential collisions globally as well as non-unified behavior with monorepos. To provide globally unique identification, the ultimate artifact has a group name (aka namespace) at the beginning to distinguish a company or a project in the company.

This is also important to mention that a branch name of sources is not a part of primary identification as well as tags because a few branches and tags might point to the same commit, so it doesn’t make sense to choose “the best pointer”.

Searchable

Primary identification is not an exclusive option to search for an artifact in the artifact registry. The Ultimate Artifact uses the branch name to point to the latest artifact built on the branch. For example, if a branch name equals a feature ticket code, that helps to find the most recent changes in the development of a particular feature. This also works for a few components under development simultaneously. For example, the statement “Components A, B and C are impacted in feature XX-1234” means that to see the latest changes before release you should just deploy A, B, C components with tag XX-1234. Some artifacts support multi-tags (docker), for others, only limited flexibility is available (maven).

One of the options to improve searchability is to tag commits that originated a particular artifact with environment type (production / staging) to speed up the hotfix procedure and find what exactly the state of code should be changed. This point will be covered in detail when we will discuss The Ultimate CD Process.

Searchability goes hand in hand with versioning because an artifact version is one of the options to search.

Versionizable

Identification is not versioning. Versioning helps to identify a particular artifact. All artifacts are identifiable but not all are versioned. For example, there are artifacts that are created during development, they require primary identification and searchability but not a real version.

Semver is the primary option to version The Ultimate Artifact. The importance of Semver for libraries is difficult to overestimate. Probably all users of libraries would like to know will library updates break something or only introduce new features/fixes.

Some types of artifacts (like maven) have versioning as a primary option to identify artifacts because tagging is not available. The limitation of this approach is that it is impossible to take an artifact for any commit on a feature branch, and versioning of merged changes is the single option, so you cannot choose not to version a commit.

Auto-versioning is available for The Ultimate Artifact, thanks to The Ultimate Commits. I will cover that topic in the next issue, where we will talk about The Ultimate CI Pipeline. Subscribe not to miss.

Subscribe now

Idempotent

The same sources should not provide a new artifact. If we built a commit on a default branch and added a new tag, we should not rebuild a new artifact for the new tag. Rather, we should add a new pointer to the already-known artifact. This is one of the important motivation points to use hash-based identification in general - to not generate new artifacts for the same commit.

This also means that if you use fast-forward (FF) merge and nobody introduced changes to the default branch before you tested an artifact, you will get exactly the same one in production.

Configurable

The Ultimate Artifact should be configurable according to artifact usage via command line attributes / environment variables / configuration files. The Ultimate Artifacts should be ready for the fact that configuration changes in time, so if the Ultimate Artifact’s startup time is too long for some reason, the artifact should be ready to refresh values in runtime (if acceptable). Command line attributes might be used to emphasize that the value can be updated only with a restart. At the same time, it doesn’t mean that env variables cannot have immutable values.

Environment type-independent

The Ultimate Artifact is not relying on the environment type (production / staging / etc.). If variables should have different values depending on an environment type, this part of the configuration should be moved outside of The Ultimate Artifact.

Deployment-independent

The Ultimate Artifact doesn’t contain information on how to deploy the artifact. Otherwise, deployment changes will impact the artifact’s version what does not have any sense and negatively impacts the separation of concerns.

Reusable (even partially)

The Ultimate Artifact defines the requirements to launch/use. If requirements are satisfied, the artifact can be reused. The fewer requirements that need to satisfy, the more reusable the artifact will be.

This is important to mention that some artifacts might support partial re-usage, for example, layers in docker assist you in sorting your code in the order of increasing change probability: framework → dependencies → custom code. That allows not to update and reuse the first two layers if only custom code were updated.

Integratable

The Ultimate Artifact must provide UI (incl. CLI) / API or both. It is possible either to integrate seamlessly into a business process as a tool or provide a clean, standardized API that follows one consistent approach and is user-centric. The topic of The Ultimate API is out of the scope here but probably can be covered later.

Subscribe now

Static

Versioned artifacts cannot be changed. But non-version tags can be moved. For example, if we tagged an artifact with a branch name as the latest one, a new commit to the same branch moves the tag, which should override the artifact.

Secure

Before The Ultimate Artifact can be used, we must perform at least a security check which confirms the artifact doesn’t have obvious leaks. Security scanners like Snyk are helpful for that purpose.

That is probably obvious but I have to mention that to guarantee that the Ultimate Artifact is the same as released, we have to sign it (an example for gradle).

Stack-agnostic

The artifact is an out-of-the-box solution that you need to configure and launch. The less external awareness about the stack you have, the less attack surface you make, and readiness for evolution is practiced. This is not a strict rule but rather a recommendation.

Here are my considerations regarding the Ultimate Artifact. In the next issue, we will discuss The Ultimate CI Pipeline, an automation process that will help you convert The Ultimate Commit to The Ultimate Artifact.

Video of The Week

Motivation

It must benefit us if we apply some effort to make something perfect. If we improve our approach to commit, we must utilize these results. Otherwise, it doesn’t make sense. What utility might we achieve?

Simplified Code Review

Program comprehension takes at least half of work time. Will developers be happier and more productive if code review might pass faster and smoother? We could add a bit more effort on every commit instead of huge efforts on code review. Eventually, the code reviewer doesn’t get hurt by this routine activity and keeps being motivated.

More Practical Code Review

Some well-known research papers say that after 200-400 LOC bug detection density is decreasing dramatically. At the same time, keeping features within such a hard limit is impossible. There should be something more atomic. Randomly reviewed files without a limited scope, mixed refactorings, and feature code might make your code review useless. A more structured approach makes the reviewer more attentive, which helps to find more problems early and saves the team’s time in total.

Change History Analysis

Code must be self-documented with clear variable names that explain what is inside and accurate method names that do not force you to look inside because it is obvious from the method name. That still makes sense to write comments for not obvious fixes that should not be occasionally reverted, for example, explicitly redefined transitive dependency version. But sometimes, we do not understand why some code was written in a particular way instead of an alternative one, we open history and see… nothing. The only “code review fix” or squashed “XX-1234 My amazing feature” ticket name in summary. History doesn’t really help developers to maintain existing code and this might be improved. The Ultimate Commit should give you more context of every particular change, simplify long-term work, help you in 6 months to return, and introduce some changes with minimal side-effects of missed memory pieces.

Inferred Versioning & Change Notes

The meaning of every change must impact, this is a consistent log of code mutations that should help you to automate versioning. Because a set of commits is a set of changes, we might leverage it. I don’t call it “Release Notes” but rather “Change Notes” because developers help themself when they write commit messages, they don’t think about an end user who might read notes inferred from commits, but at the same time, other developers might be interested in what happened.

We clarified what might be improved with “the Ultimate Commit” so let’s try to make obvious properties of one.

Subscribe now

Critical Properties of the Ultimate Commit

Small

Keeping complex structures in mind during code review and history analysis is challenging. Small limited changes are much simpler to understand. Just imagine that you review refactoring results and business code separately. Eventually, it is the same code but reviewing pieces separately, you can quickly look through refactorings or style changes and deeply review business ones that will impact your ability as a reviewer to focus on things that matter and keep high bug detection density.

Readable

This is obvious nowadays, but I must mention that the readability of commit messages directly impacts history analysis and program comprehension activities. If you save 1 minute instead of properly formulating a commit message today, this will chase you while the entire project lifetime until you leave the company.

Expressive

I often saw commits with the summary like “fix code review comments”, sometimes even repeated many times. These commits have meaningless summary because they do not explain why (even what) changes were introduced. You might object to me: but changes were introduced because the code reviewer added a comment. This is one of the most popular mistakes I’ve seen. Code Review is a tool for feedback but not a cause. The key task you solve on code review is highlighting different issues. Emphasize issues early to fix them before the root cause is merged. Expressive commit messages help you to formulate and check that you properly understand the motivation behind the comment. Is this just a style issue or a performance bug?

Normalized

There is no need to duplicate information. A summary of the Ultimate Commit should give you more information than you read from the inside code. For example, “add if statement” repeats the content but “handle a corner case” explains why these changes are needed.

Structured

There might be a few types of logical changes, so if we define the domain model, we could build automation for versioning, for example:

Completed

Committing does not correlate with time, there is no sense to commit every hour or by the end of the day. At the same time, if a change takes more time than your development session or consists of a few changes, you could definitely decompose it. For example, “introduce REST API with stubs under the hood”, “improve resilience with retries for network calls”.

Unified

This might be inefficient to scan some changes by eyes formulated in a passive voice, and others in an active one. Some have information about the initial branch/task, others do not, or this information is added differently.

There should be one standard for every particular commit.

Small, Readable, Expressive, Normalized, Structured, Completed, and Unified. WOW! A lot of properties to satisfy, some of them fully on developer’s shoulders, but others might be controlled independently.

Subscribe now

Practices

Conventional Commits

I hope that some of you who already aware of Conventional Commits are recognized that this specification covers the major part of the Ultimate Commit properties. For others, let me explain what it is.

According to the site:

The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with SemVer, by describing the features, fixes, and breaking changes made in commit messages.

If a team follows the convention, their commits get the following properties of the Ultimate Commit: small (atomic), structured, completed, and partially unified. Conventional Commits propose many standard types of commits, such as: feat, fix, chore, refactor, docs, style, test, perf (performance), ci, build, revert.

Active voice

Usually, there is an intention to write a commit summary in a passive voice, for example, “user API was introduced”. The problem with this approach is that passive voice is more complex to read because verbs might drastically change from their infinitive form; otherwise, the infinitive form in the present tense makes it simpler. Another motivation is that commit messages will be unified with Merge commits which start from “Merge …”

This practice helps to unify and improve the readability of commits.

Stop squashing

If you start with conventional commits, you must stop squashing of your commits. Now your history has been filled with information you might use, do not lose it.

Commits in history become readable and expressive. They are small, unified, and structured so you can easily understand why some changes were introduced.

A branch name is a ticket code and placed commit message’s footer

Identifying branches via ticket code makes everything simpler. First of all, you don’t need to think about the branch name at all. Secondly, you might add a branch name to the footer of a conventional commit, and if later you want to find all commits related to ticket XYZ-1234 you just search this code in the git history. If the branch were named after the ticket, you would save a lot of time.

It is obvious if you wanted to have exclusions from this rule, sometimes you can but keep in mind that it breaks your development traceability.

What is the best? Branch name addition is easy to automate but amend commits might be tricky.

“Why” instead of “What”

Your commit diff already explains what was changed. You could add more information with your commit message to explain “why”. Use commit history as a chat for communication with new developers who do not understand why a particular line was added so they will read it and not bother you repeatedly. I gave a few examples above.

Tools

Creation

IDE plugins and command line tools might help you to structurize your messages according to specifications.

Git Hooks might add a branch name to the end of every commit. There are several ways to implement git hooks, from manual git config update to build system plugin usage (example for gradle, example for frontend guys).

Validation

IDE plugins also might help you to validate your commit messages.

Git Hooks can help to test commit messages against specifications and other requirements.

Git Server Hooks help to protect from occasionally violated rules.

Version Generation

Semantic Release is a great tool to compute the next semantic version of your artifact and publish it to git server. Commitizen is also a popular one.

The most part of conventional commit-based tools is mentioned here.

Conclusion

The Ultimate Commits are not perfect because they require some effort, but eventually, you improve your code review, code comprehension, and, I’m not afraid to say, the culture of your development.

In one week, we will talk about “The Ultimate Artifact”, subscribe not to miss it!

The Video Of The Week

Subscribe now

Let me give you a few examples of software that we use nowadays to make online collaboration smoother.

• Code with me (by Jetbrains) helps people write code together before something is committed.

• Figma helps designers collaborate with other designers or even developers.

• Miro helps to draw flow charts and even more.

• Jira by Atlassian nowadays are trying to build a better collaboration experience inside Agile Poker.

• Google Docs is a standard way to create documents, including sheets and presentations.

Some of these guys are designed for collaboration. Others are trying to extend the experience. Cloud-based tooling is available, so what is wrong?

Another important aspect is the feeling of digital ownership that was available until we all worked locally, so work was not collaborative, but we managed ownership of our data. A document on my HDD, an exported file of my project from any tool installed on my computer, I was feeling ownership of these things.

Local-first software helps you keep both: ownership and opportunities for collaboration. There are a few principles behind local-first software:

• No spinners: your work at your fingertips (local data is primary, cloud data is secondary)

• Your work is not trapped on one device (data should be synced across all devices)

• The network is optional (use whenever you want)

• Seamless collaboration with your colleagues

• The Long Now (access the data for a long time in the future)

• Security and privacy by default (you own your data, a server holds only encrypted data)

• You retain ultimate ownership and control (backups on your shoulders)

Conclusion

As usual, there is no silver bullet. We should find the best tool for a particular task every time. Local-first software is not a typical way to implement something with its benefits and challenges. From my perspective, this approach is feasible in private areas (not business ones) because, eventually, a company owns data but not employees.