Rubutun Yanke Shawara na Gine-gine: RFC zuwa ADR

TL;DR

RFC yawanci yana da alaƙa da cimma yarjejeniya; ADR yana rubuta yarjejeniyar da aka cimma bayan haka. ADRs suna lalacewa saboda cimma yarjejeniyar yana faruwa a cikin tattaunawa kuma rubutun yana faruwa daga baya, daga tunani. Gudanar da duka a cikin tsari guda:

Shawarwarin na asali ne; karfin yanayi suna daban, ana iya kalubalantar hujjojin; kowanne zaɓi — ciki har da waɗanda aka ƙi — yana samun nasa node.
Jerin RFC shine sarkar: Tambayoyi da Amsoshi don bayyana, Bita don kin amincewa, Sulhu don daidaitawa — tattaunawa hudu, N masu bita = N sarkar jere.
Kimanta ba ita ce hukuncin ba: masu yanke hukunci suna kimanta a matsayin shaida; wani mutum da aka ambata yana kiran ta — kuma yana rubuta dalilin, musamman a kan dakin.
ADR itace ne: babu abin da aka rubuta, don haka babu abin da aka rasa a cikin rubutawa — fitar da shi zuwa repo idan kungiyar ku ta bukata

Shawarar da ba wanda ya iya sake gina ta

Sabon jagoran fasaha yana tambaya mai ma'ana: me ya sa kowace sabis ke magana da tsarin biyan kudi ta wannan jeri? Akwai ADR — ADR-014, jimloli hudu, an rubuta su watanni guda sha ɗaya da suka wuce. Mahallin: "muna buƙatar haɗin biyan kudi mai inganci." Shawara: "a yi amfani da jeri." Sakamako: "wasu ƙarin jinkiri." A cikin fasaha, wannan rikodi ne. Ba ya bayar da amsa ga komai.

Ka kasance a can, don haka ka san abin da ADR-014 ba ya faɗi: muhawarar makonni uku a cikin tashoshin Slack guda biyu da kuma tattaunawar PR mai zafi; zaɓin synchronous-API da ya sha kaye saboda iyakar ƙima da aka ɗaga tun daga lokacin; kin amincewar injiniyan ma'aikata da aka amsa da wani gwaji da babu wanda zai iya samun sa yanzu. An yi muhawarar. An rubuta tarihin daga baya, daga ƙwaƙwalwa, ta mutum guda, a ranar Juma'a.

Wannan shine tsarin gazawa da aka rubuta, wanda ya shafi kusan dukkanin hanyoyin aiki masu kyau. Jagororin da AWS ya bayar da kuma takardun Well-Architected na Microsoft duka suna ba da shawarar ADRs — kuma duka suna lura da wahalar: sabunta su yana daukar lokaci, kuma gudanar da su yana zama mai wahala yayin da kungiyoyi da zaɓuɓɓuka ke karuwa. Babban dalilin shine tsarin: tattaunawa da rajistar suna zaune a wurare daban-daban, don haka rajistar koyaushe tana zama fassarar da ba ta cika ba. Maganin shine a sa su zama wuri guda. Hakanan ba wannan aikin yana da alaƙa da injiniya ba, ko ma ADR. Google yana buƙatar takardar zane — matsala, hanyar da aka ba da shawara, zaɓuɓɓukan da aka yi la’akari da su, da musayar — wanda aka rubuta kuma aka duba kafin a fara aikin fasaha mai mahimmanci, wani aiki da aka bayyana a cikin Injin Zane na Software a Google. Wannan shine irin wannan tsari kamar ADR, wanda aka yi amfani da shi a mataki ɗaya kafin: ADR yana rubuta zaɓin da takardar zane ta yi muhawara akai. Duka suna fuskantar gazawa iri ɗaya saboda dalili ɗaya, kuma duka suna gyarawa ta hanyar motsi ɗaya — riƙe muhawarar a inda rajistar take, maimakon fassara ɗaya cikin ɗayan bayan haka. Karanta kowane mataki a ƙasa kamar yana rufe duka abubuwan.

Me yasa ADRs ke lalacewa

Wani jumla daga kayan aikin al'umma ta ADR tana dauke da dukkanin ganewar: RFC yawanci yana da alaƙa da cimma yarjejeniya; ADR yana rubuta yarjejeniyar da aka cimma. Abubuwa guda biyu, lokuta guda biyu — kuma komai tsakanin su yana zubar. Zabin da aka "gane" a matsayin kuskure ba a rubuta su ba (har sai sun daina zama bayyananne). Kwatancen da ya tsara ƙirar ƙarshe yana rayuwa kawai a matsayin sharhi na PR a kan wani zaren da aka rufe. Sashe na mahallin yana rubutawa a ƙarshe, mafi muni, daga wanda ya rasa wasan ba-ita. Taron da ya kamata ya haifar da yanke shawara yana haifar da taƙaitaccen bayani maimakon haka, kuma dalilin da ke sa yanke shawara ta zama mai ɗorewa — abin da dukkanin sarkar ingancin yanke shawara ke dogara akai — shine abin da rubutun ke zubar.

Abin da kake bukata

Tattaunawa guda ɗaya ta Argumentree a kowanne RFC. Idan kana da tarin markdown ADRs ko takardar shawarwari mai nauyi, ka loda shi — fitar da AI yana canza shi zuwa hujjoji masu tsari na goyon baya/kiyaye tare da rubutun tushe da aka haɗa, an yi masa alama a matsayin an fitar da shi don a guji kuskuren ɗaukar ikirarin da aka shigo da su a matsayin na ainihi (yadda fitarwa ke aiki).

Mataki 1–3: Shawarar, yanayin, zaɓuɓɓuka

1Fadi shawarar a matsayin asalin ikirari — shawarar da aka gabatar, ba tambaya ba: "Za mu tura duk rubutun biyan kuɗi ta hanyar jeri mai ɗorewa." Wannan jumla ita ce taken ADR na gaba. Tsayawa: asali yana nan, jumla guda, wanda mai gabatarwa ya rubuta.
2Mahallin a matsayin hujjoji masu zaman kansu. Kowanne karfi da ke sa shawarar ta zama dole — bukatar amintacce, iyakar farashin tsarin biyan kudi, umarnin bincike — hujja ce ta kanta a ƙarƙashin tushen. Ana iya kalubalantar sakin layi guda "Mahalli" guda ɗaya; ana iya tambayar, tabbatarwa, ko rushe hujjoji guda uku masu zaman kansu na mahalli kowane ɗaya. Tsayawa: ≥2 hujjojin mahalli, kowanne karfi ɗaya.
3Kowane zaɓi yana da node ɗinsa. Jirgin, API mai jituwa, aikin batch — hujjojin 'yan uwa, kowanne tare da 'ya'yan pro da con na kansa. Pro/con yana danganta da uwa, don haka rashin fa'idodin zaɓi yana rataye daga wannan zaɓin, ba daga shawarar ba. Hada da zaɓuɓɓukan da kuke tsammanin za ku ƙi: 'yan uwa da aka ƙi su ne ke amsa tambayar shekara mai zuwa "me ya sa ba mu yi kawai…". Checkpoint: kowanne zaɓi da mai karatu zai iya tambaya yana nan.

Mataki na 4–6: Zoben RFC da ke barin tarihin

Yanzu zagayen bita — a al'ada wannan shine ɓangaren da ke yawo a cikin tattaunawa, sharhi da hanyoyi. A nan yana gudana a matsayin nau'i uku na musayar tsari, kowanne shine tattaunawa mai juyawa hudu tsakanin mai bita da marubucin zaɓin:

Tambayoyi da Amsoshi — bayyana

"Me zai faru da abokan ciniki masu jituwa da suke akwai?" Marubucin zaɓin ya amsa, mai duba ya ci gaba, marubucin ya amsa kuma — an kammala. Babu zaɓi da ya kamata ya ɗauki tambaya da ba a amsa ba cikin shawarar.

Bita sarkar — abu

Mai duba yana kimanta wani zaɓi a matsayin mara inganci; marubucin ya amsa; ci gaba; amsa. N masu duba = N jerin gwanon jere akan wannan zaɓin — kowanne korafi yana da musayar da za a iya danganta masa, ba wani sharhi da aka rasa a cikin jeren da aka raba ba.

Tsarin sulhu — daidaita

Kungiyoyi biyu sun rabu? Daya na ba da shawarar zaɓin tsakiya ga wani marubuci. Idan an warware shi, kuna da sabon node na zaɓi. Idan ba a warware ba, jerin da aka kammala shine shaidar an yi ƙoƙarin — wanda yake da kimar kusan haka.

An kammala ≠ an yarda

Wani sarkar da ta kai cikakke na nufin musayar ta yi tafiya — tambaya an yi ta kuma an amsa ta sau biyu — ba cewa bangarorin sun yarda ba. Ka kiyaye wannan bambanci; yana da mahimmanci yanzu.

Mataki na 7: Yanke shawara — da abin da kimar ba ta kasance ba

Masu yanke shawara suna kimanta zaɓuɓɓuka: kowanne yana da alamar kimantawa. Rarraba wannan gaskiya ce ta shaidar — inda dakin ya tsaya, a cikin rajista, kafin kiran. Amma kimantawar ba ita ce shawarar ba. Wani mutum mai suna ne ke yanke shawara, kuma idan kiran ya tafi akasin rarrabawar, wurin yanke shawara shine inda za a bayyana hakan. (Wane mutum ne ya kamata ya zama, da yadda za a ba da wannan rawar kafin muhawara maimakon bayan, yana da nasa ilimin — duba darasin hakkin yanke shawara.)

Tambayar ga ƙungiyarku

Waye ya yanke shawarar kiran ku na ƙarshe na gine-gine — kuma za ku iya tabbatar da hakan? Ba wanda ya kasance a taron ba: wanene ya mallaki shawarar, kuma ina aka rubuta dalilinsa?

Mataki 8–9: ADR da ba ka bukatar rubutawa

Ga sakamakon. Rikodin ba takardun da za ka rubuta bayan haka ba — yana da node na zaɓin da aka zaɓa tare da duk abin da aka haɗa da shi: hujjojin mahallin (Context), 'yan uwa da aka ƙi (Options Considered), jerin da aka kammala (tattaunawar, tare da marubuta), kimantawa (inda dakin ya tsaya), da hujjar shawara tare da dalilinta (Decision). Babu wani abu da aka rubuta, don haka babu wani abu da aka rasa a cikin rubutawa.

1Rubuta sakamakon da kake karɓa. Sanannun rashin fa'ida — ƙarin jinkiri, nauyin aiki na jerin — suna ci gaba a matsayin 'ya'yan zaɓin da aka zaɓa, wanda mai yanke shawara ya amince da su. Rubuta su yana sa ya zama shawara maimakon zaɓi. Tsayawa: ≥1 sakamako da aka karɓa a cikin rajista.
2Fitar da idan ƙungiyarku tana buƙatar ADRs da aka bi ta hanyar repo. Yawancin suna buƙata, daidai — ADR na markdown kusa da lambar yana zama kayan aikin bin doka. Rubuta taƙaitaccen sashi hudu daga itacen (mintuna biyar, ba ranar Juma'a ba), haɗa zuwa tattaunawar don cikakken muhawara. Tsayawa: ADR na repo yana ambaton itacen; itacen yana riƙe da dalilin.

Kada ku yarda amma ku yi alkawari, a cikin rajista

Tsarin da Amazon ta shahara — sabani da kuma yarda — yana da matsala ta fahimta: ta yaya wani zai san daga baya cewa sabanin ya kasance na gaskiya, an ji, kuma an amsa, maimakon a tura shi? Amsar tana cikin tsarin sarkar. Sarkar Bita da ta gudanar da juyin guda hudu kuma ta kammala ba tare da yarda ba ita ce takardar shaidar: an yi korafi, an amsa, an matsa, kuma an amsa sake, a cikin rajista, kafin mai sabani ya yarda. An rubuta mai sabani a matsayin wanda aka ji — wanda shine abin da ke sa yarda daga baya ya zama mai ma'ana maimakon kawai bin doka.

Kada ku karanta kammala a matsayin jituwa

Gama yana nufin musayar ta ƙare, ba cewa wani ya canza ra'ayi ba. Idan ka bayar da rahoton kammala sarkar a matsayin yarjejeniya, za ka ƙirƙiri ƙarya na jituwa kuma ka ƙone amincewar da tsarin ke akwai don gina. Karatun gaskiya: an tuntube, an amsa, har yanzu an ki, an yi alkawari duk da haka — dukkanin hujjoji hudu suna bayyana.

Mataki na 10: Canza ba tare da goge ba

Shawarar shekaru. Lokacin da aka ƙara iyakar ƙimar da ta kashe zaɓin haɗin gwiwa, matakin da ya dace shine sabon shawara da ke nuni da wanda aka maye gurbinsa — sabon hujja da aka haɗa da node na ADR-014, tana bayyana abin da ya canza. Tsohuwar shawarar tana nan a karanta; dalilin ta shine ainihin dalilin da yasa sabon shawarar ke sanin abin da yake juyawa.

Gaba ɗaya mai gaskiya guda ɗaya da za a kula da ita a fili: babu filin matsayin ADR da aka gina a ciki. An ba da shawara / an karɓa / an maye gurbinsa ba wani babban hali bane a kan hujja — maye gurbinsa ana samunsa ta hanyar haɗawa, kuma al'adar tana tare da ku don kula da ita. Faɗa a cikin yarjejeniyar aikin ƙungiyarku maimakon tsammanin samfurin yana tilasta shi.

Gaskiya iyakoki

✗Wannan ba ya maye gurbin ADRs a cikin repo dinka idan kungiyar ka tana bukatar su a cikin tsarin version tare da lambar. Fitar da kuma yi wa taƙaitaccen bayani; yi amfani da itacen don ɓangaren da markdown ba ya yi kyau a ciki — muhawara.
✗Babu filin matsayin ADR. An ba da shawara/anjin/da aka maye gurbin wani tsarin haɗi ne da kuke kula da shi, ba wani abu da samfurin ke tilasta ba.
✗Waya guda hudu ne. Babban rashin jituwa na gine-gine zai bukaci kira; waya ita ce rajistar abin da aka riga aka gwada kafin ta.
✗Kimantawa suna darajar guda ɗaya mai alama, ba nauyin ƙididdiga da yawa ba.
✗Ba ya sa kowa ya rubuta kyakkyawan yanayi. Tsarin yana rage farashin kyakkyawan rikodi; ba ya bayar da hukunci.

Darussan aikace-aikace

✓RFC guda, tattaunawa guda. Ka yi watsi da babban itacen da ke rufe dukkan tsarin yanki — hanyoyin supersession suna haɗa yanke shawara fiye da yadda gina gina ke yi.
✓Tsaba daga abin da ke akwai. Wani takardar shaidar da ke dauke da yawan yanke shawara ko tsohon fayil ɗin ADR naka, wanda aka fitar, yana ba da tattaunawa wani farawa mai kyau — an yi masa lakabi a matsayin wanda aka shigo da shi, don haka hujjojin da ke gudana suna kasancewa masu bambanta.
✓Saka sunayen masu duba a kan zaren su kuma ku bar su a can. Bayanin shine alhakin; korafe-korafen gine-gine marasa suna sunan suna zama labarai.
✓Bangaren sakamakon shine na mai yanke hukunci, ba na wani ba. Rashin amfanin da aka yarda da su wanda mutum ya yarda da su suna da nauyi daban da gargadin mai duba.

ADR-014, sigar da ke amsa

Komawa ga tambayar sabon jagoran fasaha. A cikin sabon sigar da aka gina, ADR-014 wani node ne: shawarar jerin tare da dalilinta, karfi uku na mahallin (daya yanzu ya tsufa — a fili), wani dan'uwansa na API mai jituwa da aka ki yarda da shi wanda sunan gazawarsa ya ambaci tsohon iyakar kudi, jerin Bita hudu da suka kammala ciki har da na injiniyan ma'aikata, da kuma ma'aunin da aka haɗa a matsayin shaida. Jagoran fasaha yana karanta na tsawon minti goma, yana ganin an canza iyakar kudi, kuma yana buɗe wani sabon shawarwari da aka haɗa da tsohon node. Babu wanda ya bincika Slack. Wannan shine dukkan alkawarin: jerin sun kai ga yarjejeniya, itacen yana rubuta shi — kuma rajistar tana amsa tambayoyin da ba ka san za a yi musu ba.

Ya shafiHankalin Taro

Hanyoyin da za a samu karin bayani

Nygard, M. (2011). Rubuta Shawarwarin Tsarin Gine-gine. Blog na Cognitect.Rubutun da ya shahara game da ADRs: mahallin, hukunci, sakamako, ya kasance tare da lambar.
AWS Jagorar Shawara — Rikodin yanke shawara na gine-gine.Tsarin RFC-vs-ADR da kuma wahalar kula da aka rubuta wannan koyarwar yana nan don gyara.
Microsoft Azure Well-Architected Framework — Rikodin shawarar gine-gine.Aikin ADR a cikin mahallin bita na Well-Architected.
Kungiyar ADR GitHub (adr.github.io).Tsarukan, kayan aiki da al'adun da al'umma ta tara — ciki har da aikin filin matsayin da wannan koyarwar ke kwaikwayo ta hanyar haɗawa.

Tambayoyi da ake yawan yi

Menene bambanci tsakanin RFC da ADR?

RFC (buƙatar ra'ayi) shine tsarin cimma yarjejeniya: ana yawo da shawara, ana jayayya kan zaɓuɓɓuka, ana kawo ƙorafe-ƙorafe da amsawa. ADR (rikodin shawarar gine-gine) yana rubuta yarjejeniyar da aka cimma: mahallin, zaɓuɓɓukan da aka yi la'akari da su, shawara, sakamako, matsayin. Hanyar gazawa ta gudanar da su a matsayin abubuwa masu zaman kansu shine cewa komai a tsakaninsu yana zubar — tattaunawar tana ci gaba a cikin tattaunawa da sharhin PR yayin da aka rubuta rikodin daga ƙwaƙwalwa bayan haka. Gudanar da RFC a matsayin tsari na jayayya yana sa ADR ya fadi daga tattaunawar kanta: babu abin da aka rubuta, don haka babu abin da aka rasa a cikin rubutu.

Me yasa ADRs ke zama tsofaffi ko kuma su daina rubutawa?

Saboda rubuta su aikin rubutawa ne. Gaskiyar tunani tana faruwa a cikin tattaunawar Slack, sharhin bita da tarurruka; bayan haka, mutum guda yana sake gina sashen Mahallin daga tunani, yawanci a taƙaice kuma a ƙarshe. Jagororin AWS da Microsoft suna nuna wahalar: ADRs suna ɗaukar lokaci don rubutawa da sabuntawa, kuma gudanarwa yana zama mai wahala yayin da yanke shawara ke ƙaruwa. Kungiyoyi ba sa daina yarda da ADRs — suna daina biyan harajin rubutawa. Yin muhawara da rikodin a cikin tsarin guda yana cire harajin.

Ta yaya za ku gudanar da zagaye na duba RFC tare da rikodi?

Hanyoyi guda uku masu tsari, kowanne yana da tattaunawa mai juyawa hudu tare da marubucin zaɓin. Tsarukan tambaya da amsa don karin bayani: tambaya, amsa, ci gaba, amsa. Tsarukan bita don ƙin yarda: kimantawa, amsa, ci gaba, amsa — tare da N masu bita suna buɗe N hanyoyi masu zaman kansu akan zaɓin guda ɗaya maimakon jigo ɗaya, don haka kowanne ƙin yarda yana da alaƙa da amsa. Tsarukan sulhu don rarrabewa: ɓangare guda yana ba da shawarar matsayi na tsakiya ga ɗayan, kuma ko ya warware ko a'a, an rubuta cewa an yi ƙoƙarin kammala tsarukan. Tashar tantancewa kafin yanke shawara: babu zaɓi da ke ɗauke da tambaya marar amsa, kuma kowanne ƙin yarda mai ma'ana yana wanzuwa a matsayin tsari da aka kammala.

Yaya 'kin yarda da kuma sadaukar da kai' ke aiki tare da rikodin yanke shawara?

Hanyoyin sarkar suna sa ya zama mai karantawa. Sarkar Bita da ke gudana cikin cikakken tsari — korafi, amsa, ci gaba, amsa — kuma ta kammala ba tare da yarjejeniya ba shine shaidar cewa rashin jituwa ya kasance na gaske, an ji kuma an amsa kafin wanda ya nuna rashin jituwa ya yi alkawari. Muhimmanci, kammala ba yana nufin an yarda ba: yana nufin musayar ta kammala. Bayar da kammala a matsayin yarjejeniya yana haifar da yarjejeniya ta karya kuma yana lalata darajar tsarin. Rajistar gaskiya tana nuna gaskiya hudu a lokaci guda: an tuntuba, an amsa, har yanzu an ki, an yi alkawari duk da haka — wanda shine ainihin abin da ke sa alkawari bayan rashin jituwa ya zama mai ma'ana.

Shin rikodin yanke shawara ya kamata ya maye gurbin ADRs a cikin ajiyar lambar?

A'a — kuma wannan koyarwar ta bayyana hakan a fili. Idan ƙungiyarku tana buƙatar ADRs masu sarrafa sigar a gefen lambar (da yawa suna buƙata, daidai, don bin doka da samun damar offline), ku riƙe su: ku rubuta taƙaitaccen markdown na sassa hudu daga itacen cikin mintuna biyar ku haɗa shi da tattaunawar. Rarraba aikin yana da tsabta: ADR na repo shine kayan aikin bin doka mai ɗorewa; itacen yana riƙe abin da markdown ba shi da kyau — muhawara mai rai, zaɓuɓɓukan da aka ƙi tare da dalilan su, ƙin amincewa da amsoshin su, da kimantawa.

Ta yaya za ka yi alamar ADR a matsayin wanda aka maye gurbinsa?

Ta hanyar al'ada, ba ta hanyar fanni ba — kuma yana da kyau a kasance da gaskiya cewa babu wani matsayin da aka gina wanda aka ba da shawara/aka karɓa/aka maye gurbin a kan hujja. Yi amfani da sabuntawa ta hanyar ƙirƙirar sabon hukunci a matsayin hujja ta kansa da aka haɗa da wanda ya maye gurbinsa, yana bayyana abin da ya canza (iyakar ƙimar da aka ƙara, sabon buƙata). Tsohon hukuncin yana nan a karanta — goge shi zai lalata daidai tunanin da sabon hukuncin ke buƙatar ambato. Bayyana al'adar a cikin yarjejeniyar aiki ta ƙungiyarku don a ci gaba da kiyaye ta da gangan.

Daina rubuta hukunci. Fara adana su.

Gudanar da RFC dinka na gaba a matsayin itace: zaɓuɓɓuka tare da dalilansu, ƙorafe-ƙorafe a matsayin jerin amsoshi, da ADR da ke rubuta kansa.

Fara Gwaji Kyauta na Kwanaki 14

Babu katin kiredit da ake bukata

Daga RFC zuwa ADR: Samun Shawara da Tsare Dalilin