Rekodi za Maamuzi ya Ujenzi: RFC hadi ADR

TL;DR

RFC mara nyingi inahusiana na kufikia makubaliano; ADR inarekodi makubaliano mara tu yanapofikiwa. ADRs zinaharibika kwa sababu ya kufikia makubaliano kunafanyika kwenye mazungumzo na kurekodi kunafanyika baadaye, kutoka kwenye kumbukumbu. Endesha zote mbili katika muundo mmoja:

Mapendekezo ni mada ya msingi; nguvu za muktadha ni tofauti, zinazoweza kupingwa; kila chaguo — ikiwa ni pamoja na zile zilizokataliwa — kinapata node yake mwenyewe
Raundi ya RFC ni minyororo: Maswali na Majibu ili kufafanua, Mapitio ili kupinga, Mkataba ili kupatanisha — mazungumzo ya mzunguko nne, N waandishi wa maoni = N minyororo sambamba
Rating si uamuzi: waamuzi wanapima kama ushahidi; mtu aliyepewa jina anasema hivyo — na anaandika kwa nini, hasa dhidi ya chumba
ADR ni mti: hakuna kinachorekodiwa, hivyo hakuna kinachopotea katika urekodi — export kwa repo ikiwa shirika lako linahitaji hivyo

Uamuzi ambao hakuna aliyeweza kuurejesha.

Kiongozi mpya wa teknolojia anauliza swali la busara: kwa nini kila huduma inazungumza na mfumo wa bili kupitia foleni hiyo? Kuna ADR — ADR-014, sentensi nne, iliyoandikwa miezi kumi na moja iliyopita. Muktadha: "tulihitaji uunganisho wa bili unaotegemewa." Uamuzi: "tumia foleni." Matokeo: "baadhi ya ucheleweshaji uliongezeka." Kimsingi ni rekodi. Haijibu chochote.

Ulikuwepo, hivyo unajua kile ADR-014 hakisema: mjadala wa wiki tatu katika vituo viwili vya Slack na uzi wa PR wenye hasira; chaguo la synchronous-API lililoshindwa kwa sababu ya kikomo cha kiwango ambacho tangu wakati huo kimepandishwa; pingamizi la mhandisi wa wafanyakazi ambalo lilijibiwa kwa kipimo ambacho hakuna mtu anayeweza kukipata sasa. Mjadala ulifanyika. Rekodi iliandikwa baadaye, kwa kumbukumbu, na mtu mmoja, siku ya Ijumaa.

Hii ni hali ya kushindwa ambayo imeandikwa, karibu ya ulimwengu mzima, ya mbinu nzuri kweli. Mwongozo wa AWS na hati za Microsoft za Well-Architected zote zinapendekeza ADRs — na zote zinaeleza maumivu: kuzifanya ziwe za kisasa kunachukua muda, na kuzisimamia kunakuwa ngumu kadri timu na chaguo zinavyoongezeka. Sababu ya msingi ni ya muundo: mjadala na rekodi zinakaa mahali tofauti, hivyo rekodi daima ni nakala yenye hasara. Suluhisho ni kuzifanya kuwa mahali pamoja. Pia, mbinu hii si maalum kwa uhandisi, wala hata kwa ADR. Google inahitaji hati ya muundo — tatizo, njia iliyopendekezwa, chaguzi zilizozingatiwa, faida na hasara — kuandikwa na kukaguliwa kabla ya kazi kubwa ya kiufundi kuanza, mbinu iliyowekwa katika Uhandisi wa Programu katika Google. Ni nidhamu ile ile kama ADR, inayotumika hatua moja mapema: ADR inarekodi chaguo ambalo hati ya muundo ilijadili. Zote zinashindwa kwa njia ile ile kwa sababu ile ile, na zote zinafanyiwa marekebisho kwa hatua ile ile — shikilia mjadala mahali ambapo rekodi inakaa, badala ya kuandika moja ndani ya nyingine baadaye. Soma kila hatua hapa chini kama inavyohusisha vitu vyote viwili.

Kwa nini ADRs zinaharibika

Sentensi moja kutoka kwa nyenzo za jamii ya ADR inabeba utambuzi mzima: RFC kwa kawaida inahusisha kufikia makubaliano; ADR inarekodi makubaliano mara tu yanapofikiwa. Vitu viwili, nyakati mbili — na kila kitu kati yao kinavuja. Mbadala ambazo zilikuwa "dhahiri" makosa hazirekodiwi (hadi zisipokuwa dhahiri). Pingamizi lililounda muundo wa mwisho linaishi tu kama maoni ya PR kwenye mjadala uliofungwa. Sehemu ya muktadha inaandikwa mwisho, vibaya, na yeyote aliyeshindwa katika mchezo wa si-huyu. Mikutano ambayo ilipaswa kutoa maamuzi inatoa muhtasari badala yake, na mantiki inayofanya uamuzi kuwa thabiti — kitu ambacho mnyororo wa ubora wa maamuzi unategemea — ndicho hasa ambacho uandishi wa nakala unakosa.

Unachohitaji

Majadiliano moja ya Argumentree kwa kila RFC. Ikiwa una mkusanyiko wa ADRs za markdown au nakala ya mkutano yenye maamuzi mengi, pakia — uchimbaji wa AI unageuza kuwa hoja za muundo wa pro/con zikiwa na vipande vya chanzo vilivyounganishwa, vikiwa na alama kama vilivyochimbwa ili madai yaliyoingizwa yasichukuliwe kuwa ya moja kwa moja (jinsi uchimbaji unavyofanya kazi).

Hatua 1–3: Pendekezo, muktadha, chaguzi

1Taja pendekezo kama mada kuu — uamuzi uliopendekezwa, si swali: "Tutapeleka maandiko yote ya bili kupitia foleni ya kudumu." Sentensi hii ni kichwa cha ADR ya baadaye. Kitengo: mzizi upo, sentensi moja, iliyoandikwa na mpendekezi.
2Muktadha kama hoja tofauti. Kila nguvu inayofanya uamuzi kuwa wa lazima — hitaji la kuaminika, kikomo cha kiwango cha mfumo wa bili, agizo la ukaguzi — ni hoja yake mwenyewe chini ya mzizi. Paragrafu moja ya "Muktadha" haiwezi kupingwa; mada tatu tofauti za muktadha zinaweza kila moja kuhojiwa, kuthibitishwa, au kupingwa kwa njia ya pekee. Kitovu: ≥2 hoja za muktadha, kila moja nguvu.
3Kila chaguo kina node yake mwenyewe. Foleni, API ya sambamba, kazi ya kundi — hoja za ndugu, kila moja ikiwa na watoto wake wa faida na hasara. Faida/hasara ni ya kuhusiana na mzazi, hivyo mapungufu ya chaguo yanategemea chaguo hilo, si uamuzi. Jumuisha chaguzi unazotarajia kukataa: ndugu aliye kataa ndiye anayejibu swali la mwaka ujao "kwa nini hatuku…". Kitengo: kila chaguo ambalo msomaji anaweza kuuliza kuhusu lipo.

Hatua 4–6: Mzunguko wa RFC unaoacha rekodi

Sasa mzunguko wa mapitio — kawaida sehemu inayosambaa katika mazungumzo, maoni na korido. Hapa inafanyika kama aina tatu za ubadilishanaji wa muundo, kila moja ikiwa mazungumzo ya hatua nne kati ya mchapishaji na mwandishi wa chaguo:

Mnyororo wa maswali na majibu — fafanua

"Nini kinatokea kwa wateja wa synchronous waliopo?" Mwandishi wa chaguo anajibu, mreviewer anauliza tena, mwandishi anajibu tena — imekamilika. Hakuna chaguo kinachopaswa kubeba swali lisilojibiwa katika uamuzi.

Kikundi cha mapitio — kitu

Mhakiki anapitia chaguo kama kisicho na msingi; mwandishi anajibu; ufuatiliaji; jibu. N wahakiki = N mnyororo sambamba kwenye chaguo moja — kila pingamizi ni ubadilishanaji wake mwenyewe unaoweza kutambulika, si maoni yaliyopotea katika uzi wa pamoja.

Mnyororo wa makubaliano — pata suluhu

Makundi mawili yanagawanyika? Moja inapendekeza chaguo la kati kwa mwandishi mwingine. Ikiwa inatatuliwa, unakuwa na node mpya ya chaguo. Ikiwa haijatolewa, mnyororo ulio kamilika ni rekodi kwamba ulijaribiwa — ambayo inathaminiwa karibu kama hiyo.

Imekamilika ≠ imekubaliana

Mnyororo unaofikia ukamilifu unamaanisha kwamba ubadilishanaji umefanyika — swali lililoulizwa na kujibiwa mara mbili — si kwamba pande hizo zilikubaliana. Hifadhi tofauti hiyo; itakuwa na umuhimu.

Hatua ya 7: Kuamua — na kile kiwango siyo

Wafanya maamuzi wanapima chaguzi: kila moja imewekwa alama ya rating. Usambazaji ni ushahidi halisi — ambapo chumba kilikuwa, kwenye rekodi, kabla ya wito. Lakini rating siyo uamuzi. Binadamu aliyepewa jina bado anafanya uamuzi, na ikiwa wito unakwenda kinyume na usambazaji, node ya uamuzi ndiyo mahali ambapo hilo linaelezewa. (Nani huyo binadamu aliyepewa jina anapaswa kuwa, na jinsi ya kupewa jukumu kabla ya mjadala badala ya baada, ni nidhamu yake mwenyewe — angalia mafunzo ya haki za maamuzi.)

Swali kwa timu yako

Nani aliamua wito wako wa mwisho wa usanifu — na unaweza kuthibitisha? Si nani aliyekuwa kwenye mkutano: ni nani aliyemiliki uamuzi huo, na wapi maelezo yao yameandikwa?

Hatua 8–9: ADR ambayo hukuhitaji kuandika

Hapa kuna malipo. Rekodi sio hati unayoandika baadaye — ni node ya chaguo lililochaguliwa pamoja na kila kitu kilichounganishwa nacho: hoja za muktadha (Muktadha), ndugu waliokataliwa (Chaguzi Zilizozingatiwa), minyororo iliyokamilika (majadiliano, na waandishi), viwango (mahali chumba kilipokuwa), na hoja ya uamuzi pamoja na mantiki yake (Uamuzi). Hakuna kinachorekodiwa, hivyo hakuna kinachopotea katika urekebishaji.

1Rekodi matokeo unayokubali. Hasara zinazojulikana — ucheleweshaji ulioongezeka, mzigo wa kiutendaji wa foleni — zinaendelea kama watoto wa chaguo lililochaguliwa, zinazotambuliwa na mamuzi. Kuandika chini ni kile kinachofanya iwe uamuzi badala ya upendeleo. Kitovu: ≥1 matokeo yaliyokubaliwa kwenye rekodi.
2Export ikiwa shirika lako linahitaji ADRs zinazofuatiliwa na repo. Wengi wanahitaji, kwa usahihi — ADR ya markdown iliyo karibu na msimbo inabaki kuwa kipande cha uthibitisho wa kufuata. Andika muhtasari wa sehemu nne kutoka kwenye mti (dakika tano, si Ijumaa), ungana tena na mjadala kwa ajili ya mjadala kamili. Kitovu: ADR ya repo inarejelea mti; mti unashikilia mantiki.

Kubaliana na kutekeleza, kwenye rekodi

Mfumo ambao Amazon ilifanya kuwa maarufu — kukatisha na kujitolea — una tatizo la ueleweka: mtu yeyote anajua vipi baadaye kwamba kukatishwa ilikuwa halisi, kusikilizwa, na kujibiwa, badala ya kupuuziliwa mbali? Jibu linapatikana katika mitambo ya mnyororo. Mnyororo wa Mapitio uliofanya mizunguko yake minne kamili na kukamilika bila makubaliano ndivyo hasa risiti: pingamizi lilitolewa, kujibiwa, kulazimishwa, na kujibiwa tena, kwenye rekodi, kabla ya mpinzani kujitolea. Mpinzani ameandikwa kama aliyesikilizwa — ambayo ndiyo inafanya kujitolea baadaye kuwa na maana badala ya kuwa mtiifu tu.

Usisome kukamilika kama makubaliano.

Imekamilika inamaanisha ubadilishanaji umemalizika, si kwamba mtu yeyote alibadilisha mawazo yake. Ikiwa unaripoti kukamilika kwa mnyororo kama makubaliano, utaunda makubaliano ya uongo na kuharibu uaminifu ambao mfumo huu upo ili kujenga. Tafsiri ya kweli: ulitafutwa, ulijibu, bado unapingana, umejizatiti hata hivyo — ukweli wote wanne unaonekana.

Hatua ya 10: Kuweka badala bila kufuta

Maamuzi yana umri. Wakati kikomo cha kiwango ambacho kilikufa chaguo la sambamba kinapoinuliwa, hatua sahihi ni uamuzi mpya ambao unarejelea ule unaobadilishwa — hoja mpya inayohusishwa na node ya ADR-014, ikieleza kilichobadilika. Uamuzi wa zamani unabaki kuwa rahisi kusomeka; mantiki yake ndiyo hasa sababu uamuzi mpya unajua kinachobatilishwa.

Pengo moja la uaminifu ambalo linapaswa kudhibitiwa wazi: hakuna uwanja wa hali ya ADR uliojengwa ndani. Ilipendekezwa / ilikubaliwa / iliyoondolewa si hali ya daraja la kwanza kwenye hoja — kuondolewa kunatolewa kwa kuunganisha, na desturi ni yako kudumisha. Ieleze katika makubaliano ya kazi ya timu yako badala ya kudhani kuwa bidhaa inatekeleza.

Mipaka ya uaminifu

✗Hii haisitishi ADRs katika repo yako ikiwa shirika lako linahitaji ziwe na udhibiti wa toleo karibu na msimbo. Export na commit muhtasari; tumia mti kwa sehemu ambayo markdown haifanyi vizuri — mjadala.
✗Hakuna uwanja wa hali ya ADR. Ilipendekezwa/kukubaliwa/kubadilishwa ni kanuni ya kuunganisha unayoendeleza, si kitu ambacho bidhaa inatekeleza.
✗Minyororo ni mizunguko minne. Kutokubaliana kwa kina katika usanifu kutahitaji simu; minyororo ni rekodi ya kile ambacho tayari kilijaribiwa kabla yake.
✗Ratings ni thamani moja iliyo na lebo, si alama za vigezo vingi zenye uzito.
✗Haifanyi mtu yeyote aandike muktadha mzuri. Muundo unashusha gharama ya rekodi nzuri; haupeani hukumu.

Masomo ya vitendo

✓RFC moja, mjadala mmoja. Pingamizi mti mkubwa unaofunika usanifu wa robo nzima — viungo vya supersession vinahusisha maamuzi bora zaidi kuliko kuingiza.
✓Mbegu kutoka kwa kile kilichopo. Nakala yenye maamuzi mengi au folda yako ya zamani ya ADR, iliyochukuliwa, inatoa mjadala mwanzo mzuri — ikitambulishwa kama iliyoagizwa, hivyo hoja za moja kwa moja zinabaki tofauti.
✓Weka majina ya waandishi wa maoni kwenye minyororo yao na uyache hapo. Utoaji wa majina ni uwajibikaji; pingamizi za usanifu zisizojulikana zinakuwa hadithi za kale.
✓Sehemu ya matokeo ni ya muamuzi, si ya mtu mwingine yeyote. Hasara zilizokubaliwa zilizoandikwa na mtu aliyekubali zinabeba uzito tofauti na onyo la mhariri.

ADR-014, toleo linalojibu

Rudi kwenye swali la kiongozi mpya wa teknolojia. Katika toleo lililojengwa upya, ADR-014 ni node: uamuzi wa foleni na sababu zake, nguvu tatu za muktadha (moja sasa imepitwa na wakati — kwa wazi), ndugu wa API wa synchronous aliyepewa kibali ambaye jina lake la hatari linaonyesha kikomo cha zamani, minyororo minne ya Mapitio iliyokamilika ikiwa ni pamoja na ya mhandisi wa wafanyakazi, na kipimo kilichounganishwa kama ushahidi. Kiongozi wa teknolojia anasoma kwa dakika kumi, anaona kikomo cha kiwango kimebadilika, na kufungua pendekezo linalofuatilia lililounganishwa na node ya zamani. Hakuna anayeangalia Slack. Hiyo ndiyo ahadi nzima: minyororo inafikia makubaliano, mti unarekodi, na rekodi inajibu maswali ambayo hukujua yangekuwa yanoulizwa.

InahusuIntelligence ya Mkutano

Vyanzo na kusoma zaidi

Nygard, M. (2011). Kurekodi Maamuzi ya Architektura. Blogu ya Cognitect.Insha ambayo ilifanya ADRs kuwa maarufu: muktadha, uamuzi, matokeo, ilihifadhiwa na kanuni.
Mwongozo wa AWS — Rekodi za maamuzi ya usanifu.Muundo wa RFC-vs-ADR na maumivu ya matengenezo yaliyorekodiwa ambayo mafunzo haya yapo ili kuyatatua.
Microsoft Azure Well-Architected Framework — Rekodi za maamuzi ya usanifu.Mazoezi ya ADR katika muktadha wa ukaguzi wa Well-Architected.
Shirika la ADR GitHub (adr.github.io).Mifano, zana na desturi zilizokusanywa na jamii — ikiwa ni pamoja na mazoea ya uwanja wa hadhi ambayo mafunzo haya yanaonyesha kwa kuunganisha.

Maswali Yanayoulizwa Mara kwa Mara

Nini tofauti kati ya RFC na ADR?

RFC (ombile la maoni) ni mchakato wa kufikia makubaliano: pendekezo linazungushwa, mbadala zinajadiliwa, pingamizi zinainuliwa na kujibiwa. ADR (rekodi ya uamuzi wa usanifu) inarekodi makubaliano yaliyofikiwa: muktadha, chaguzi zilizozingatiwa, uamuzi, matokeo, hali. Njia ya kushindwa ya kuendesha hizi kama vitu tofauti ni kwamba kila kitu kati yao kinavuja — mjadala unaishi katika mazungumzo na maoni ya PR wakati rekodi inaandikwa baadaye kutoka kwenye kumbukumbu. Kuendesha RFC kama mti wa hoja ulio na muundo kunafanya ADR itoke katika mjadala wenyewe: hakuna kinachorekodiwa, hivyo hakuna kinachopotea katika uandishi.

Kwa nini ADRs zinakuwa za zamani au kuacha kuandikwa?

Kwa sababu kuandika hizo ni kazi ya uandishi. Mantiki halisi inafanyika katika nyuzi za Slack, maoni ya mapitio na mikutano; baadaye mtu mmoja anajenga sehemu ya Muktadha kutoka kwenye kumbukumbu, mara nyingi kwa ufupi na mwishowe. Mwongozo wa AWS na Microsoft unasisitiza maumivu: ADRs zinachukua muda kuandika na kusasisha, na usimamizi unakuwa mgumu kadri maamuzi yanavyoongezeka. Timu haziachi kuamini katika ADRs — wanacha kulipa kodi ya uandishi. Kufanya mjadala na rekodi kuwa muundo mmoja kunondoa kodi hiyo.

Jinsi gani unafanya mzunguko wa mapitio ya RFC na rekodi?

Hatua tatu zilizopangwa, kila moja ikiwa ni mazungumzo ya mzunguko nne na mwandishi wa chaguo. Mnyororo wa maswali na majibu kwa ufafanuzi: swali, jibu, ufuatiliaji, jibu. Mnyororo wa mapitio kwa upinzani: tathmini, jibu, ufuatiliaji, jibu — na waandishi N wakifungua mnyororo N wa sambamba kwenye chaguo moja badala ya thread moja iliyoshirikiwa, hivyo kila upinzani unabaki na uhusiano na kujibiwa. Mnyororo wa makubaliano kwa migawanyiko: upande mmoja unapendekeza nafasi ya kati kwa mwingine, na iwe inatatua au la, mnyororo ulio kamilika unarekodi kwamba ulijaribiwa. Kituo cha ukaguzi kabla ya kuamua: hakuna chaguo linalobeba swali lisilojibiwa, na kila upinzani wa maana upo kama mnyororo ulio kamilika.

Je, 'kukataa na kujitolea' kunavyofanya kazi na rekodi za maamuzi?

Mifumo ya mnyororo inafanya iweze kusomeka. Mnyororo wa mapitio unaotembea kwa njia yake yote — pingamizi, jibu, ufuatiliaji, jibu — na kukamilika bila makubaliano ni risiti kwamba tofauti ilikuwa halisi, ilisikiwa na kujibiwa kabla ya tofauti kujiunga. Kwa umuhimu, kukamilika hakumaanishi kukubaliana: inamaanisha kubadilishana kumalizika. Kutoa taarifa ya kukamilika kama makubaliano kunazalisha makubaliano ya uwongo na kuharibu thamani ya mfumo. Rekodi ya uaminifu inaonyesha ukweli wanne kwa wakati mmoja: ilishauriwa, ilijibiwa, bado inapingana, ilijitolea hata hivyo — ambayo ndiyo hasa inafanya kujitolea baada ya kutofautiana kuwa na mantiki.

Je, rekodi za maamuzi zinapaswa kuchukua nafasi ya ADRs katika hifadhi ya msimbo?

Hapana — na mafunzo haya yanaeleza hivyo wazi. Ikiwa shirika lako linahitaji ADRs zenye udhibiti wa toleo karibu na msimbo (mengi yanahitaji hivyo, kwa usahihi, kwa ajili ya kufuata sheria na upatikanaji wa mtandaoni), zishike: andika muhtasari wa sehemu nne wa markdown kutoka kwenye mti ndani ya dakika tano na uunganishe tena na majadiliano. Ugawaji wa kazi ni safi: ADR ya repo ni kipande cha kudumu cha kufuata sheria; mti unashikilia kile ambacho markdown haifanyi vizuri — mjadala wa moja kwa moja, chaguo zilizokataliwa na sababu zao, pingamizi na majibu yao, na viwango.

Je, unamwonyesha vipi ADR kama ilivyopitwa na wakati?

Kwa kawaida, si kwa uwanja — na inafaa kuwa mkweli kwamba hakuna hali iliyopendekezwa/imekubaliwa/imeondolewa iliyojengwa ndani ya hoja. Onyesha kubadilishwa kwa mfano kwa kuunda uamuzi mpya kama hoja yake mwenyewe inayohusishwa na ile inayobadilisha, ikieleza kilichobadilika (kikomo cha kiwango kilichoinuliwa, hitaji jipya). Uamuzi wa zamani unabaki kuwa rahisi kusomeka — kuufuta kutaharibu hasa mantiki ambayo uamuzi mpya unahitaji kurejelea. Eleza kawaida hiyo katika makubaliano ya kazi ya timu yako ili ihifadhiwe kwa makusudi.

Acha kuandika maamuzi. Anza kuyahifadhi.

Endesha RFC yako inayofuata kama mti: chaguzi zikiwa na sababu zao, pingamizi kama mchaini ya majibu, na ADR inayojandika yenyewe.

Anza Jaribio la Bure la Siku 14

Hakuna kadi ya mkopo inayohitajika

Kutoka RFC hadi ADR: Kufikia Uamuzi na Kuhifadhi Mantiki