brandon/oam
1
0
Fork 0
mirror of https://gitea.com/mcereda/oam.git synced 2026-02-09 05:44:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
4890a997a89a59b43a8222471a14c45b6bf28edc
oam/knowledge base/best practices.md
Michele Cereda 4890a997a8 refactor: specific sections
2024-01-06 03:15:58 +01:00

9.1 KiB
Raw Blame History

OAM best practices

What really worked for me.

  1. Generic concepts
  2. CI/CD specific
    1. Pipelining
  3. Product engineering
  4. Sources

Generic concepts

  • Always think critically.
    If you do/think things just bEcAuSe OtHeRs SaId So, all you're doing is admitting both that you know no better and that you're not willing to consider otherwise.
  • 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.
  • Apply the KISS approach wherever possible.
    Consider it not as keeping all things simple because they need to be simple, but as an invite to keep things simple with respect of your ultimate goal.
    Beware of simplicity for the sake of simplicity, specially if this makes things complicated on a higher level. Check out KISS principle is not that simple.
  • Beware of complex things that sHoUlD bE sImPlE.
    Check out the SAFe delusion.
  • There is no perfect nor correct solution, just different sets of tradeoff.
    Find the one that most satisfies you and your current necessities.
  • Review every decision after some time. Check they are still relevant, or if there is some improvement you can implement.
    Things change constantly: new technologies are given birth often, and processes improve.
  • Focus on what matters, but also set time aside to check up the rest.
    Check Understanding the pareto principle (the 80/20 rule).
  • Learn from your (and others') mistakes.
  • Put in place processes to avoid repeating mistakes.
    Check out the 5 whys approach.
  • Automate when and where you can, yet mind the automation paradox.
    Check also out pre-commit.
  • Keep things decoupled where possible, the same way interfaces are used in programming.
    This allows for quick and (as much as possible) painless switch between technologies.
  • Choose tools based on how helpful they are to achieve your goals.
    Do not adapt your work to specific tools.
  • Backup your data, especially when you are about to update something.
    Murphy's law is lurking. Consider the 3-2-1 backup strategy.
  • Branch early, branch often.
  • Keep changes short and sweet.
    Nobody likes to dive deep into a 1200 lines, 356 files pull request (PR fatigue, everybody?).
  • 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 and other branching strategies all work.
    Consider the different pros and cons of each.
  • Refactoring can be an option.
    Just don't use it mindlessly.
  • 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 need to be adapted to the workplace, not the other way around.
  • Be aware of corporate bullshit.
  • Amazon's leadership principles are double-edge swords.
    Only Amazon was able to apply them as they are defined, and they still create a lot of discontent.

CI/CD specific

  • Keep integration, delivery and deployment separated.
    They are different concepts, and as such should require different tasks.
    This also allows for checkpoints, and to fail fast with less to no unwanted consequence.

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.
  • Keep in mind the automation paradox.
    Pipelines tend to easily 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.
  • 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 blackbox somewhere.
  • DevOps pipelines are 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.

Product engineering

Consider what follows for infrastructure and platform engineering as well.

  • 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.
  • 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.

Sources

In order of addition: