AGENTS.hy.md

lang	hy
direction	ltr
source	AGENTS.md
status	complete
generator	scripts/sync_docs_i18n.py
source_hash	5036d004829b1c2da0991b637aa735da9cdf2f3e8e42ac760ff651e60d25d433
source_last_modified	2026-01-31T07:37:05.947018+00:00
translation_last_reviewed	2026-02-07
translator	machine-google-reviewed

ԳՈՐԾԱԿԱԼՆԵՐ Հրահանգներ

Այս ուղեցույցները վերաբերում են ողջ պահեստին, որը կազմակերպված է որպես բեռների աշխատանքային տարածք:

Արագ մեկնարկ

• Ստեղծեք աշխատանքային տարածք՝ cargo build --workspace
• Շինությունները կարող են տևել մոտ 20 րոպե; կառուցման քայլերի համար օգտագործեք 20 րոպե տևողություն:
• Փորձեք ամեն ինչ՝ cargo test --workspace (նկատի ունեցեք, որ այս գործարկումը սովորաբար տևում է մի քանի ժամ, պլանավորեք համապատասխանաբար)
• Լինտ խստորեն՝ cargo clippy --workspace --all-targets -- -D warnings
• Ձևաչափի կոդը՝ cargo fmt --all (հրատարակություն 2024)
• Փորձարկեք մեկ տուփ՝ cargo test -p <crate>
• Կատարեք մեկ թեստ՝ cargo test -p <crate> <test_name> -- --nocapture
• Swift SDK. IrohaSwift գրացուցակից գործարկեք swift test՝ Swift փաթեթի թեստերը կատարելու համար:
• Android SDK. java/iroha_android-ից գործարկեք JAVA_HOME=$(/usr/libexec/java_home -v 21) ANDROID_HOME=~/Library/Android/sdk ANDROID_SDK_ROOT=~/Library/Android/sdk ./gradlew test:

Տեսություն

• Hyperledger Iroha-ը բլոկչեյն հարթակ է
• DA/RBC աջակցությունը տարբերվում է հիմնական տարբերակից. Iroha 3-ը կարող է միացված լինել միայն DA/RBC:
• IVM-ը Iroha վիրտուալ մեքենան է (IVM), վիրտուալ մեքենա Hyperledger Iroha v2 բլոկչեյնի համար։
• Kotodama-ը բարձր մակարդակի խելացի պայմանագրային լեզու է IVM-ի համար, որն օգտագործում է .ko ֆայլի ընդլայնում չմշակված պայմանագրային կոդի համար, և այն հավաքվում է բայթկոդի մեջ, որն օգտագործում է .to ֆայլի ընդլայնում, երբ պահվում է որպես ֆայլ կամ շղթայի մեջ: Սովորաբար, .to բայթկոդը տեղադրվում է շղթայի վրա:
  • Պարզաբանում. Kotodama-ն ուղղված է Iroha վիրտուալ մեքենային (IVM) և արտադրում է IVM բայթկոդ (.to): Այն չի թիրախավորում «risc5»/RISC‑V որպես ինքնուրույն ճարտարապետություն: Այնտեղ, որտեղ պահոցում հայտնվում են RISC-V-ի նման կոդավորումներ, դրանք IVM-ի հրահանգների ձևաչափերի կատարման մանրամասներն են և չպետք է փոխեն տեսանելի վարքը ապարատում:
• Norito-ը Iroha-ի տվյալների սերիականացման կոդեկն է
• Ամբողջ աշխատանքային տարածքը ուղղված է Rust ստանդարտ գրադարանին (std): WASM/no-std build-ներն այլևս չեն աջակցվում և չպետք է հաշվի առնվեն փոփոխություններ կատարելիս:## Պահեստի կառուցվածքը
• Cargo.toml-ը պահեստի արմատում սահմանում է աշխատանքային տարածքը և թվարկում բոլոր անդամների տուփերը:
• crates/ – Iroha բաղադրիչներ ներդրող ժանգոտ տուփեր: Յուրաքանչյուր արկղ ունի իր ենթացանցը, որը սովորաբար պարունակում է src/, tests/, examples/ և benches/:
  • Կարևոր արկղերը ներառում են.
    • iroha – գրադարանի վերին մակարդակի հիմնական գործառույթը համախմբող:
    • irohad – daemon երկուական, որն ապահովում է հանգույցի իրականացումը:
    • ivm – Iroha վիրտուալ մեքենա:
    • iroha_cli – հրամանի տող ինտերֆեյս հանգույցի հետ փոխազդելու համար:
    • iroha_core, iroha_data_model, iroha_crypto և այլ օժանդակ տուփեր:
• IrohaSwift/ – Swift փաթեթ հաճախորդի/բջջային SDK-ի համար: Դրա աղբյուրները ապրում են Sources/IrohaSwift/-ի տակ, իսկ միավորը փորձարկում է Tests/IrohaSwiftTests/-ի ներքո: Գործարկեք swift test-ն այս գրացուցակից՝ Swift փաթեթը գործարկելու համար:
• integration_tests/ – tests/-ի ներքո բեռների արկղի հոսթինգի խաչաձև բաղադրիչ թեստեր:
• data_model/ – Տվյալների մոդելի օրինակելի սահմանումներ, որոնք օգտագործվում են թեստերում և փաստաթղթերում:
• docs/ – Ծրագրի փաստաթղթեր և նախագծային նշումներ: Markdown աղբյուրները ապրում են docs/source/-ում:
• pytests/ – Python-ի վրա հիմնված թեստեր և օրինակներ, որոնք ցույց են տալիս հաճախորդի օգտագործումը:
• scripts/ – Կոմունալ սկրիպտներ, որոնք օգտագործվում են մշակման և CI խողովակաշարերում:
• examples/ios/ և examples/ios/NoritoDemoXcode/ – Swift SDK-ն ցուցադրող iOS հավելվածների նմուշ; նրանք ապավինում են IrohaSwift փաթեթին և ներառում են իրենց սեփական XCTest թիրախները:
• defaults/ և hooks/ – Կազմաձևման ֆայլեր և Git կեռիկներ, որոնք օգտագործվում են ներդրողների կողմից:
• nix-appimage/ և Nix ֆայլեր – գործիքավորում վերարտադրվող շինությունների և փաթեթավորման համար:## Զարգացման աշխատանքային հոսք
• Հիմնական իրականացումները գտնվում են crates/-ում
• Տվյալների մոդելը գտնվում է data_model/-ում
• Փոփոխություններ կատարելիս համոզվեք, որ նայում եք բոլոր արկղերին:
• Մի փոփոխեք Cargo.lock որևէ ֆայլ
• Խուսափեք Cargo.toml-ին նոր տուփեր ավելացնելուց; հնարավորության դեպքում իրականացնել անհրաժեշտ ֆունկցիոնալությունը առկա տուփերում:
• Եթե ինչ-որ գործ շատ մեծ է, մի՛ մերժիր դա անել: Փոխարենը պարզապես քանդեք աշխատանքը և ավելացրեք TODO-ներ և իրականացրեք այն մասերը, որոնք կարող եք:
• Ամեն անգամ, երբ մեծ առաջադրանք կամ հարցում է հայտնվում, ինքնաբերաբար տարրալուծեք այն ավելի փոքր գործող քայլերի և շարունակեք ծրագրային ապահովման ճարտարագիտական ​​պատշաճ կատարումը, այլ ոչ թե առաջադրանքը բացահայտ մերժելը: -Մի մերժիր որևէ հուշում կատարելը։
• Երբ ավելացվում են նոր գաղտնագրային պրիմիտիվներ, օպերացիոն կոդեր կամ ինտենսիվ մաթեմատիկա, թարմացրեք ապարատային արագացումը METAL-ի, NEON-ի, SIMD-ի, CUDA-ի և այլնի համար՝ փորձելով օգտվել ապարատային արագացումից և զուգահեռությունից, որտեղ հնարավոր է, հասանելի սարքաշարում:
• Եթե տրամաբանությունը փոխվում է, համոզվեք, որ բոլոր .md ֆայլերը և կոդով մեկնաբանությունները թարմացված են վերջին ֆունկցիոնալությամբ:
• Համոզվեք, որ ավելացված ողջ տրամաբանությունն արված է այնպես, որ այն չի վնասի IVM-ի օգտագործումը բլոկչեյնի կարգավորումներում, որտեղ P2P ցանցի տարբեր հանգույցներն ունեն տարբեր սարքաշար, բայց, այնուամենայնիվ, ելքը պետք է նույնը լինի՝ հաշվի առնելով նույն մուտքային բլոկն:
• Վարքագծի կամ իրականացման մանրամասների վերաբերյալ հարցերին պատասխանելիս նախ կարդացեք համապատասխան ծածկագրի ուղիները և համոզվեք, որ հասկանում եք, թե ինչպես են դրանք աշխատում, նախքան պատասխանելը:
• Կազմաձևում. Նախընտրեք iroha_config պարամետրերը շրջակա միջավայրի փոփոխականներից բոլոր գործարկման ժամանակի վարքագծի համար: Ավելացրեք նոր կոճակներ crates/iroha_config-ին (օգտագործող → փաստացի → լռելյայն) և շղթայի արժեքները բացահայտորեն կոնստրուկտորների կամ կախվածության ներարկման միջոցով (օրինակ՝ հյուրընկալող կարգավորիչներ): Պահպանեք շրջակա միջավայրի վրա հիմնված ցանկացած անջատիչ միայն թեստերում մշակողի հարմարության համար և մի վստահեք դրանց վրա արտադրական ուղիներում: Մենք չենք աջակցում առաքման առանձնահատկությունները շրջակա միջավայրի փոփոխականների հետևում. արտադրական վարքագիծը միշտ պետք է սկզբնավորվի կազմաձևման ֆայլերից, և այդ կազմաձևերը պետք է բացահայտեն խելամիտ լռելյայնությունները, որպեսզի նորեկը կարողանա կլոնավորել ռեպո-ն, գործարկել երկուականները և ամեն ինչ «պարզապես աշխատի»՝ առանց արժեքները ձեռքով խմբագրելու:
  • IVM/Kotodama v1-ի համար միշտ կիրառվում է ցուցիչ-ABI տեսակի խիստ քաղաքականություն: Չկա ABI-քաղաքականության փոխարկիչ; պայմանագրերը և տանտերերը պետք է անվերապահորեն հետևեն ABI քաղաքականությանը:
• Մի՛ փակցրեք IVM համակարգային զանգերում կամ օպերացիոն կոդերում օգտագործվող որևէ բան. Iroha-ի յուրաքանչյուր կառուցում պետք է ուղարկի այդ կոդերի ուղիները, որպեսզի պահպանի դետերմինիստական ​​վարքագիծը հանգույցներում:
• Սերիալացում. serde-ի փոխարեն ամենուր օգտագործեք Norito: Երկուական կոդեկների համար օգտագործեք norito::{Encode, Decode}; JSON-ի համար օգտագործեք norito::json օգնականները/մակրոները (norito::json::from_*, to_*, json!, Value) և երբեք չվերադարձնեք I18NI0000000-ին: Մի ավելացրեք ուղղակի serde/serde_json կախվածություն տուփերում; եթե սերդը պահանջվում է ներսում, ապավինեք Norito-ի փաթաթաններին:
• CI պաշտպան. Գործարկեք այն լոկալ, եթե դիպչեք սերիականացման կոդի:
• Norito օգտակար բեռները ՊԵՏՔ Է գովազդեն իրենց դասավորությունը. կա՛մ տարբերակի համարը քարտեզագրվում է ֆիքսված դրոշի հավաքածուի վրա, կա՛մ Norito վերնագիրը հայտարարում է վերծանման դրոշները: Էվրիստիկայից մի գուշակեք փաթեթավորված հաջորդականության բիթերը. Ծննդոց տվյալները հետևում են նույն կանոնին.- Բլոկները ՊԵՏՔ Է պահպանվեն և բաշխվեն՝ օգտագործելով կանոնական SignedBlockWire ձևաչափը (SignedBlock::encode_wire/canonical_wire), որը նախածանցում է տարբերակի բայթը Norito վերնագրով: Բաց ծանրաբեռնվածությունը չի ապահովվում:
• Ավելացրեք TODO: մեկնաբանություն՝ բացատրելով ցանկացած ժամանակավոր կամ թերի իրականացում:
• Ձևաչափեք Rust-ի բոլոր աղբյուրները cargo fmt --all-ով (հրատարակություն 2024), նախքան կատարելը:
• Ավելացնել թեստեր. ապահովել առնվազն մեկ միավորի թեստ յուրաքանչյուր նոր կամ փոփոխված ֆունկցիայի համար, որը տեղադրված է կամ #[cfg(test)]-ի հետ կամ արկղի tests/ գրացուցակում:
• Գործարկեք cargo test-ը տեղական մակարդակում, շտկեք կառուցման ցանկացած խնդիր և համոզվեք, որ այն անցնում է: Դա արեք ամբողջ պահեստի համար, այլ ոչ միայն հատուկ տուփի համար:
• Ընտրովիորեն գործարկեք cargo clippy -- -D warnings-ը` ցողունի լրացուցիչ ստուգման համար:

Փաստաթղթեր

• Միշտ ավելացրեք տուփի մակարդակի փաստաթղթեր. սկսեք յուրաքանչյուր արկղ կամ փորձնական տուփ հակիրճ ներքին փաստաթղթով (//! ...):
• Մի օգտագործեք #![allow(missing_docs)] կամ ապրանքի մակարդակի #[allow(missing_docs)] որևէ տեղ (ներառյալ ինտեգրման թեստերը): Բացակայող փաստաթղթերը հերքվում են աշխատանքային տարածքի գծերում և պետք է շտկվեն փաստաթղթեր գրելով:
• Norito կոդեկ. տես norito.md ռեպո արմատում՝ կանոնական on-wire դասավորության և իրականացման մանրամասների համար: Եթե ​​Norito-ի ալգորիթմները կամ դասավորությունները փոխվեն, թարմացրեք norito.md-ը նույն PR-ում:
• Նյութերը աքքադերեն թարգմանելիս տրամադրեք սեպագիր գրված իմաստային թարգմանություն. խուսափեք հնչյունական տառադարձությունից, և երբ բացակայում են ստույգ հին տերմինները, ընտրեք բանաստեղծական աքքադերեն մոտարկումներ, որոնք պահպանում են մտադրությունը:

ABI Evolution (Ինչ պետք է անեն գործակալները)

Նշում. Առաջին թողարկման քաղաքականություն

• Սա առաջին թողարկումն է, և մենք ունենք մեկ ABI տարբերակ (V1): V2 դեռ չկա: Վերաբերվեք ստորև բերված էվոլյուցիայի բոլոր կետերին, որոնք առնչվում են ABI-ին որպես ապագա ուղեցույց. առայժմ թիրախը միայն abi_version = 1 է: Տվյալների մոդելը և API-ները նույնպես առաջին թողարկված են և կարող են ազատորեն փոխվել, երբ անհրաժեշտ է առաքման համար. նախընտրում են հստակությունն ու կոռեկտությունը վաղաժամ կայունությունից:

• Ընդհանուր:

  • ABI-ի քաղաքականությունը անվերապահորեն կիրառվում է v1-ում (ինչպես syscall մակերեսի, այնպես էլ ցուցիչ-ABI տեսակի): Մի ավելացրեք գործարկման ժամանակի անջատիչներ:
  • Փոփոխությունները պետք է պահպանեն դետերմինիզմը սարքավորումների և գործընկերների միջև: Թարմացրեք թեստերն ու փաստաթղթերը նույն PR-ում:

• Եթե ավելացնեք/հեռացնեք/վերահամարակալեք syscals.

  • Թարմացրեք ivm::syscalls::abi_syscall_list() և պահեք այն պատվիրված: Համոզվեք, որ is_syscall_allowed(policy, number) արտացոլում է նախատեսված մակերեսը:
  • Կիրառել կամ միտումնավոր մերժել նոր համարները հոսթներում; Անհայտ թվերը պետք է համապատասխանեն VMError::UnknownSyscall-ին:
  • Թարմացրեք ոսկե թեստերը.
    • crates/ivm/tests/abi_syscall_list_golden.rs
    • crates/ivm/tests/abi_hash_versions.rs (կայունություն + տարբերակի տարանջատում)

• Եթե ավելացնեք ցուցիչ-ABI տեսակները.

  • Ավելացրեք նոր տարբերակը ivm::pointer_abi::PointerType-ին (նշանակեք նոր u16 ID, երբեք մի փոխեք գոյություն ունեցող ID-ները):
  • Թարմացրեք ivm::pointer_abi::is_type_allowed_for_policy-ը ճիշտ abi_version քարտեզագրման համար:
  • Թարմացրեք crates/ivm/tests/pointer_type_ids_golden.rs-ը և անհրաժեշտության դեպքում ավելացրեք քաղաքականության թեստեր:

• Եթե դուք ներկայացնում եք նոր ABI տարբերակ.

  • Քարտեզեք ProgramMetadata.abi_version → ivm::SyscallPolicy և թարմացրեք Kotodama կոմպիլյատորը, երբ պահանջվի, թողարկվի նոր տարբերակը:
  • Վերականգնեք abi_hash-ը (ivm::syscalls::compute_abi_hash-ի միջոցով) և համոզվեք, որ մանիֆեստները տեղադրեն նոր հեշը:
  • Նոր տարբերակում ավելացրեք թույլատրված/չթույլատրված syscals-ի և ցուցիչների տեսակների թեստեր:

• Ընդունելություն և դրսևորումներ.

  • Ընդունելությունը պարտադրում է code_hash/abi_hash հավասարությունը շղթայական դրսևորումների նկատմամբ. պահպանել այս վարքագիծը անձեռնմխելի:
  • iroha_core/tests/-ում ավելացնելու/թարմացնելու թեստեր՝ դրական (համապատասխանող abi_hash) և բացասական (անհամապատասխանություն) դեպքեր:- Փաստաթղթեր և կարգավիճակի թարմացումներ (նույն PR).
  • Թարմացրեք crates/ivm/docs/syscalls.md (ABI Evolution բաժինը) և ցանկացած syscall աղյուսակներ:
  • Թարմացրեք status.md-ը և roadmap.md-ը՝ ABI-ի փոփոխությունների և թեստային թարմացումների համառոտ ամփոփմամբ:

Ծրագրի կարգավիճակը և պլանը

• Ստուգեք status.md-ը ռեպո արմատից՝ արկղերում առկա կազմման/աշխատանքի ընթացիկ կարգավիճակի համար:
• Ստուգեք roadmap.md առաջնահերթ TODO-ների և իրականացման պլանի համար:
• Աշխատանքն ավարտելուց հետո թարմացրեք կարգավիճակը status.md-ում և պահեք roadmap.md-ը կենտրոնացած չմարված առաջադրանքների վրա:

Գործակալի աշխատանքային հոսք (կոդերի խմբագրիչների/ավտոմատացման համար)

• Եթե որևէ պահանջի վերաբերյալ պարզաբանման կարիք ունեք, դադարեցրեք և կազմեք ChatGPT հուշում ձեր հարցի հետ, այնուհետև կիսվեք այն օգտագործողի հետ՝ նախքան շարունակելը:
• Պահպանեք փոփոխությունները նվազագույն և ծավալով; խուսափել անկապ խմբագրումներից նույն կարկատում:
• Նախընտրեք ներքին մոդուլները նոր կախվածություններ ավելացնելու փոխարեն; մի խմբագրեք Cargo.lock:
• Օգտագործեք առանձնահատկությունների դրոշները՝ ապարատային արագացված ուղիները պաշտպանելու համար (օրինակ՝ simd, cuda) և միշտ տրամադրեք որոշիչ հետադարձ ճանապարհ:
• Ապահովել, որ ելքերը մնում են նույնական ապարատային սարքերում. խուսափել ոչ դետերմինիստական ​​զուգահեռ կրճատումների վրա հույս դնելուց:
• Թարմացրեք փաստաթղթերը և օրինակները, երբ փոխվում են հանրային API-ները կամ վարքագիծը:
• Վավերացրեք iroha_data_model սերիականացման փոփոխությունները շրջադարձային թեստերով՝ Norito դասավորության երաշխիքները պահպանելու համար:
• Ինտեգրման թեստերը պտտում են իրական բազմակողմանի ցանցեր; փորձնական ցանցեր կառուցելիս օգտագործեք առնվազն 4 գործընկերներ (մեկ գործընկերային կազմաձևերը ներկայացուցչական չեն և կարող են փակուղի հայտնվել Sumeragi-ում):
• Մի փորձեք անջատել DA/RBC-ն թեստերում (օրինակ՝ DevBypassDaAndRbcForZeroChain-ի միջոցով); DA-ն ուժի մեջ է, և այդ շրջանցման ուղին ներկայումս փակուղի է մտել sumeragi-ում՝ համաձայնության գործարկման ժամանակ:
• QC քվորումը պետք է բավարարվի քվեարկության վավերացնողների կողմից (min_votes_for_commit); Դիտորդների լիցքավորումը չի հաշվվում առկայության/նախօրոք քվեարկության/նախապես ստանձնելու քվորումի ստուգումների համար, այնպես որ խմբավորեք QC-ները միայն այն բանից հետո, երբ բավարար վավերացնող ձայներ կգան:
• DA-ով միացված կոնսենսուսն այժմ ավելի երկար է սպասում մինչև դիտումների փոփոխությունները (քվորումի ժամկետի ավարտ = block_time + 4 * commit_time), որպեսզի RBC/հասանելիության QC-ն ավարտվի ավելի դանդաղ հոսթորդների վրա:

Նավիգացիոն խորհուրդներ

• Որոնել կոդը՝ rg '<term>' և ցուցակի ֆայլեր՝ fd <name>:
• Ուսումնասիրեք արկղերը՝ fd --type f Cargo.toml crates | xargs -I{} dirname {}:
• Արագ գտնել օրինակներ/նստարաններ՝ fd . crates -E target -t d -d 3 -g "*{examples,benches}":
• Python հուշում. որոշ միջավայրեր չեն ապահովում python; փոխարենը փորձեք python3, երբ գործարկում եք սկրիպտներ:

Proc-Macro թեստեր

• Միավորի թեստեր. օգտագործել մաքուր վերլուծության, կոդեգենների օգնականների և կոմունալ ծառայությունների համար (արագ, կոմպիլյատոր չկա):
• UI-ի թեստեր (trybuild). օգտագործել վավերացնելու համար կոմպիլյացիայի ժամանակի վարքագիծը և ածանցյալ/proc-մակրոների ախտորոշումը (հաջողության և ակնկալվող ձախողման դեպքեր .stderr-ով):
• Նախընտրեք երկուսն էլ մակրոներ ավելացնելիս/փոխելիս՝ միավորի թեստեր ներքին սարքերի համար + UI թեստեր՝ օգտատերերի առջև դրված վարքագծի և սխալի հաղորդագրությունների համար:
• Խուսափեք խուճապից; թողարկեք հստակ ախտորոշում (օրինակ՝ syn::Error կամ proc_macro_error միջոցով): Հաղորդագրությունները կայուն պահեք և թարմացրեք .stderr միայն միտումնավոր փոփոխությունների համար:

Քաշեք հարցումի հաղորդագրություն

Ներառեք փոփոխությունների կարճ ամփոփագիրը և Testing բաժինը, որը նկարագրում է ձեր գործած հրամանները: