Download to read offline
More Related Content
Similar to Architecture decision records
Architecture decision records
- 1. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL Top 1:32 #Architecture decision records ## How not to get lost in the past
- 2. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # About me -Krisztián Papp - Principal Software Engineer @ Diligent - <3 Neovim - Enemy of the mutable state - Founder/co-host at letscode.hu 6% 2:32
- 3. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Software isevolving - Thousands of decisions are made during the lifetime of a software - Most of it is not documented or lost already - Along with the decision the context is also lost 2% 3:32
- 4. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # What isarchitecture? - Hard to change - Important stuff - High business value - High cost - High technical risk 12% 4:32
- 5. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL > An architecturedecision is a justified software design choice that addresses a functional or non-functional requirement that is architecturally significant. - https://adr.github.io/ 15% 5:32
- 6. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # What isan architecture decision? - Using event-driven architecture - Choosing a cloud provider - Monolith or microservices - Replacing MariaDB with <add your favorite NoSQL database here> - Using peer-to-peer vs client-server - Creating a data lake - Use gitflow workflow 2% 5:32
- 7. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Why dowe use this or that? - Well there is a historical reason… - Okay, what is that? - You need to know the context… - Okay, tell me about it - I don’t know… 2% 6:32
- 8. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Things youdon’t know - You plan to offload some functionality to AWS lambda - You research it, it seems to be a good decision - You implement it - Your company get sued by customers because their data shouldn’t leave your data center 2% 7:32
- 9. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Situation: Storinghighly dynamic structure in a relational database - Why didn’t we use XY? - We needed the referential integrity and transactions. - But XY also supports transactions! - We implemented it in 2009 when XY wasn’t around. 2% 8:32
- 10.
- 11. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL > An architecturedecision record (ADR) is a document that captures an important architectural decision made along with its context and consequences. 2% 10:32
- 12. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Title: "ADR-01:Temporal as global workflow management." ## Context: "Temporal was presented at recent conference, apparently the speaker was very convincing. Our RabbitMQ administrators are bored." ## Decision: "We will replace all existing messaging with Temporal workflows." ## Status: "decided" ## Consequences: ### Good: "I can add Temporal to the skills section of my CV." ### Neutral: "We are in line with what everybody does these days." ### Bad: "We will have to re-implement all existing messaging endpoints and migrate all data in transit. Test cases and audit procedures will have to be revisited too." 2% 11:32
- 13. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL Top 1:32 2%12:32 - markdown based - renders HTML - seamless Github integration # Log4brains
- 14.
- 15. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # How doesthe workflow look like? 2% 14:32
- 16. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL 2% 15:32 #Have an architecturally significant decision up ahead
- 17.
- 18. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL 2% 17:32 #Check for an existing ADR
- 19.
- 20. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Check foran existing ADR - Someone might have decided against - The context might have changed - The decision drivers might have changed - There might be some alternatives mentioned you didn’t think of 2% 19:32
- 21.
- 22.
- 23. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Document it -It can be any kind of wiki, git, markdown files, etc - It might take time to create it before reviewing it - Formal checks happen - There should be a DoD for the proposal 2% 22:32
- 24. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Definition ofDone - Are we confident enough that this design will work? - Have we decided between at least two options, and compared them systematically? - Have we discussed among each other and with peers and come to a common view? - Have we captured the decision outcome and shared the decision record? - Do we know when to realize, review and possibly revise this decision? 2% 23:32
- 25.
- 26.
- 27. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # ADR Review -Should be a dedicated meeting - It can be done by a review board - A vote required if the decision finalized or needs some rework - Action items created and assigned to people - Socialize the decision making 2% 26:32
- 28.
- 29. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Finalize decision -The decision is already made based on the available information. - The outcome is either accepted (might superseed an earlier ADR) or rejected - Merge in the updated PR (or update the wiki) - The ADR is immutable from now on 2% 28:32
- 30. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL 2% 29:32 Idea Checkfor existing ADR Open a PR with proposed state Formal checks on PR ADR review Finalizing decision # Summary
- 31. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Useful links -https://adr.github.io/ - https://www.ozimmer.ch/practices/2023/04/05/A DRReview.html - https://github.com/thomvaill/log4brains - https://www.ozimmer.ch/practices/2020/05/22/A DDefinitionOfDone.html 2% 30:32
- 32.
- 33. 1 2 3 4 5 6 7 8 9 10 ~ ~ ~ ~ ~ ~ ~ ~ ~ presentation.md master VISUAL # Thanks foryour attention! 2% 31:32
Editor's Notes
- #4 aki már egy ideje benne van a szoftveriparban, az tudja, hogy amin dolgozunk, az jó esetben folyamatosan változik, ilyen-olyan döntések nyomán. sajnos ezek a döntések elvesznek a múltban
- #5 akkor egy kicsit az architektúráról mint olyan
- #7 nézzünk egy pár példát erre láthatjuk, hogy nem csak purely technikai dolgok vannak, láthatunk processzeket is
- #8 miért használunk Hbase-t pár százezer dokumentum tárolására? miért pull módszerrel szinkronizálgatunk két adatbázist? miért kell itt átfolynia még az adatnak, ahelyett hogy direktben onnan jönne?
- #9 valaki más már spikeolta, rákérdezett legal oldalon és kiderült, hogy jogi akadálya van
- #10 minden döntést érdemes időpontját tekintve megítélni
- #11 szerncsénkre a fentiekre van megoldás, hogy szépen összeszedjük a döntésket, azok körüli kontextust és ledokumentáljuk
- #12 az ADR gyakorlatilag egy architekturális döntés, amihez adunk egy kontextust, összeszedjük az alternatívákat, és megvizsgáljuk azokat pro-kontra, majd ez alapján döntünk
- #13 hogy is néz ez ki? az, hogy hova írjuk sokféle lehet, lehet wiki oldal, word doksik, de a legtöbben a markdown mellett voksoltak, ebből lett az úgynevezett MADR, markdown any decisions record
- #14 a markdownos implementáció közül az egyik a log4brains - github action, github pages integráció, de vannak még mások is, pl az adr-manager, ahol
- #15 láthatjuk szépen az egyes döntéseket sorban
- #16 sok tényezőtől függ, leginkább csapattól, kik a döntéshozók, stb
- #17 viszont mindenképp úgy indul, hogy látjuk, hogy bizony itt el kell döntenünk valamit, választani kell egy adatbázist, architektúrát, valami 3rd party eszközt, folyamatot stb.
- #19 viszont még mielőtt jobban belemerülnénk abba, hogy tényleges döntést hozzunk, használjuk ki az ADR log előnyeit és nézzük meg, hogy a múltban volt-e hasonló helyzet, ami befolyásolja a döntésünket, vagy éppen amit felülbírálnánk most ez jó lesz egyébként sima PR review alatt is, lehet mutogatni az ADR-re, hogy bizony itt leírtuk, hogy REST-en át megy minden inter-service kommunikáció, mi ez a WSDL itt?
- #20 ha nincs ADR, akkor bizony ez lesz a helyzet minden esetben, de lehet mégis szerencsével járunk
- #21 miért van értelme megnézni az ADR-t korábbról? lehet valaki leszavazta a dolgot, okkal.. lehet azóta változott a kontextus, például ha korábban még nem mentek át egy új CI/CD megoldásra, de most lejár valami licensz akkor bizony más lesz a kimenetel lehet az a megoldás, amit akkor használtak még olcsó volt kezdetben, de ahogy nőtt a cég és jobban használni kezdték, a licenszdíjak az egekben az elődöknek lehet olyasmi is eszébe jutott, amire nem is gondoltál volna és ha nem is marad el a döntési folyamat, hozzájárul a döntéshez
- #22 na és akkor most jön a lényeg. elkezdjük összerakni az ADR-t és nyitunk egy PR-t
- #24 példa workflow, hogy draft PR-t elkezd valaki, ránéznek mások is a csapatból, finomitgatnak rajta, ajánlásokat tesznek, mígnem eljut oda, hogy ready for review itt fontos megjegyezni, hogy bárki csinálhat ADR-t, ez nem csak az elefántcsonttoronyban üldögélő architektek kiváltsága, pont az a lényeg, hogy minél több ember benne legyen a dontésben
- #25 biztos, hogy jól körbejártuk a problémát? kivitelezhető, amit választottunk? legalább egy alternatívát felsoroltunk, ami közül döntöttünk és a kettő között volt bármiféle verseny? tegyük fel, hogy akarunk egy key-value adatbázist, egyik döntés a redis, a másik opció meg egy rabbitMQ, nyílván nem az utóbbit fogjuk erre a célra használni, tehát nem is vizsgáltunk meg két értelmes megoldást. megbeszéltük egymás közt a dolgot és nem csak hoztunk egy döntést? ami nagyon fontos, hogy olyan döntéseket hozzunk, amik számítanak, tehát tudjuk, hogy igen az implementációt, bevezetést, migrációt, stb. elkezdjük a közeljövőben
- #27 jó esetben nem így fog kinézni a dolog
- #28 lehet szinkron vagy async, lehet rá egy dedikált bizottság, de minél többen látják/részt vesznek benne, annál jobb itt eldől, hogy az adott ADR jó és ennek függvényében el lehet fogadni a döntést vagy sem vagy még nincs elég információ a döntéshez és akkor visszadobjuk, hogy dolgozzanak még rajta, itt action itemeket rendelünk egyes emberekhez, hogy xy-nak járjanak utána, stb. fontos aspektusa a dolognak, hogy ezeket a döntéseket elősegítsék, ne féljünk ettől, lássák az emberek, hogy van ilyen lehetőség és nem egy gonosz társaság vétózza meg a terveket pofára
- #29 elérkeztünk az utolsó lépéshez
- #30 itt szokott egy kis zavar lenni a fejekben, hogy igazából itt választunk, hogy most akkor mi is lesz használva itt jóváhagyunk egy döntést, nem pedig döntünk, ezt el kell választani ha sikerült dönteni, akkor véglegesíteni kell a dolgot és azt is dokumentálni
- #31 először is van egy döntési szükség, megnézzük, hogy valaki hozott-e már döntést, elfogadták-e leszavazták, mik voltak a körülmények, aztán jön az a bizonyos PR, amit lehet köpködni, itt már a döntési folyamat az alternatívák közt elkezdődik, információt gyűjtünk és hasonlók. Ezek alapján hozunk egy döntést, hogy X-et kéne használni. Ekkor jön el a review ideje, a draft státuszból átkerül proposed-ba és valahogy átnézzük. Ezt élőben egy rendes meetingen érdemes. Itt szavazásra kerül a döntés, hogy egyáltalán igen, nem, vagy tartózkodunk. Ha egyértelmű többség van, akkor lehet véglegesíteni, ha nincs, akkor még valami hiányzik, kell róla action item és a következő alkalommal ránézünk.
- #32 valaki más már spikeolta, rákérdezett legal oldalon és kiderült, hogy jogi akadálya van
- #33 valaki más már spikeolta, rákérdezett legal oldalon és kiderült, hogy jogi akadálya van
- #34 valaki más már spikeolta, rákérdezett legal oldalon és kiderült, hogy jogi akadálya van