The most important convention lies in your build system

The conversation

rick: “OK, good, it seems the build is successful! So we can create the merge request and eventually release the software in production!”
john: “No, wait… you need to push on git and then wait for the pipeline on Gitlab”
rick: “oh ok. Let’s push the changes. (wait some minutes for the pipeline). OK, the pipeline is ok… so now we create the merge request!”
john: “Yes sure… (after some time for the code review)… “
rick: “OK the branch has been merged, so now I think we can release it”
john: “No, wait… maybe we should get a feedback in our QA environment”
rick: “oh why? don’t we have already a green build?”
john: “well yes, but it doesn’t test everything”
rick: “oh OK… yes… it happens sometimes… let’s make this manual test… (after dozens and dozens of minutes). OK, it seems working. Now we can release it!”
john: “oh nooooo!”
rick: “what’s happened?”
john: “the step after the deploy in our QA env failed!”
rick: “and?”
john: “they are our ‘api-tests'”
rick: “what do they do? a sort of end to end tests?”
john: “no, we call “end to end test” tests that involve all services. These ‘api-tests’ are run just against this service”
rick: “oh ok, but why are we running them now and not with our build system?”
john: “because they are slow”
rick: “mhm… whatever… where can I find them?”
john: “they are in the same project. There is a specific directory for them”
rick: “so they are in the same project but we do not run them in our build system, right?”
john: “yes, because they are slow”
rick: “yeah I get it”
john: “anyway you can run them manually… you have just to run in IntelliJ xyz and then you can open that folder and run in IntelliJ xyz”
rick: “yeah… manually… of course… ok 😕 let’s see why they are failing, right?”
john: “oh I found! the data they are based on are no more available… we have to find some others…”
rick: “sorry, are they based on data coming from other systems?”
john: “yes”
rick: “so if someone touches those systems and those data, our api-tests fail miserably, right?”
john: “yes”
rick: “and we need to check the error, find new data allowing them to pass and update them, right?”
john: “yes”
rick: “OK, it’s 6.00 PM… and I’m tired… can we fix this tomorrow?

Feelings, agreements, time

There are a lot of things happening in this conversation.
If you look at the feelings of rick and john, it seems clear that while both started with high energy and passion, rick‘s feelings are degenerating… but why? Even john‘s feeling are not so good when api-tests fail, but not for the rest of the conversation.
If you look at what they are discussing, it seems like rick was expecting something from the build system… but what is that?
If you look at the conversation itself, you can imagine that it required some time… but they were just finishing a feature, weren’t they?
What’s your opinion about this conversation?
Do you feel more near to rick or to john?

Rick is right

Rick is right.
How do I know that?
Because Rick is asking just one simple thing: reduce cognitive load needed in this project to understand that something can be delivered in production.

We all have our tools: make, ant, maven, gradle, npm, …
We all have our commands, “phases” or tasks.
But what is missing here is the most simple convention you need in your build system: when you run the default command of your build system and it is green, the software can be released in production.

Let’s imagine if you have dozens and dozens of projects: do you feel comfortable in reading dozens and dozens of docs (maybe the RELEASE chapter in your README.md) in order to understand how to make a release? do you think it’d be simple to follow dozens and dozens of checklists with different steps between each other on how to be sure your software is working as expected?

What about John?

I don’t know John.
But what I think is that John focused mainly on the software strictly related to the product forgetting that as an engineer/software-developer all processes and tools used during development phases of that software need the same care.
In this specific case, it seems the release process of that software have been left undone… as a checklist… maybe to be memorized and to teach to new colleagues…
Such a waste of time!

Excuses

“Yes, you’re right! But in my company we have XYZ so this cannot be done”

I won’t answer to one of my colleagues in this way, but because this is my blog, I can be totally direct (and probably a little bit rude):
This is just an excuse.
I know that you are an engineer, my dear reader.
And as an engineer, you know that there is “very often” a solution to everything (yeah “always” can be too much sometimes).

Focus on the outcome: how simple would be releasing your project with such a convention in place?

3 things to remember when you play with MS Word docs in Java

I’m playing with my maven plugin (https://github.com/sixro/vodafonecanvassrelease-maven-plugin) and I need to insert texts in a MS Word document. Unfortunately there are some pitfalls you have to know if you use the Apache POI Java library. Continue reading 3 things to remember when you play with MS Word docs in Java

DRY? Create a Maven plugin!

“Don’t Repeat Yourself” is a rule, but sometimes I don’t remember that (do I need a wallpaper?). Today I realized that I was spending lots of my time following guidelines of a client company (Vodafone Italy) about “how to package a release for the next Canvass”… and this happens whenever a release should be built.
Now it is the time to create something to automate this!
It’s time for a new Maven plugin! Continue reading DRY? Create a Maven plugin!