Mateus Costa

Fragments (pieces of I read) - 07.2026

Mon, 13 Jul 2026 22:00:00 +0000

Some pieces from The Developer Divide — What the Pragmatic Engineer’s 900-Developer Survey Actually Reveals About AI

The Pragmatic Engineer survey identified three developer archetypes in the age of Al: Builders, Shippers and Coasters. The central insight is not that one group is right and the others are wrong. It is that Al amplifies existing tendencies. It does not make everyone faster. It makes who you already are more intense.

Builders care about quality, architecture and craft. They do the large refactors, the migrations, the test coverage work.
Shippers care about output. They ship features fast and measure success by what reaches production.
Coasters are engineers who were average before Al and are now, with the right tools, producing more code than ever, but with proportionally more problems.

The critical finding: each group experiences Al completely differently. What feels like speed to a shipper feels like noise to a builder. What feels like a promotion to a coaster feels like a tax to everyone else.

Fragments (pieces of I read) - 04.2026

Fri, 17 Apr 2026 22:00:00 +0000

(Inspired by Martin Fowler)

Some pieces from Tech Radar(Volume 34 - April 2026)

Measuring collaboration quality with coding agents

Metrics such as first-pass acceptance rate, iteration cycles per task, post-merge rework, failed builds and review burden provide more meaningful signals than speed alone. Teams using Claude Code can use the /insights command to generate reports reflecting on successes and challenges from agent sessions. Our teams have also experimented with tracking first-pass acceptance of a customized /review command.

Agent instruction bloat

Context files such as AGENTS.md and CLAUDE.md tend to accumulate over time as teams add codebase overviews, architectural explanations, conventions and rules. While each addition is useful in isolation, this often leads to agent instruction bloat. Instructions become long and sometimes conflict with each other. Models tend to attend less to content buried in the middle of long contexts, so guidance deep in a long conversation history can be missed. As instructions grow, the likelihood increases that important rules are ignored.

AI-accelerated shadow IT

AI continues to lower the barriers for noncoders to build complex systems. While this enables experimentation and early validation of requirements, it also introduces the risk of AI-accelerated shadow IT. In addition to no-code workflow platforms integrating AI APIs (e.g., OpenAI or Anthropic), more agentic tools are becoming available to noncoders, such as Claude Cowork. When the spreadsheet that quietly runs the business evolves into customized agentic workflows that lack governance, it introduces significant security risks and a proliferation of competing solutions to similar problems. Distinguishing between disposable, one-off workflows and critical processes that require durable, production-ready implementation is key to balancing experimentation with control. Organizations should prioritize governance as part of their AI adoption strategy by facilitating experimentation within controlled environments.

Codebase cognitive debt

Codebase cognitive debt is the growing gap between a system’s implementation and a team’s shared understanding of how and why it works. As AI increases change velocity, especially with multiple contributors or Coding Agent Swarms, teams can lose track of design intent and hidden coupling. This, combined with rising technical debt, creates a reinforcing loop that makes systems progressively harder to reason about. Weaker system understanding also reduces developers’ ability to guide AI effectively, making it harder to anticipate edge cases and steer agents away from architectural pitfalls. Left unmanaged, teams reach a tipping point where small changes trigger unexpected failures, fixes introduce regressions and cleanup efforts increase risk instead of reducing it.

Feedback sensors for coding agents

To make coding agents more effective and reduce the load on human reviewers, teams need feedback loops that agents can directly access. These feedback sensors for coding agents act as a form of feedback backpressure, increasing trust in generated results. Developers have long relied on deterministic quality gates such as compilers, linters, structural tests and test suites; here, they’re wired into agentic workflows so that failures trigger timely self-correction. These checks reduce routine steering work for the human in the loop. Teams can implement them in different ways, such as introducing a reviewer agent responsible for running checks and triggering corrections, or by exposing the checks through a companion process that runs in parallel that agents can query efficiently. Coding agents also make it cheaper to build custom linters and structural tests, further strengthening these feedback loops. Whenever possible, these sensors should run during the coding session and report clean results before a commit is made, rather than relying on post-commit checks.

Complacency with AI-generated code

As AI coding assistants and agents gain traction, so does the body of data and research highlighting concerns about complacency with AI-generated code. While there’s ample evidence these tools can accelerate development — especially for prototyping and greenfield projects — studies show that code quality can decline over time. GitClear’s 2024 research found that duplicate code and code churn have risen more than expected, while refactoring activity in commit histories has dropped. Reflecting a similar trend, Microsoft research on knowledge workers shows that AI-driven confidence often comes at the expense of critical thinking — a pattern we’ve observed as complacency sets in with prolonged use of coding assistants. The rise of coding agents further amplifies these risks, since AI now generates larger change sets that are harder to review. As with any system, speeding up one part of the workflow increases pressure on the others. Our teams are finding that using AI effectively in production requires renewed focus on code quality. We recommend reinforcing established practices such as TDD and static analysis, and embedding them directly into coding workflows, for example through curated shared instructions for software teams.

Fragments (pieces of I read) - 03.2026

Mon, 09 Mar 2026 22:00:00 +0000

(Inspired by Martin Fowler)

Some pieces from Stop Sloppypasta I thought were interesting:

Too long, didn’t read:

slop·py·pas·ta n. Verbatim LLM output copy-pasted at someone, unread, unrefined, and unrequested. From slop (low-quality AI-generated content) + copypasta (text copied and pasted, often as a meme, without critical thought). It is considered rude because it asks the recipient to do work the sender did not bother to do themselves.

The Eager Beaver

A conversation participant wants to contribute to the topic at hand, so they ask a chatbot and share whatever comes back. The intention is good - they genuinely want to help - but the wall of generic AI text they contributed blocks the discussion already underway. Now other participants have to scroll past it to continue, or stop to read and validate it. It feels helpful to send. It creates work to receive.

The OrAIcle

Someone asks a specific question. Another person puts it into a chatbot and pastes the response as the answer.

The Ghostwriter

The sender shares AI output as their own work, with no indication a chatbot wrote it. Recipients have no reason to question it, and may act on information that is out of date, incomplete, or simply wrong. Using AI as a ghostwriter borrows the sender’s credibility. If the content turns out to be wrong, that credibility is what gets spent.

Fragments (pieces of I read) - 02.2026

Wed, 25 Feb 2026 22:00:00 +0000

(Inspired by Martin Fowler)

Some pieces from Harness engineering: leveraging Codex in an agent-first world I thought were interesting:

About AGENTS.md

We tried the “one big AGENTS.md” approach. It failed in predictable ways: Context is a scarce resource. A giant instruction file crowds out the task, the code, and the relevant docs—so the agent either misses key constraints or starts optimizing for the wrong ones. Too much guidance becomes non-guidance. When everything is “important,” nothing is. Agents end up pattern-matching locally instead of navigating intentionally. It rots instantly. A monolithic manual turns into a graveyard of stale rules. Agents can’t tell what’s still true, humans stop maintaining it, and the file quietly becomes an attractive nuisance. It’s hard to verify. A single blob doesn’t lend itself to mechanical checks (coverage, freshness, ownership, cross-links), so drift is inevitable. So instead of treating AGENTS.md as the encyclopedia, we treat it as the table of contents.

About asynchronous decisions in different channels

We learned that we needed to push more and more context into the repo over time. That Slack discussion that aligned the team on an architectural pattern? If it isn’t discoverable to the agent, it’s illegible in the same way it would be unknown to a new hire joining three months later.

About AI Guardrails

In practice, we enforce these rules with custom linters and structural tests, plus a small set of “taste invariants.” For example, we statically enforce structured logging, naming conventions for schemas and types, file size limits, and platform-specific reliability requirements with custom lints. Because the lints are custom, we write the error messages to inject remediation instructions into agent context.

In a human-first workflow, these rules might feel pedantic or constraining. With agents, they become multipliers: once encoded, they apply everywhere at once.

Human taste is fed back into the system continuously. Review comments, refactoring pull requests, and user-facing bugs are captured as documentation updates or encoded directly into tooling. When documentation falls short, we promote the rule into code.

The resulting code does not always match human stylistic preferences, and that’s okay. As long as the output is correct, maintainable, and legible to future agent runs, it meets the bar.

About feedback loops and merge gates

The repository operates with minimal blocking merge gates. Pull requests are short-lived. Test flakes are often addressed with follow-up runs rather than blocking progress indefinitely. In a system where agent throughput far exceeds human attention, corrections are cheap, and waiting is expensive. This would be irresponsible in a low-throughput environment. Here, it’s often the right tradeoff.

About humans in the loop

Humans always remain in the loop, but work at a different layer of abstraction than we used to. We prioritize work, translate user feedback into acceptance criteria, and validate outcomes. When the agent struggles, we treat it as a signal: identify what is missing—tools, guardrails, documentation—and feed it back into the repository, always by having Codex itself write the fix.

From @Test to #[test]: an essay about testing between Java and Rust

Sun, 13 Sep 2020 12:00:00 +0000

A disclaimer about used terms in the text: I’ve seen along the years that some definitions about testing have different meanings to developers. So everything here it’s based on my experience along the years: the projects that I was involved, the people that I worked with, blog posts and books that I read, etc.

Unit Testing in the projects that I’ve worked

It was working with Groovy that I have my first contact with Test Driven Development, and looking back today, I can say that people in my team was not pragmatic regarding the Test Pyramid. We aimed for a high percentage for test coverage in all the pyramid levels. I remember that our concept of integration tests was a very specific one.

Basically two objects (two Groovy classes) interacting to each other was considered an integration and, since we were using a more mockist approach we used a lot of stubs and mocks. At this point, you can imagine that we had a lot of redundant tests since is impossible to multiples objects to work without some kind of interaction/dependency between them. I think this project was extreme, but since then I carried this mindset with me always trying to test almost everything.

I was working with Java in my previous company as a consultant and it was a company that was pretty much by the book regarding practices like TDD and other buzzwords in our area as selling points to clients. I remembering convincing one developer to do a very complex unit test that was hard to set up to assert that a log statement was printed. This log statement was being used for our monitoring. And even that my arguments at the time were good, I think we could achieve better things to the business instead of spending almost 3 days to set up something complex to test a cross-functional requirement that could be easily manually tested in a few minutes.

Another case was to test some complex environment configuration to make sure it was there during the startup of the application. Again, my conclusion today is that the time spent trying to test something complex that could be just confirmed starting the application and would give the same confidence than with a complex test would be better to the business.

Of course, in both cases, we would miss a lot of benefits on the long term like regression and documentation, but even considering this I think it would not be worth doing with a test that required so long time to setup.

Most of the projects that I worked with Java had this similar mindset that I have described. My mindset had changed in my last project where I worked with a very experienced developer that was more pragmatic with some specific tests and was always reminding me about how important it is to solve the clients’ problems with quality but being pragmatic when testing some complex things or just forget for a moment about writing several unit tests and invest in at least a few integration tests. These things I didn’t learn in any book. You need to understand your context and have experience with different scenarios, projects, problems, deadlines and people. These details on everyday routine are going to give you enough knowledge to find a good decision that works with the scenario at hand.

Some differences between Testing in Rust and Java

These stories were told to give an idea of how much I struggled with testing in Rust when I started.

In Java, we need at least one dependency (like JUnit) to write unit tests and Rust has support for unit tests in the language by default. I think this is amazing since the possibility of doing tests is just there and the syntax is pretty much the same as writing production code. Of course, as your project grows, things get more complex and then you may need some external help from other crates.

Another big difference for me is where you write your unit tests. In Java, you usually have a file for your production code and another one for testing. In Rust, you write them together in the same file.

This was weird for me in the beginning, but it was the beginning! Nothing weird to feel weird if it’s something that you’re starting to do. Today it makes complete sense since is easier to look at the code and understand what is wrong if some test is falling or some scenario is missing. And of course, they are not compiled in the final binary since rust exclude everything with #[test] attribute.

Another thing is the number of scenarios that you need to write. It changes since you don’t have null like java. null in Java can leave you to think in edge cases later, since you can easily get to a situation like “I don’t want to think in error handling now, let’s just return null“. And then when running the production code you realize that there is this null case that needs to be treated. Rust forces you to think better in the edge cases where things can go wrong since you probably are going to work with types like Option and Result.

A practical example

I was implementing a new endpoint in our Rust project at Impero with a function that looked pretty much like this:

#[get("/process_query")]
process_query(query_executor: QueryExecutor) -> Result<Processed, InternalError> {
    let something = query_executor.call_to_database_that_return_something();
    let result = complex_private_method_logic_that_I_wanted_to_test(something);
    result
}

In Java I would choose between two testing approaches:

an integration test that would hit the endpoint and use an in-memory database
a unit test calling the public method and use a Mock returning something realistic from the database that I could work with afterwards.

Some people probably are going to have a strong opinion here about the way to test but I like what Kent Beck says in this podcast about TDD and testing or what kind of specific test you should write in a specific situation:

I think the level, the interface where you apply your tests, is a pragmatic decision based on the circumstances you’re in. I write tests at whatever scale I need them to be to help me make my next step of progress. Part of the skill of TDD is learning to move between scales, right. So I write a test that my customer says, “this scenario should result in a five”. So you write a test that says this scenario should result in a five, and then you’re down deep in the intestines of your program and you’re thinking, oh, I see, well this object when given a five and a seven should return the five. Well, that’s a good place to write a test because that’s another piece of the story that needs to be told. But, you know, is that Acceptance Test Driven Development, or is that BDD? I think that erecting rigid walls between the styles is actually a mistake, like the scales, as a programmer I want to understand all those scales. Tests help me understand, so I write tests at all those scales.

I tried to apply the number two (with Mock) with Rust but there is a problem. There aren’t still good mocking crates (you can check a good comparison table here) for structures. It’s being some time since I’ve faced this issue, but I remember the problem was related to being hard to create mocks for structs in external crates (and the struct to access the database was complex). I remember reading these two posts here and here, and this good discussion here:

Rust does not have a concept of object inheritance for structs so there is no way to mimic a struct type from the standard library or an external crate.

I hope as I get more fluency with the language and with new or more mature crates I can manage to do this without problems.

Another way to see the problem: maybe my design was broken. And yes this, in fact, can be one of the answers when I compare the way that a connection is passed in Java or how the Dependency Inversion Principle works, but this right now seems a question for the future. I’m still exploring the language in other aspects and even that I could say how this is made in other languages, I think I need to see more to have an elaborated opinion.

But back to the testing strategy: How did I test the code?. In fact, pairing with my colleague he comes up with a very simple solution:

it’s just one line of code that is making this database call and it’s been already isolated tested in another place, so let’s just test the isolated private function and move on.

That’s what we did, and it was hard for me to let it go at the time, but today I understand that was a good decision.

In Java, people would complete forbid this and start screaming about how we only test the public API’s/public methods. And I understand it, since is also the way that the language was designed and consequently how the libraries supporting the ecosystem also is going to be affected by that.

I only wanted to highlight that the testing approach here can be different because the two languages are different. Not just by design, but also in how each community can approach practices that are not linked by the language itself.

Another example: I see the Single Responsibility Principle with a different way in Rust than Java. In my experience, in Java, is more common for developers to create smaller classes with small methods while in Rust I see that is more forgivable to have more modules with way more lines that I have seen in Java classes. And this, in general, it’s ok I think. The community of either language will figure out later if a different approach needs to be taken.

Conclusion

When migrating from Java to Rust, I had to revisit a lot of concepts regarding testing. I learn to be way more pragmatic when going too far or spending too much time creating complex setups for tests that in the end would not bring too much value when compared to one specific integration test.

Learning another language also gives you the opportunity to learn new ways of doing things that you can apply in general. Today if I had to code in Java again, I would try to use way more the Optional type that I used in the past. After seeing how it works in Rust, is something that I think I could benefit way more in Java today than just using null.

Rust is still a young language. I’m sure the testing approach still has a long way to evolve and in a few years, this post probably is going to seem outdated.

My final message is that if you come from another language you probably know that you need to adapt to how the language works (or at least something in between). So you should do the same for the testing approach.

Rust releases for single and multiple targets with GitHub Actions

Sun, 17 May 2020 12:00:00 +0000

GitHub Actions has been growing at a fast pace and I’ve been using it in some pet projects. In a recent one, I tried the support for binary releases (CLI tools). Currently, the Infrastructure Rust team is also evaluating GitHub Actions so you expect support for different scenarios to be easy to setup.

I had trouble finding good and detailed material about how to setup releases for multiple targets with Rust for small projects, so I decided to document it myself hoping that it can help others.

GitHub Actions marketplace is full of different actions that combined can give you the same result. If you know another approach than the one here, please let me know.

1- Workflow for the releases

This workflow was set up for a small project, so we decided not having too many different steps when creating a new release:

Create new branch from master —> Open a PR —> Merge and release

Where Merge and release can be split into:

code checkout
creating the binary
incrementing version and pushing new tag/create a release
uploading generated binary/binaries to the new release

2- Releasing binaries for a single Linux target

Releasing binaries for a single target is simple. The folder structure for our project is the following (check it out here):

<project_folder>/.github/workflows
    ci.yml
    create_tag_and_release.yml

If you’re familiar with GitHub workflows, ci.yml is where we execute common Continuous Integration jobs like unit/integration tests. For most of my Rust projects, I usually run cargo check, cargo test, cargo fmt and cargo clippy. You can check what GitHub actions I use for running cargo commands and the entire file here.

Most of the times you want to release only when the other jobs are successful. In our case, it means that all jobs in ci.yml are passing. In our project we achieve this by using GitHub project’s settings:

go to your project’s main page
go to project Settings in the top menu
go to Branches in the left side menu
click on Add Rule
type a branch name pattern in Branch name pattern (in my case it was master)
tick the box Require status checks to pass before merging choosing the jobs that you want to make sure are green in order to make the branch “mergeable”
click on Create to confirm

And since the tutorial is about creating releases, I’m going to focus on explaining only the create_tag_and_release.yml file below:

name: Build, bump tag version and release

on:
  push:
    branches:
      - master

jobs:
  release:
    name: Build and Release
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Build project
        run: cargo build --release --locked
      - name: Bump version and push tag/create release point
        uses: anothrNick/github-tag-action@1.17.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          WITH_V: true
        id: bump_version
      - name: Upload binary to release
        uses: svenstaro/upload-release-action@v1-release
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: target/release/alemanes
          asset_name: alemanes-linux-amd64
          tag: ${{ steps.bump_version.outputs.new_tag }}
          overwrite: true

This file is going to be detailed in the next sections where I split the explanation for each block. I’m going to paste almost every block and explain it, but maybe you want to open the file in another tab in order to follow the explanation and compare to the entire file at the same time.

If I don’t mention something it’s because there’s nothing special about it for our context, but probably it’s mandatory in order to make everything work.

2.1 When to execute the release workflow

on:
  push:
    branches:
      - master

This workflow is going to be executed every time a commit is pushed on the master branch.

2.2 Release job and its steps

2.2.1 Job header

release:
    name: Build and Release
    runs-on: ubuntu-latest

Where name: Build and Release it’s the job’s name and runs-on: ubuntu-latest it’s the used virtual machine platform.

2.2.2 Checkout step

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

Check out our project code using actions/checkout@v2 in order to execute the next steps on it.

2.2.3 Build and create a binary step

- name: Build project
  run: cargo build --release --locked

Execute cargo build command that generates the project’s binary in release mode (with optimizations for the target platform).

2.2.4 Bump version and push tag/create release

- name: Bump version and push tag/create release point
  uses: anothrNick/github-tag-action@1.17.2
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    WITH_V: true
  id: bump_version

It bumps the version and pushes a tag, creating a release for it using anothrNick/github-tag-action@1.17.2 action.

id: bump_version is where we can send information from the current step to the next one. We need it in order to say for which tag/release we’re uploading the binary file.

note: anothrNick/github-tag-action@1.17.2 action only works in Linux VMs. If you try to generate a single release for macOs you get: ##[error]Container action is only supported on Linux. Fortunately, with extra steps, we can still make it work using the same idea for release for multiple targets that we’re going to set up later. I’ll add a proposed solution at the end of the tutorial.

2.2.5 Upload binary to release

- name: Upload binary to release
  uses: svenstaro/upload-release-action@v1-release
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: target/release/alemanes
    asset_name: alemanes-linux-amd64
    tag: ${{ steps.bump_version.outputs.new_tag }}
    overwrite: true

Upload its binaries using the action svenstaro/upload-release-action@v1-release:

file: target/release/alemanes is the binary you want upload to the release (it can be any kind of file: e.g. tar.gz)
asset_name: alemanes-linux-amd64: filename that is going to appear for target/release/alemanes file in releases page.
tag: ${{ steps.bump_version.outputs.new_tag }}: to get the tag info from the previous step saying which tag/release we’re updating the file.

3- Releasing binaries for multiple targets

The main difference on releasing binaries for multiple targets is that we need two workflows: one to create a tag and dispatch a repository event. And another one to be triggered on every tag-created event dispatched by the first one.

This is a different project, so we have a different folder structure (check it out here):

<project_folder>/.github/workflows
    ci.yml
    create_new_tag.yml
    release.yml

ci.yml is the same as we saw in here.

The difference in the structure here is that releasing binaries for multiple targets requires a separated job to create a tag that is the same one used by Linux, Windows and macOS platforms.

Since we’re going to execute jobs in different VMs for each platform, is not possible right now to share information about the newly created tag only using tag: ${{ steps.bump_version.outputs.new_tag }} between jobs running in different platforms.

3.1 Create new tag and dispatch repository event

The previous problem is solved by a separated job (create_new_tag.yml) that creates a new tag and dispatch a repository event. This is the content of create_new_tag.yml:

name: Bump version, create new tag and release point
on:
  push:
    branches:
      - master

jobs:
  bump_version:
    name: Bump version, create tag/release point
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Bump version and push tag/create release point
        id: bump_version
        uses: anothrNick/github-tag-action@1.17.2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          WITH_V: true
      - name: Repository dispatch tag created event
        uses: peter-evans/repository-dispatch@v1
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          event-type: tag-created
          client-payload: '{"new_version": "${{ steps.bump_version.outputs.new_tag }}"}'

This job has 3 steps:

checkout code
bump the version and push tag/create a release
dispatch a tag-created event

The first two steps was described previously here, so let’s focus on the third one:

- name: Repository dispatch tag created event
        uses: peter-evans/repository-dispatch@v1
        with:
          token: ${{ secrets.REPO_ACCESS_TOKEN }}
          event-type: tag-created
          client-payload: '{"new_version": "${{ steps.bump_version.outputs.new_tag }}"}'

uses: peter-evans/repository-dispatch@v1 is the action that dispatchs the repository event and client-payload: '{"new_version": "${{steps.bump_version.outputs.new_tag }}"}' is a evaluated json payload used by the action. In the end the payload could look like:

{
   "new_version": "v0.10.0"
}

We dispatch this event(event-type: tag-created) from create_new_tag.yml including the newly created tag in its payload and other jobs can be executed upon this event.

3.2 Upload binaries to the newly created tag

The second job, release.yml, is executed when this event of type tag-created is dispatched and uses its received payload to identify the tag to upload binaries from differents platform to the same release.

name: Build and upload binaries to release

on:
  repository_dispatch:
    types: [tag-created]

jobs:
  release:
    name: Build and Release
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            artifact_name: leis-municipais
            asset_name: leis-municipais-linux-amd64
          - os: macos-latest
            artifact_name: leis-municipais
            asset_name: leis-municipais-macos-amd64
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Build project
        run: cargo build --release --locked
      - name: Upload binary to release
        uses: svenstaro/upload-release-action@v1-release
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: target/release/${{ matrix.artifact_name }}
          asset_name: ${{ matrix.asset_name }}
          tag: ${{ github.event.client_payload.new_version }}

3.3 When to execute the release workflow

on:
  repository_dispatch:
    types: [tag-created]

This workflow is going to be executed every time there is a repository_dispatch of type tag-created(in our case dispatched by create_new_tag.yml)

3.4 Different environments to run the Release job

name: Build and Release
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        include:
          - os: ubuntu-latest
            artifact_name: leis-municipais
            asset_name: leis-municipais-linux-amd64
          - os: macos-latest
            artifact_name: leis-municipais
            asset_name: leis-municipais-macos-amd64

strategy and matrix means that you have more than one variation of environment to run your job in. Is like an array where each block inside include specifies one configuration. In our example is for ubuntu-latest and macos-latest. arfifact_name and asset_name are also necessary for the next steps(artifact_name maybe could be omitted since they have the same value).

3.5 Release job and its steps

3.5.1 Checkout and build

- name: Checkout code
  uses: actions/checkout@v2
- name: Build project
  run: cargo build --release --locked

Here is the same as we saw in here. The difference is that all steps run for each different platform.

3.5.2 Upload binary to release

- name: Upload binary to release
  uses: svenstaro/upload-release-action@v1-release
  with:
    repo_token: ${{ secrets.GITHUB_TOKEN }}
    file: target/release/${{ matrix.artifact_name }}
    asset_name: ${{ matrix.asset_name }}
    tag: ${{ github.event.client_payload.new_version }}

Here we also use svenstaro/upload-release-action@v1-release action to upload the generated binaries to the created tag/release. The difference is that we use matrix context properties to differentiate between each platform:

file: target/release/${{ matrix.artifact_name }} is the generated binary that is going to be uploaded to the release
asset_name: ${{ matrix.asset_name }}: is the binary’s name that appears in the release page. Since we have two different platforms, we want to differentiate them for the users.
tag: ${{ github.event.client_payload.new_version }}: is how we access the information received from the dispatched repository event. What matters here is the new_version property that contains the desired tag version to upload our binary files.

In the end, you should have something as we have in our releases page. After downloading one of the binaries, you probably need to run chmod +x binary_file in order to execute it.

4- Conclusion

The final set up of the workflow seems simple now, but it took some time to check how tags, versioning and releases work in GitHub. After that finding the actions that you need and at the same time associating the events that you need to run each workflow. Also stumbling in some workflow “limitations” like how to pass data between different jobs and understanding how you can achieve the same result using a different approach.

5- Extras

5.1 Pull request events

During the setup I also had tried with pull_request event:

pull_request:
    branches:
      - master

And I learnt that means that this is going to make the workflow to be executed NOT just when the PR it’s merged into master but even when a pull request is created. I didn’t want that, so I removed.

5.2 Solving the releasing binaries for a single target for Windows/macOS platforms

As mentioned in one of the previous sections anothrNick/github-tag-action@1.17.2 action only works in Linux VMs. Using the same approach that we used for multiple target releases, we could solve the problem for a single Windows release, per example, with something like (beware I didn’t test this workflow):

name: Build, bump tag version and release

on:
  repository_dispatch:
    types: [tag-created]

jobs:
  release:
    name: Build and Release
    runs-on: windows-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Build project
        run: cargo build --release --locked
      - name: Upload binary to release
        uses: svenstaro/upload-release-action@v1-release
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: target/release/alemanes
          asset_name: alemanes-linux-amd64
          tag: ${{ github.event.client_payload.new_version }}
          overwrite: true

Notes from Accelerate: Building and Scaling High Performing Technology Organizations

Wed, 01 May 2019 11:00:00 +0000

1. Some thoughts

It’s good to work in projects that use the latest practices applied by the industry, but sometimes that is not the case and you have to sell this fish to your boss in order to change organization. Sometimes just changing processes for the sake of trying to make the company is not enough, so have numbers and a whole book to prove their point with numbers is something that makes you even more confident to purpose something at your workspace.

2. What they found

velocity is designed to be used as a capacity planning tool (how long it will take to finish the tasks);
the measure should focus on outcomes, not output
we should measure: delivery lead time, deployment frequency, time to restore service and change fail rate.
- delivery part of the lead time: the time it takes for work to be implemented, tested, and delivered.
- product delivery lead time: the time it takes to go from code committed to code successfully running in production.
- deployment frequency: a software deployment to production or to an app store.
- how quickly can a service be restored?
- what percentage of changes to production fail
software delivery performance impacts organizational performance and noncommercial performance.
the fact that software delivery performance matters provides a strong argument against outsourcing the development of software that is strategic to your business.

3. Measuring Culture

basic assumptions are formed over time as members of a group or organizations make sense of relationships, events, and activities. And are things that we may find difficult to articulate.
values also influence group interactions and activities by establishing social norms, which shape the actions of the group members and provide contextual rules.
pathological organizations are characterized by large amounts of fear and threat.
bureaucratic organizations protect departments. Those in the department want to maintain their “turf”, insist on their rules, and generally do things by the book - their book.
generative organizations focus on the mission. How do we accomplish our goal? Everything is subordinated to good performance, to doing what we are supposed to do.

Three characteristics of good information:

it provides answers to the questions that the receiver needs to be answered
it’s timely
it is presented in such a way that it can be effectively used by the receiver

A good culture requires trust and cooperation, so it reflects the level of collaboration and trust inside the organization. You need to have good information to make decisions and these decisions can be easily reverted with the team is open and transparent rather than closed and hierarchical.

Google found that “who is on a team matter less than how the team members interact, structure their work, and view their contributions”. It comes down to team dynamics.

In complex adaptive systems, accidents are almost never the fault of a single person. Rather, accidents typically emerge from a complex interplay of contributing factors.

To change the culture: start by changing how people behave, what they do.

4. Technical Practices

Many Agile adoptions have treated technical practices as secondary as compared to the management and team practices. The research shows that technical practices play a vital role in achieving these outcomes. The research also found that Continuous Delivery has an impact on software delivery performance, organizational culture, and other outcome measures, such as team burnout and deployment pain.

Continuous Delivery:

Continuous Delivery is a set of capabilities that enable us to get changes of all kinds into production safely, quickly and sustainably:

detect any issues quickly
cost of pushing individual changes is very low
should be possible to provide our environments from information stored in version control
when implemented correctly, the process of releasing new versions to users should be a routine activity that can be performed on demand at any time.
reduce deployment pain and team burnout because it makes not to be a big-bang event every time that needs to be done and can be done during working hours
teams that can choose their own tools based on what is best for the users of those tools

They found that teams that did well at continuous delivery achieved the following outcomes:

strong identification with the organization your work for
a higher level of software delivery performance
lower change fail rates
a generative, performance-oriented culture This means that investments in technology are also investments in people

4.1 The impacts of Continuous Delivery on Quality

in the quality and performance of applications
the percentage of time spent on rework or unplanned work
the percentage of time spent working on defects identified by the end users (it represents the quality)

Unplanned work: “paying attention to the low fuel warning light on an automobile versus running out of gas on the highway”. In the first case, the organization can fix the problem in a planned manner, without much urgency or disruption to other scheduled work. In the second case, they must fix the problem in a highly urgent manner, often requiring all hands on deck – for example, have six engineers drop everything and run down the highway with full gas cans to refuel a stranded truck.

Test data management: successful teams had adequate test data to run their fully automated test suites and could acquire test data for running automated tests on demand.

Trunk Based Development: it was correlated more with high delivery performance. Teams had fewer than three active branches. Teams working with short-lived branches perform better than the ones with longer-lived branches.

5. Architecture

Employing the latest whizzy microservices architecture deployed on containers is no guarantee of higher performance if you ignore these characteristics.

High performers:

we can do most of our testing without requiring an integrated environment
we can and do deploy or release our application independently of other applications/services it depends on

The biggest contributors to continuous delivery:

make large-scale changes without the permission of somebody outside the team
make large-scale changes without other teams having to change something
complete their work without telling other people from external teams
deploy and release the product without depending on others
testing on demand
perform deployment during normal business hours In other words: architecture and teams are loosely coupled.

When teams can decide which tools they use, it contributes to software delivery performance and, in turn, to organizational performance. When the tools provided actually make life easier for the engineers who use them, they will adopt them of their own free will. This is a much better approach than forcing them to use tools that have been chosen for the convenience of other stakeholders.

6. Integrating infosec into the delivery lifecycle

Build security from scratch, when is the best moment to do this kind of preparation. Building security improves delivery performance because you spent less time remediating security issues.

7. Management practices for software

limit work in progress
visual displays with productivity metrics and aligning them with operational goals
use data from the application to make business decisions

high performers: peer review (with the team) instead of bureaucratic process with external entities.

8. Product Development

user research from the very beginning of the product lifecycle.
use of MVPs
customer feedback
work (features) in small batches
update specifications without requiring the approval of people outside the team

9. Making Work Sustainable

Deployment pain: the fear and anxiety that engineers can feel when deploying something in production. They find that where code deployments are most painful, you’ll find the poorest software delivery performance, organizational performance, and culture. Deployments need to easily happen during normal business hours. Build intelligence into the application and the platform so that the deployment process can be as simple as possible.

Burnout:

“learning from failure” kind of environment
communicating a strong sense of purpose
investing in employee development
asking employees what is preventing them from achieving their objectives
giving employees time, space, and resources to experiment and learn

Common problems that can lead to burnout:

job demands exceed human limits
lack of control: inability to influence decisions that affect your job
insufficient rewards: financial, institutional, or social rewards
breakdown of community: unsupportive workplace environment
absence of fairness: lack of fairness in decision-making processes

How to reduce or fight burnout:

strong feelings of burnout are found in organizations with a pathological, power-oriented culture. Create a blame-free environment, striving to learn from failures, and communicating a shared sense of purpose.
deployment pain
the effectiveness of leaders
organizational investments in DevOps
organizational performance. When organizational values and individual values aren’t aligned, you are more likely to see burnout in employees.

10. Employee satisfaction, identity, and engagement

They found that employees in high-performing teams were 2.2 times more likely to recommend their organization to a friend: highly engaged workers are associated with the high performers’ companies.

When leaders invest in their best work, employees identify more strongly with the organization and are willing to go the extra mile to help it be successful. In return, organizations get higher levels of performance and productivity, which lead to better outcomes for the business.

Continuous Delivery  
                    --> Job Satisfaction --> Organisational Performance
Lean Practices

11. Transformational Leadership

Good leaders affect a team’s ability to deliver code, architect good systems, and apply Lean principles to how the team manages its work and develops products:

establishing and supporting generative and high-trust cultural norms
creating technologies that enable developer productivity, reducing code deployment lead times and supporting more reliable infrastructures
supporting team experimentation and innovation, and creating and implementing better products faster
working across organizational silos to achieve strategic alignment

Leaders are those who set the tone of the organization and reinforce the desired cultural norms.

Five characteristics of a transformational leader are

vision: understands where the organisation is going and where it should be
inspirational communication
intellectual stimulation: challenges followers to think about problems in new ways
supportive leadership: demonstrates care and consideration of followers personal needs and feelings
personal recognition: praises and acknowledges the achievement of goals and improvements in work quality; personally compliments others when they do outstanding work.

11.1 Other things to create a good environment

establish a dedicated training budget and make sure people know about it
encourage staff to attend technical conferences at least once a year and summarize what they learned for the team
set-up internal hack days
set-up days to work on technical debt
set-up space to share knowledge
give time to experiment with new technologies
let the team choose their tools
make monitoring a priority: proactive monitoring was strongly related to performance and job satisfaction.

Notes from Growing Object-oriented Software Guided by Tests

Thu, 21 Feb 2019 11:00:00 +0000

1. Intro

mock objects are substitute implementations for testing how an object interacts with its neighbors.
testing is no long just about keeping defects from the users; instead, it’s about helping the team to understand the features that the users need and to deliver those features reliably and predictably.
“in our experience, dramatically improves the quality of the systems we build, in particular their reliability and their flexibility in response to new requirements”.
new applications can force developers into unfamiliar corners.
they all know there will be changes, they just don’t know what changes. They need a process that will help them cop with uncertainty as their experience grows, to anticipate unanticipated changes.
iterative development progressively refines the implementation of features in response to feedback until they are good enough.
we need constant testing to catch regression errors, so we can add new features without breaking existing ones.
TDD turns testing into a design activity. We use the tests to clarify our ideas about what we want the code to do. It makes code accessible for testing often drives it towards being cleaner and more modular.
the cycle of TDD: write a test; write some code to get it working; refactor the code to be as simple an implementation of the tested features as possible. Repeat.
we use TDD to give us feedback on the quality of the implementation (“Does it work?”) and design (“Is it well structured?”).
writing tests:
- makes us clarify the acceptance criteria for the next piece of work. We have to ask ourselves how we can tell when we’re done.
- encourages us to write loosely coupled components, so they can easily be tested in isolation and, at higher levels, combined together (design)
- adds an executable description of what the code does
- adds to a complete regression suite (implementation)
running tests:
- detects errors while the context is fresh in our mind (implementation);
- let us know when we’ve done enough, discouraging “gold plating” and unnecessary features (design)
never write new functionality without a failing test.
they use acceptance tests (that exercises the system end-to-end in a environment that tries to reflect the production environment), but personally I would no write a new acceptance test for each new feature. I prefer writing this kind of test for journeys and invest in other kind of tests (like integration and contract tests).
acceptance tests: does the whole system work? It helps to speak with the domain experts (or Product Owners) and to make sure that existing features haven’t broken.
integration: does our code work against code we can’t change?
unit: Do our objects do the right thing/Are they convenient to work with?
external quality and internal quality: external quality is how well the sytem meets the needs of its customers and users (is it functional, reliable, available, responsive, etc.). And internal quality is how well it meets the needs of its developers and administrators (is it easy to understand, easy to change, etc).
end to end tests tells about the external quality and how the team understand the domain.
a class to be easy to unit-test must have explicit dependencies that can easily be substituted and clear responsibilities that can easily be invoked and verified. Consequently loosely coupled and highly cohesive.
we’re tempted not to write tests when our code makes it difficult, but we try to resist. We use such difficulties as an opportunity to investigate why the test is hard to write and refactor the code to improve its structure. We call this “listening to the tests”.
elements are coupled if a change in one forces a change in the other.
an element’s cohesion is a measure of whether its responsibilities form a meaningful unit. For example, a class that parses both dates and URLs is not coherent, because they’re unrelated concepts. Think of a machine that washes both clothes and dishes - it’s unlikely to do both well.

2. Test-Driven Development with Objects

object-oriented design focuses more on the communication between objects than on the objects themselves.
an object communicates by messages: it receives messages from other objects and reacts by sending messages to other objects as well, as perhaps, returning a value or exception to the original sender. An object has a method of handling every type of message that it understands and, in most cases, encapsulates some internal state that it uses to coordinate its communication with other objects.
this lets us change the behavior of the system by changing the composition of its objects-add and removing instances, plugging different combinations together-rather than writing procedural code. The code we write to manage this composition is a declarative definition of the how the web of objects will behave. It’s easier to change the sytem’s behavior because we can focus on what we want it do, not how.
tell, don’t ask: use this “style” to avoid train wreck, where a series of getters is chained together like the carriages in a train.
we should ask to the object the question we really want answered, instead of asking for the information to help us figure out the answer ourselves.
adding a query method moves the behavior to the most appropriate object, gives it an explanatory name, and makes it easier to test.

unit-testing the collaborating objects

a circle object will send messages to one or more of its three neighbors when invoked. How can we test that it does so correctly without exposing any of its internal state?
one option is to replace the target object’s neighbors in a test with substitutes, or mock objects. We can specify how we expect the target object to communicate with its mock neighbors for a triggering event; we call these specifications expectations. During the test, the mock objects assert that they have been called as expected; they also implement any stubbed behavior needed to make the rest of the test work.
make clear the intention of every test: distinguish between the tested functionality, the supporting infrastructure, and the object structure.
JUnit uses reflection to walk the structure of a class and run whatever it can find in that class that represents a test.
test fixtures: a fixture may be set up before the test runs and torn down after it has finished. Many tests don’t need tear down and it’s enough to just let the JVM garbage work.
test runners: in charge of running the tests. Per example: Parameterized test runner let you write data-driven tests in which the same test methods are run for many different data values returned from a static method.

3. Kick-starting the Test-Driven Cycle

to run an initial end-to-end test that fails is already a lot of work. Deploying and testing right from the start of a project forces the team to understand how their system fits into the world. It flushes out the “unknown unknown”.
we view feedback as a fundamental tool, and we want to know as early as possible whether we’re moving in the right direction. Once we have our fist test in place, the subsequent tests will be much quicker to write.
one of the symptons of an unstable development environment is that there’s no obvious first place to look when something fails.
a walking skeleton is an implementation of the thinnest possible slice of real functionality that we can automatically build, deploy, and test end-to-end. “End-to-end” refers to the process, as well as the system. We want our test to start from scratch, build a deployable system, deploy it into a production-like environment, and then run the tests through the deployed system.
nothing forces us to understand a process better than trying to automate it. If it’s going to take six weeks to take six weeks and four signatures to set up a database, we want to know now, not two weeks before delivery.
we make the smallest number of decisions we can to kick-start the TDD cycle, to allow us to start learning and improving from real feedback.
no tests are perfect, of course, but in practice we’ve found that a substantial test suite allows us to make major changes safely.
the time to implement the first few features will be unpredictable as the team discovers more about its requirements and target environment.
incremental development can be disconcerting for teams and management who aren’t used to it because it front-loads the stress in a project. Projects with late integration start calmly but generally turn difficult towards the end as the team tries to pull the system together for the first time. Late integration is unpredictable because the team has to assemble a great many moving parts with limited time and budget to fix any failures. The result is that experienced stakeholders react badly to the instability at the start of an incremental project because they expect that the end of the project will be much worse. Our experience is that a well-run incremental development runs in the opposite direction. It starts unsettled but then, after a few features have been implemented and the project automation has been built up, settles in to a routine. As project approaches delivery, the end-game should be a steady production of functionality, perhaps with a burst of activity before the first release. All the mundane but brittle tasks, such as deployment and upgrades, will have been automated so that they “just work”.

4. Maintaining the Test-Driven Cycle

writing the tests before coding makes us clarify what we want to achieve. It makes us look at the system from the user’s point of view, understanding what they need it to do rather than speculating about features from the implementers’ point of view.
we prefer to start by testing the simplest success case. Once that’s working, we’ll have a better idea of the real structure of the solution and can prioritize between handling any possible failures we noticed along the way and further success cases. Of course, a feature isn’t complete until it’s robust. This isn’t an excuse not to bother with failure handling-but we can choose when we want to implement first.
we discover that these objects need supporting services from the rest of the system to perform their responsibilities. We write more objects to implement these services, and discover what services these new objects need in turn.
when we find a feature that’s difficult to test, we don’t just ask ourselves how to test it, but also why is it difficult to test. The same structure that makes the code difficult to test now will make it difficult to change in the future.
if we just test at too fine a grain, we’ll miss problems that arise from objects not working together.
how much unit testing should we do, using mock objects to break external dependencies, and how much integration testing? We don’t think there’s a single answer to this question. It depends too much on the context of the team.
The best we can get from the testing part of TDD, is the confidence that we can change the code without breaking it: Fear kills progress. The trick is to make sure that the confidence is justified.

5. Object-Oriented Style

we value code that is easy to maintain over code that is easy to write. Implementing a feature in the most direct way can damage the maintainability of the system, for example by making the code difficult to understand or by introducing hidden dependencies between components. Balancing immediate and longer-term concerns is often tricky, but we’ve seen too many teams that can no long deliver because their system is too brittle.
change as little code as possible. If all the relevant changes are in one area of code, we don’t have to hunt around the system to get the job done.
high level abstractions: that’s why most people order food from a menu in terms of dishes, rather than detail the recipes used to create them.
ports and adapters: the code for the business domain is isolated from its dependencies on technical infrastructure, such as databases and user interfaces. We don’t want technical concepts to leak into the application model, so we write interfaces to describe its relationships with the outside world in its terminology.
features without side effects mean that we can assemble our code from smaller components, minimizing the amount of risky shared state. We find that a little immutability within the implementation of a class leads to much safer code and that, if we do a good job, the code reads well too.
our heuristic is that we should be able to describe what an object does without using any conjunctions (“and”, “or”).
the API of a composite object should not be more complicated than that of any of its components.

6. Achieving Object-Oriented Design

first, starting with a test means that we have to describe what we want to achieve before we consider how. This focus helps us maintain the right level of abstraction for the target object. If the intention of the unit test is unclear then we’re probably mixing up concepts and not ready to start coding. It also helps us with information hiding as we have to decide what needs to be visible from outside the object. Third, to construct an object for a unit test, we have to pass its dependencies to it, which means that we have to know what they are. This encourages context independence, since we have to be able to set up the target object’s environment before we can unit-test it. A unit test is just another context. We’ll notice that an object with implicit (or just too many) dependencies is painful to prepare for testing and make a point of cleaning it up.
we think the communication patterns between objects are more important.
an interface describes whether two components will fit together, while a protocol describes whether they will work together.
we use tdd wih mock objects as a technique to make these communication protocols visible, both as a tool for discovering them during development and as a description when revisiting the code.
when starting a new area of code, we might temporarily suspend our design judgment and just write code without attempting to impose much structure. This allows us to gain some experience in the area and test our understanding of any external APIs we’re developing against. Splitting out a new object also forces us to look at the dependencies of the code we’re pulling out.
under time pressure, it’s tempting to leave the unstructured code as is and move on to the next thing (“after all, it works and it’s just one class…”). We’ve seen too much code where the intention wasn’t clear and the cost of cleanup kicked in when the team could least afford it.
we might be adding behavior to an object and find that, following our design principles, some new feature doesn’t belong inside it.
we give the new service a name and mock it out in the client object’s unit tests, to clarify the relationship between the two. Then we write an object to provide that service and, in doing so, discover what services that object needs. We follow this chain (or perhaps a directed graph) of collaborator relationships until we connect up to existing objects, either our own or from a third-party API.
when the test for an object becomes too complicated to set up when there are too many moving parts to get the code into the relevant state, consider bundling up some of the collaborating objects.
we use interfaces to name the roles that objects can play and to describe the messages they’ll accept.
the fewer methods there are on an interface, the more obvious is its role in the calling object. We don’t have to worry which other methods are relevant to a particular call and which were included for convenience. Narrow interfaces are also easier to write adapters and decorators for; there’s less to implement, so it’s easier to write objects that compose together well.
driving an interface from its client avoids leaking excess information about its implementers, which minimizes any implicit coupling between objects and so keeps the code malleable.
if there really isn’t a good implementation name, it might mean that the interface is poorly named or designed. Perhaps it’s unfocused because it has too many responsibilities; or it’s named after its implementation rather than its role in the client.

7. Building on Third-Party code

only mock types that you own - don’t mock types you can’t change
although we know how we want our abstraction to behave, we don’t know if it really does so until we test it in combination with the third-party code.
providing mock implementations of third-party types is of limited use when unit-testing the objects that call them.
a second risk is that we have to be sure that the behavior we stub or mock matches what the external library will actually do. How difficult this is depends on the quality of the library. Whether it’s specified (and implemented) well enough for us to be certain that our unit tests are valid. Even if we get it right once, we have to make sure that the tests remain valid when we upgrade the libraries.

write an adapter layer

if we don’t want to mock an external API, how can we test the code that drives it? We will have used TDD to design interfaces for the services our objects need – which will be defined in terms of our objects domain, not the external library.
we write a layer of adapter objects that uses the third party API to implement these interfaces. We keep this layer as thin as possible, to minimize the amount of potentially brittle and hard-to-test code. We test these adapters with focused integration tests to confirm our understanding of how the third party API works. There will be relatively few integration tests compared to the number of unit tests, so they should not get in the way of the build even if they’re not as fast as the in-memory unit tests.
following this approach consistently produces a set of interfaces that define the relationship between our application and the rest of the world in our application’s terms and discourages low-level technical concepts from leaking into the application domain model.
there are some exceptions where mocking third-party libraries can be helpful. We might use mocks to simulate behavior that is hard to trigger with the real library, such as throwing exceptions.

8. A Worked Example

even the best people misunderstand requirements and technologies or, sometimes, just miss the point. A resilient process allows for mistakes and includes techniques for discovering and recovering from errors as early as possible.
focus on just the immediate change at hand and merging changes back in is never a crisis.
we’ve often found it worth writing a small amount of ugly code and seeing how it falls out. It helps us to test our ideas before we’ve gone too far, and sometimes the results can be surprising. The important point is to make sure we don’t leave it ugly.
there are teams that overdo their design effort, but our experience is that most teams spend too little time clarifying the code and pay for it in maintenance overhead.
we try to minimize the time when we have code that does not compile by keeping changes incremental.
we’re grow our a design from what looks like an unpromising start. We alternate, more or less, between adding features and reflecting on - and cleaning up - the code that results. The cleaning up stage is essential, since without it we would end up with an unmaintainable mess. We’re prepared to defer refactoring code if we’re not yet clear what to do, confident that we will take the time when we’re ready. In the meantime, we keep our code as clean as possible, moving in small increments and using techniques such as null implementation to minimize the time when it’s broken.
we’re try hard to follow what the code is telling us instead of imposing our preconceptions.
we discover that some of the choices we made are no longer valid, so we dare to change existing code. We continue to refactor and sense that a more interesting structure is starting to appear.
nothing shakes out a design like trying to implement it, and between us we know just a handful of people who are smart enough to get their designs always right. Our coping mechanism is to get into the critical areas of the code early and to allow ourselves to change our collective mind when we could do better. We rely on our skills, on taking small steps, and on the tests to protect us when we make changes.
deciding when to change the design requires a good sense for tradeoffs, which implies both sensitivity and technical maturity: “I’m about to repeat this code with minor variations, that seems dull and wasteful” as against “This may not be the right time to rework this, I don’t understand it yet”.
as we learn more about what the structure should be by using the code we’ve written, we learn more about the names we’ve chosen when we work with them.
draw something when you don’t know exactly where to start.
The skill is in learning how to divide requirements up into incremental slices, always having something working, always adding just one more feature.

9. Listening to the Tests

when writing a test is hard, it can means that your design can be improved.
we’ve found that a object easy to test is also easy to change.
TDD is also about feedback on the code’s internal qualities: the coupling and cohesion of its classes, dependencies that are explicit or hidden, and effective information hiding.
we don’t just ask ourselves how to test it, but also why is it difficult to test.
instead of using Date directly we introduce Clock and pass it into the Receiver class.
tests for supportive logging: protect us from breaking any tools and scripts that other people write to analyze them.
tests for diagnostic logging: not necessarily tested.
clients should not be forced to depend upon interfaces that they do not use, but that’s exactly what we do when we mock a concrete class.
interfaces give us better information-hiding and clearer abstractions.
once a codebase starts to “rot”, the developers will be under pressure to botch the code to get the next job done. It doesn’t take many such episodes to dissipate a team’s good intentions.
test names should act as documentation for the code.
AAA: arrange, act and assert.
all code should emphasize “what” it does over “how”.
our highest concern is making the test describe what the target code does, so we refactor enough to be able to see its flow.
write test data builders
allocate literal values to variables and constants with names that describe their function.

10. Test Diagnostics

a “failing” test has succeeded at the job it was design to do, but it needs to be clear about the failure’s reason.
sometimes is quicker to roll back and restart with a clear head than to keep digging.
the tests overspecify the expected behavior of the target code, constraining it more than necessary.
mind methods returning null to other objects since null can be used as a return of anything. So if you’re mocking something make sure that is returning the right thing rather than just forcing a “null” return.
use expressive assertions.
commands have side effects, queries don’t.
high level tests to make sure that everything works together.
make sure every test starts with the database in a known, clean state.
ORM mappings can by declarative or configuration, but misconfiguration creates defects that are difficult to diagnose, so we use round-trip tests so we can quickly identify the cause of such defects.
tests with realistic infrastructure are slower than with in memory database. We also can unit-test our code by defining a clean interface to the persistence infrastructure.

