diff --git a/knowledge base/best practices.md b/knowledge base/best practices.md index e9b8705..01de818 100644 --- a/knowledge base/best practices.md +++ b/knowledge base/best practices.md @@ -1,6 +1,6 @@ # OAM best practices -What really worked for me. +What really worked for me personally, or in my experience. 1. [Generic concepts](#generic-concepts) 1. [Teamwork](#teamwork) @@ -43,7 +43,7 @@ What really worked for me. - Stop [abstracting away][we have used too many levels of abstractions and now the future looks bleak] stuff that does not need to be (`docker-cli`/`kubectl` wrappers mapping features 1-to-1, anyone?). - Beware of complex things that _should be simple_.
- E.g., google what the _[SAFe] delusion_ is. + E.g., check what the _[SAFe] delusion_ is. - Focus on what matters, but also set time aside to work on the rest.
Check [Understanding the pareto principle (the 80/20 rule)]. - Learn from your (and others') mistakes.
@@ -53,11 +53,11 @@ What really worked for me. [abstractions][we have used too many levels of abstractions and now the future looks bleak]. - Keep different parts **de**coupled where possible, the same way [_interfaces_ are used in programming][what does it mean to program to interfaces?].
- This allows for quick and (as much as possible) painless switch between technologies. + Allows for quick and (as much as possible) painless switch between technologies. - The _one-size-fits-all_ approach is a big fat lie.
- You'll end up with stiff, hard to change results that satisfy nobody. This proved particularly true with regards to - templates and pipelines.
- Stop designing systems that _should work for everybody at all times_. + One'll end up with stiff, hard to change results that satisfy nobody. This proved particularly true with regards to + _templates_ and _pipelines_.
+ Stop designing systems that _should work for everybody at all times_. Prefer safe defaults instead. - Choose tools based on **how helpful** they are **to you** to achieve your goals.
Do **not** adapt your work to specific tools. - Keep track of tools' EOL and keep them updated accordingly. @@ -67,38 +67,37 @@ What really worked for me. - [Branch early, branch often]. - [Keep a changelog]. - [Keep changes short and sweet][the art of small pull requests].
- Nobody likes to dive deep into a 1200 lines, 356 files pull request ([PR fatigue][how to tackle pull request fatigue], - everybody?). -- Consider keeping changes in _behaviour_ (logic) separated from changes to the structure.
+ Nobody likes to dive deep into a 1200+ lines, 356+ files pull request + ([PR fatigue][how to tackle pull request fatigue], right?). +- Consider keeping changes in _behaviour_ (logic) separated from changes to the _structure_.
It allows for easier debugging by letting you deal with one great issue at a time. -- Make changes easy, avoid making easy changes.
- Easy changes will build up long term and become a pain to deal with. -- [Trunk-based development][trunk-based development: a comprehensive guide] and other branching strategies all +- Make changes easy, avoid making _easy changes_.
+ Easy changes will only build up with time and become a pain to deal with long term. +- [Trunk-based development][trunk-based development: a comprehensive guide] and other branching strategies **all** work.
Consider the [different pros and cons of each][git branching strategies vs. trunk-based development]. - Refactoring _can_ be an option.
Just **don't default** to it nor use it mindlessly. - Be aware of [corporate bullshit][from inboxing to thought showers: how business bullshit took over]. - _DevOps_, _GitOps_ and other similar terms are sets of practices, suggestions, or approaches.
- They are **not** roles or job titles.
- They are **not** to be taken literally.
+ They should **not** roles or job titles.
+ They should **not** to be taken literally.
They **need** to be adapted to the workplace, not the other way around. -- [Amazon's leadership principles] are double-edge swords.
- They are generally good practices, but only Amazon is able to apply them as they are defined **and** they still create - a lot of discontent when used against people. +- [Amazon's leadership principles] are generally good practices, but also double-edge swords.
+ They still create a lot of discontent even inside Amazon when used _against_ anybody. - Keep Goodhart's law in mind: > When a measure becomes a target, it ceases to be a good measure. ## Teamwork - Respect what is already there, but strive to improve it.
- Current solutions are there for a reason. Learn about their ins and outs **and, most of all, the why**.
- Then try to make them better. + Current solutions are there for a reason. Learn about their ins and outs **and, most of all, the why**. Only _then_, + it makes any sense to try to make them better. - Don't just dismiss your teammates' customs.
E.g., use [EditorConfig] instead of your editor's specific setting files only. -- You, your teammates and other teams in your company _should be_ on the same boat and _should be_ shooting for the same - goal.
- Act like it. You may as well collaborate instead of fighting. +- One and one's contributors (e.g. one's teammates and other teams in one's company) _should be_ on the same boat and + _should be_ shooting for the same goals.
+ Act like it. You may as well collaborate instead of fighting each other. ## CI/CD specific @@ -109,32 +108,36 @@ What really worked for me. ### Pipelining - Differentiate what the concept of pipelines really is from the idea of pipelines in approaches like DevOps.
- Pipelines are sequences of actions. Pipelines in DevOps and alike end up being magic tools to take actions away from - people. + Pipelines in general are nothing more than _sequences of actions_. Pipelines in DevOps and alike end up most of the + times being _magic tools that take actions away from people_. - Keep in mind [the automation paradox].
- Pipelines tend to easily become complex systems just like Rube Goldberg machines. + Pipelines tend to become complex systems just like Rube Goldberg machines. - Keep tasks as simple, consistent and reproducible as possible.
- Avoid like the plague to put programs or scripts in pipelines: they should be _glue_, not replace applications. + Avoid like the plague relying on programs or scripts written directly in pipelines: pipeline should act as the _glue_ + connecting tasks, not replace full fledged applications. - All tasks should be able to execute from one's own local machine.
This allows to fail fast and avoid wasting time waiting for pipelines to run in a black box somewhere. -- Consider using local automation to guarantee basic quality **before** the code reaches the shared repository.
- Tools like [`pre-commit`][pre-commit] or [`lefthook`][lefthook] are a doozy for this. -- DevOps pipelines are meant to be used as **last mile** steps for specific goals.
+- DevOps pipelines should be meant to be used as **last mile** steps for specific goals.
There **cannot** be a single pipeline for everything, the same way as the _one-size-fits-all_ concept never really works. +- Try and strike a balance between what **needs** to be done centrally (e.g. from a repository's `origin` remote) and + what can be done locally from one's machine **before** the code reaches repositories' remotes.
. + Tools like [`pre-commit`][pre-commit] or [`lefthook`][lefthook] are a doozy for this, but can disrupt the development + experience and encourage the use of the `--no-verify` switch. Actions that need to be enforced (e.g. automatic + formatting) are usually worth done only when changes reach the central remote anyways. ## Product engineering -Consider what follows for infrastructure and platform engineering as well. +Consider what follows for _infrastructure_ and _platform engineering_ as well. -- Focus on creating things users will want to use.
+- Focus on creating things users will **want** to use.
Tools should solve issues and alleviate pain points, not create additional walls. -- Focus on small audiences first. Avoid trying appealing lots of users from the beginning.
- If you do not have a user base, the product has no reason to exist but your will to create it. +- Focus on **small** audiences first. Avoid trying appealing lots of users from the very beginning.
+ If one does not have a user base, one's product has no reason to exist but one's will to create it. - Consider and fix users' pain points **before** adding new features.
- If users are not happy with your tool they'll try moving away from it, bringing the discussion back to the previous + If users are not happy with one's tool they'll try moving away from it, bringing the discussion back to the previous point in this list. -- Avoid creating mindless abstractions, like templates using variables for all their attributes.
+- Avoid creating mindless abstractions, like templates using variables for _all_ their attributes.
Prefer providing one or at most a few simplified solutions that use different [adapters or interfaces][what does it mean to program to interfaces?] in the background instead.
E.g., check out how [Crossplane] works.