Notes from Building Microservices

Thu, 03 Jan 2019 11:00:00 +0000

1. Microservices

Domain-driven design, continuous delivery, on demand virtualization, infrastructure automation, small autonomous teams and systems at scale: microservices have emerged from this world.
in a monolithic system we try to make sure that our code is cohesive, trying to group code together (single responsibility principle).
small and autonomous services that work together.
microservices is also focus in high cohesion. It focus service boundaries on business boundaries, making it obvious where code lives for a given piece of functionality. And keeping it focused we avoid the temptation to grow it large.
the rule of thumb gave in the book is that a microservice could be rewritten in two weeks.
if a team is small, breakdown into microservices can be very sensible
microservice it’s a separate entity. We try to avoid packing multiple services onto the same “machine”
all communication between the services themselves are via network calls, to enforce separation between the services and tight coupling.
these services need to be able to change independently of each other, and be deployed by themselves without requiring consumers to change.
our services exposes an application programming interface (API), and collaborating services communicate with us via those APIs.
the golden rule: can you make a change to a service and deploy it by itself without changing anything else?
if one part of our system needs to improve its performance, we might decide to use a different technology and this is easy to approach with a microservices architecture than with a monolith.
resilience: if one component of a system fails, but that failures doesn’t cascade, you can isolate the problem and the rest of the system can carry on working.
scaling: we can just scale those services that need scaling, allowing us to run other parts of the system on smaller, less powerful hardware.
ease of deployment: a one-line change to a big codebase requires the whole application to be deployed.
composability: with microservices, think of us opening up seams in our system that are addressable by outside parties. As circumstances change, we can build things in different ways. With our services being in small size, the cost to replace them with a better implementation, or even delete them altogether is easier to manage.
you should think of microservices as a specific approach for SOA
you’ll have to get much better at handling deployment, testing, and monitoring to unlock the benefits we’ve covered so far.

Shared libraries

you lose true technology heterogeneity. The library typically has to be in the same language, or at the very least run on the same platform.
unless you’re using dynamically linked libraries, you cannot deploy a new library without redeploying the entire process, so your ability to deploy changes in isolation is reduced.
you’ll find yourself creating code for common tasks that aren’t specific to your business domain that you want to reuse across the organization, which is an obvious candidate for becoming reusable library.
shared code used to communicate between services can become a point of coupling.

2. The Evolutionary Architect

the architecture needs to make sure we have a joined-up technical vision, one that should help us deliver the system our customers need.
bridges and buildings will fall down much less than the number of times our programs will crash, making comparisons with engineers quite unfair.
our architecture needs to shift their thinking away from creating the perfect end product, and instead focus on helping create a framework in which the right systems can emerge, and continue to grow as we learn more.
architecture have a duty to ensure that the system is habitable for developers too.
you may be OK with a team picking a different technology in a area of the system that they own.
“be worried about what happens between the boxes, and be liberal in what happens inside”
strategic goals should focus in making the customers happy: “let the customer achieve as much as possible using self-service”.
principles: rules you have made in order to align with a goal: if a goal is to decrease time to market, so you may define that teams will have full control over the lifecycle, independently of any other team.
practices: how we ensure the principles are being carried out: all logs need to be centralized; HTTP/REST is the standard integration style.
the principles between a Java and a .NET team can be equal, but the practices different. You can have some documentation around principles and practices.

what we need to ensure that one bad service doesn’t bring down the whole system?
we need to find the balance between autonomy of the service without losing sight of the bigger picture.

Other aspects of microservices

ensure that all services emit health and general monitoring metrics in the same way (push data into a central location or some polling system).
if you pick HTTP/REST, are you going to handle pagination and versioning?
ensure that our services shield themselves from unhealthy, downstream calls.
write good documentation with examples in order to expose your service.
what if the developers had a template to implement core attributes that each service needs? (some of the practices already in place).
if a lot of exceptions happen around the principles/practices, then we can change to reflect a new understand of it.
I often take the approach that I should go with the group decision. Even that this means going with a decision that you don’t agree with.
the team needs to understand the vision themselves.

How to model services

*what the world stood? On a tortoise. And what does the tortoise stand? On another tortoise.”
a change to one service should not require a change to another.
we want to limit the number of calls from one service to another, because beyond the potential performance problem, chatty communication can lead to tight coupling.
related behavior sit together and unrelated behavior sit elsewhere.
each bounded context has an explicit interface. There is an internal-only representation, and the external representation we expose.
premature decomposing can be costly if you’re new to the domain. Break a monolith is easier than going microservices from day one.
you need to think about bounded contexts from a capability perspective and not about data that is shared.
if a new field is added to a piece of data, existing costumers shouldn’t be impacted.
any technology that push to expose internal representation should be avoided.
shared database: we’re allowing services to view and bind to internal implementation details and tight to all of them to one specific technology

Communication

synchronous: it blocks the operation until is complete
synchronous: doesn’t wait for the operation be complete and may not even care if it was complete or not
with an event-based collaboration, we invert things. Instead of a client initiating requests asking for things to be done, it instead says this thing happened and expects other parties to know what to do. You can just add subscribe to these events.
orchestration vs choreography: with orchestration we rely on a central brain to guide and drive the process, much like the conductor in a orchestra. With choreography, we inform each part ot its job, and let it work out the details.
you need to be aware of orchestration, because you can end up with god services communicating too much with other services.
with choreography you need extra work to ensure that you can monitor that the right things have happened.
I strongly prefer aiming for a choreographed system, where each service is smart enough to understand its role in the whole dance
the client has to understand the semantics of the API in much the same way as a human being needs to understand that on a shopping website the cart is where the items to be purchased will be.
provide links to allow consumers to navigate in the API endpoints (HAL standard per example).
for choreography: message brokers. And use dead-letter-queues to retry messages in another time.
have a good monitoring and consider the use of correlation IDs, which allow you to trace requests across process boundaries.
rather than make code shared, the company copies it for every new service to ensure that coupling doesn’t leak in. The evils of too much coupling between services are far worse than the problems caused by code duplication. For logging libraries is ok, since is not related with domain logic.
the best way to reduce impact of making breaking changes, is to avoid making them in the first place.
MAJOR change contains incompatible changes; MINOR new functionality but still compatible and PATCH just for bug fixes.
keep more than one version running and stop it when all the services migrated to the new one.
the longer it takes to these services to update, you should look to coexist different endpoints in the same microservice.

3. Microservices and UI

users don’t want to feel that different parts of the interface work in different ways.
backend for frontends: it can handle multiple backend calls and aggregate content if needed. This can lead to everything being thrown in together, and suddenly we start to lose isolation of our various user interfaces, limiting our ability to release them independently. It should contain behavior specific to delivering a particular user experience.

4. Splitting the Monolith

identify the boundaries in our code.
the packages should interact in the same way the real-life organizational groups in our domain interact.
split as you go: think about where you are going to get the most benefit from some part of the codebase being separated. Other criterias: areas that demands more frequent changes; or team location (different countries); technology
sometimes making one thing slower in exchange for other things is the right thing to do, specially if slower is still acceptable.
sometimes the system will change because some concept that was not there before had a need and then it was “borned”.
eventual consistency: we accept that the system will get itself into a consistent state at some point in the future. Or we can just revert the transaction and try again.
be aware of report generation: some calls can require big amounts of data. Data pumbs: push data to the report system using the database of each microservice. We can push to this system as soon we see that an event happened (a user created per example). Or we can go towards eventing system capable of routing our data to multiple different places depending on need.
when trying to figure out the impact of a change: what calls get made? Is there any circular references? Do you see two services that are overly chatty? (this can indicate that they should be just one).

5. Deployment

is good to have the entire path to production to see the quality of our software and to reduce the time take between releases, as we have one place to observe our build and releases process.
have pre-baked images with already installed dependencies to run the service.
install the configuration of the services in the source control.
the more your configuration changes, the more you will find problems only in certain environments.
be aware in how to handle sensitive information (credentials per example).
carefully when deploying different services at the same host. This way you’re not 100% making them separated, since an overload in one service can compromise the resources for the other services. An outage to one host should impact only a single service.
can you write a line of code to launch a virtual machine, or shut one down? Can you deploy the software you have written automatically? Can you deploy database changes without manual intervention? Embracing a culture of automation is key if you want to keep the complexities of microservice architectures in check.
use containers: one host, multiple containers with one service each.

6. Deployment

you will want tests of different scope for different purposes.
“we decide that from a feedback point of view we had way too many service and end-to-end tests”
mountbank to stube calls to other systems
as test scope increases, so too does the number of moving parts. A test can fail because some service is down, and this is not related to the nature of the test itself. If you have tests that sometimes fails, but everyone just re-runs them because they may pass again later, then you have flaky tests.
normalization of deviance: the idea that over time we can become so accustomed to things being wrong that we start to accept them as being normal and not a problem.
not shared end-to-end tests: everyone is going to assume it is someone else’s problem.
if the same feature is covered in 20 different tests, perhaps we can get rid of half of them.
with a long test suite, any breaks take a while to fix. And while a broken integration test stage is being fixed, more changes from upstream teams can pile in.
TEST JOURNEYS, NOT STORIES. High value interactions and very few in number.
consumer-driven tests to the rescue: we don’t want our changes to break consumers. We are defining the expectations of a consumer on a service (or producer). The expectations of the consumers are captured in code form as tests, which are then run against the producer. If done right, these CDCs should be run as part of the CI build of the producer, ensuring that it never gets deployed if it breaks on of these contracts.
on the producer side, you then verify that this consumer specification is met by using the JSON Pact specification to drive call against your API and verify responses.
these end-to-end tests may form a useful safety net, where you are trading off cycle time for decreased risk. But be aware that you will not eliminate all sources of defects.
smoke test suite: a collection of tests designed to be run against newly deployed software to confirm that the deployment worked.
blue green deployment: by keeping the old version running while we perform our release we greatly reduce the downtime associated with releasing our software.
create a good process to revert code from a new deployment and back to a previous version.
execute performance tests.

7. Monitoring

at bare minimum, monitore the response time of the service
number of errors
central aggregations for logs and metrics
are we reaching out limit? How long until we need more hosts?
track what features that is never been actually used.
what is a good cpu level for the application?
a way to track a call in all the services (as in a stack trace).
standardize the way that you monitor in your services.

8. Security

authentication: I’m who I’m saying I am.
principal: who or what is been authenticated.
authorization: map the action that lets the principal execute it.
inside the own network, sometimes there is no authentication. But then is easier for an attack to get information once inside this network.
use HTTPS
API keys allow a service to identify who is making a call, and place limits on what they can do.
application firewall can help throttle connections from certain IP ranges and detect other sorts of malicious attacks.
how do you revoke access to credentials when someone leaves the organization?

9. Other notes and tools

organizations that can change their structure is likely to have faster time to market.
no matter how it looks at first, it’s always a people problem.
assume that failure, in some aspect, is going to happen.
how long an operation can last? Can you expect a service to be down? How much data loss is acceptable?
what happens if “this” is down?
fail fast!. Do not have slow requests at your system. Avoid calling unhealthy systems in the first place.
use circuit breakers: all requests fails while the circuit breaker is in its blown state. After a certain period of time, the client sends a few requests through to see if the service has recovered.
CQRS: command-query responsibility segregation: the command and query parts of our system could live in different services, or different hardware, and could make use of radically different types of data store.
be conscious about your cache configuration. Don’t let the cached data living too long.
you can autoscale when you see an increase in load or an instance failure.
use a service to share configuration between multiple nodes.
zookeeper: general or service specific configuration, allowing you to do tasks like dynamically changing log levels or turning off features of a running system.

Notes from Practical Vim

Thu, 27 Dec 2018 11:00:00 +0000

Some of the content of this book I already knew, but it was good to understand them in a deeper level and how can I extend the usage from most of the basic commands that I have been using before.

the . command let us repeat the last change. It is the most powerful and versatile command vim
the >G command increases the indentation from the current line until the end of the file
the x, dd and > commands are all executed from Normal mode, but we also create a change each time we dip into Insert mode. From the moment we enter in IM, vim records every keystroke
A to insert in the end of the current line
the ; command will repeat the last search that the f command performed
to perform an substitution in a file :s/target/replacement
* searchs for the next occurrence of the word under the cursor
vim records our keystrokes until we leave IM
the author mentions the dot formula: one keystroke to move, one keystroke to execute
dw deletes a word
dw deletes a word and a space
list of vim operators: they can operate on a single character dl, a complete word daw, or an entire paragraph dap:
- c: change
- d: delete
- y: yank into register
- g~: swap case
- gu: make lowercase
- gU: make uppercase
- >: shift right
- <: shift left
- =: autoindent
grammar: an action is composed from an operator + motion
when invoking the operator in duplication (dd per example) it acts upon the current line
you can add operators to vim: take the commentary.vim plugin. The operator it’s gc, so gcc comments the current line
editing from the IM:
- ctrl + h: delete back one char
- ctrl + w: delete back one word
- ctrl + u: delete back to start of the line
viw: select inner word in visual mode
to enter in IM: i it’s for before the current char and a (append) after the current char
when we open a file, vim creates a new buffer and loads it into the current window

inline search

f{char} searchs for the next char occurrence
F{char} for previous char occurrence
t{char} searchs for the char before next char occurrence
T{char} searchs for the char before previous char occurrence
; repeat the last character-search command
, reverse the last character-search command

motions for lines

j: down one real line
gj: down one display line
k: up one real line
gk: up one display line
0: to first character of the real line
g0: to first character of the display line
ˆ: to first nonblank character of the real line
gˆ: to first nonblank character of the display line
$: to end of the real line
g$: to end of the display line

motions for words

w: forward to start of next word
b: backward to start of current/previous word
e: forward to end of current/next word
ge: backward to end of previous word
append to end of word: ea
append to end of previous word: gea
definition of a WORD: sequence of nonblank characters separated with whitespaces
vim’s text objects consist of two characters, the first of which is always either i or a. In general, we can say that the text objects prefixed with i select inside the delimiters, whereas those that are prefixed with a select everything including the delimiters
ci": change inside the double quotes
d{motion} tends to work well with aw, as and ap whereas the c{motion} command works better with iw and similar

other motions

": position before the last jump within current file
%: jumps between opening and closing sets of (), {}, []
<Leader>f{char}: my leader key is ,, so ,f{char} would show the keys that I can press to go to {char}. This also works with AceJump IntelliJ plugin with you configure the keys properly.

surround.vim plugin

cs"': change surround from " to '
ds': delete surround '
ysiw[: add surround in an inner word with [

windows management

ctrl + w + s: split current window horizontally
ctrl + w + v: split current window vertically
ctrl + w + w: cycle between open windows
ctrl + w + h: focus the window to the left
ctrl + w + j: focus the window below
ctrl + w + k: focus the window above
ctrl + w + l: focus the window right
ctrl + w + c: close the active window
ctrl + w + T: move the current window into its own tab
{N}gt: switch to tab page number {N}
gt: switch to the next tab page
gT: switch to the previous tab page

visual mode

v enables character-wise visual mode
V enables line-wise visual mode
ctrl + v enables block-wise visual mode
gv reselects the last visual selection
the . command in visual mode acts on the same amount of text as was marked by the most recent visual selection. But doesn’t work so well sometimes
vit: select the inner contents of a tag

copy and paste

in Vim’s terminology, we don’t deal with the clipboard but instead with registers
the x command cuts the character under the cursor, placing a copy of it in the unnamed register after the cursor position
yyp: copy and paste line
“Oops! I clobbered my yank”: you had something to paste, but before pasting it you had to cut something and then your previously yanked text was replaced by the cut that you did
vim’s delete command is equivalent to the standard cut operation
black hole register is addressed by the - symbol, so _d{motion performs a true deletion
delete, yank and put commands interact with one of Vim’s registers. We can specify which register we want to use by prefixing the command with "{register}. If we don’t specify the register, then Vim will use the unnamed register
example: cut the current line into register b with "bdd and paste it with "bp
when we use y{motion} command, the specified text is copied not only into the unnamed register but also into the yank register, which is addressed by the 0 symbol. The yank register is reliable, whereas the unnamed register is volatile. We can cut something and when using "0p we would still have what we want
copying and paste from clipboard:
- if we capture text in an external application, then we can paste it inside Vim using "+p command
- if we want to copy text from vim to an external application, then we have to use the register "+
the visual selection in the document swaps places with the text in the register
p: pastes after the cursor position
P: pastes before the cursor position

macros

when recording a macro, ensure that every command is repeatable
w, b, e is better for macros than h, j, k, l
q{register} (you don’t need the ") to start recording a macro. The word recording should appear in the status
q is a good register for a macro, so you just need to press qq to start recording and then a final q to finish
@{register} command executes the macro in the given register
@@ repeats the that was invoked most recently
to append commands in a macro: if you macro was q, then use Q. Per example qQ to start appending commands in the previous macro that you recorded using qq

search and replace

%s/going/rolling/g: it will search and replace in the whole file the word going for rolling
%s/going/rolling/gc: it will ask every time that it finds a going if we want to replace it for rolling