OmniRoute/docs/i18n/phi/docs/ops/CONTRIBUTION_GOLDEN_PATH.md

Contribution Golden Path (Filipino)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

Gamitin ang gabay na ito upang piliin ang pinakamaliit na maaasahang development loop para sa isang pull request. Hindi nito pinapalitan ang mga dokumento sa arkitektura at seguridad na partikular sa bawat area at naka-link sa ibaba; iniuugnay nito ang bawat karaniwang uri ng pagbabago sa mga contract, nakatuong pagsusuri, at saklaw ng CI nito.

Ang landas na sinusundan ng bawat pagbabago

1. Piliin ang base bago mag-edit. Hanapin ang pinakamataas na aktibong release/v* branch at gumawa ng branch mula sa pinakahuling commit nito. I-target ang branch na iyon, hindi ang main. Kung may aktibong release freeze, huwag i-target ang naka-freeze na branch; gamitin ang susunod na aktibong cycle na inilalarawan sa Modelo ng Branching at Release.
2. Tukuyin ang mga contract. Tukuyin ang bawat catalog, schema, nabuong artifact, pampublikong API, o user interface na naaapektuhan ng pagbabago. Ibinibigay ng talahanayan sa ibaba ang minimum na panimulang hanay.
3. Sumulat o mag-update ng mga nakatuong test. Ang mga pagbabago sa production sa src/, open-sse/, electron/, o bin/ ay nangangailangan ng automated test sa parehong PR. Patakbuhin ang pinakamaliliit na test file na nagpapatunay sa gawi, pagkatapos ay ang mga nakalistang nakatuong gate.
4. Hayaang patakbuhin ng CI ang malawak na matrix. Tumatakbo sa PR ang kumpletong unit shard, Vitest, coverage ratchet, at production build. Magpatakbo lamang ng malawak na suite nang lokal kapag ang isang nakatuong failure ay nagpapahiwatig ng mas malawak na epekto o kapag sumasaklaw ang pagbabago sa ilang subsystem.
5. Itugma bago ang review. I-fetch ang aktibong base, suriin ang mga bagong commit nito at ang iyong diff laban dito, pagkatapos ay i-rebase o i-merge ang base ayon sa contributor workflow. Lutasin ang mga conflict sa nabuong file at catalog mula sa pinagmulan ng mga ito, buuin muli ang mga ito, patakbuhin muli ang nakatuong loop, at kumpirmahing naka-target pa rin ang PR sa aktibong release branch.
6. Itala ang ebidensya. Sa PR template, ilista ang mga command na pinatakbo, bawat test file na idinagdag o binago, mga migration o feature flag, at anumang validation na para lamang sa CI na nakabinbin pa.

Mga pangunahing landas ayon sa uri ng pagbabago

Ang mga command sa ibaba ay mga minimum na nakatuong pagsusuri, hindi pahintulot na laktawan ang isang test na direktang sumasaklaw sa gawi na binago mo.

Provider

Mga contract

• Depinisyon ng provider sa src/shared/constants/providers/ at ang komposisyon nito sa src/shared/constants/providers.ts.
• Mga model at capability sa open-sse/config/providerRegistry.ts o sa mga inihiwalay na registry file nito.
• Pagpili ng executor/translator, configuration ng OAuth o API key, mga asset ng dashboard, at nabuong sanggunian ng provider kapag naaangkop.
• Dapat gamitin ng mga pampublikong credential ang resolvePublicCred(); dapat gamitin ng mga error response ang mga nakabahaging sanitized error helper. Tingnan ang docs/security/PUBLIC_CREDS.md (git; hindi kino-compile sa /docs) at Pag-sanitize ng Error.

Nakatuong loop

npm run check:provider-consistency
npm run check:provider-assets
node --import tsx/esm --test tests/unit/provider-translate-path-golden.test.ts
node --import tsx/esm --test tests/unit/<provider-or-executor>.test.ts
npm run gen:provider-reference   # kapag nagbago ang catalog; i-commit ang nabuong diff
npm run lint

I-test din ang bawat apektadong pamilya ng request: chat, Responses, images, embeddings, audio, o video. Suriin ang nabuong catalog at mga golden diff bilang mga pagbabago sa contract; huwag tanggapin ang mga ito nang walang pagsusuri.

Routing

Mga contract

• Mga pampublikong value ng strategy at UI metadata sa src/shared/constants/routingStrategies.ts.
• Dispatch at pagkakasunod-sunod sa ilalim ng open-sse/services/combo.ts at open-sse/services/combo/.
• Mga combo schema, persistence, resilience state, capability ng model, at mga kontrol ng API/UI.
• Auto-Combo Engine at dokumentasyon ng resilience kapag nagbabago ang gawi.

Nakatuong loop

node --import tsx/esm --test tests/unit/combo-<behavior>.test.ts
npm run test:combo:matrix        # mga pagbabago sa strategy o dispatch
npm run check:known-symbols      # mga pagbabago sa pagpaparehistro ng strategy
npm run lint

Gumamit ng mga deterministic na test na may mocked upstream nang lokal. Nangangailangan ng mga credential ang mga live combo smoke test at manual ang mga ito, hindi pamalit sa CI.

UI / UX

Mga contract

• Next.js route/page at mga hangganan ng shared component sa ilalim ng src/app/ at src/shared/components/.
• Mga hugis ng API response, loading/empty/error state, gawi ng keyboard at screen reader, responsive layout, theming, at pagpapalawak ng locale.
• Mga English UI source string sa src/i18n/messages/en.json; huwag mag-hard-code ng bagong text na nakikita ng user.

Nakatuong loop

node --import tsx --test tests/unit/dashboard/<feature>.test.ts
npx vitest run --config vitest.config.ts tests/unit/ui/<component>.test.tsx
npm run check:dashboard-typecheck
npm run lint

Patakbuhin ang app para sa mga pagbabago sa interaction o visual at suriin ang parehong makitid at malawak na viewport. Pinapatakbo ng CI ang production build at mas malawak na mga suite; kailangan pa rin ng visual na gawi ng nakatuong component test, Playwright test, o nakadokumentong manual na pagsusuring naaangkop sa pagbabago.

i18n

Mga contract

• Ang src/i18n/messages/en.json ang source ng UI; ang config/i18n.json ang source ng locale.
• Hiwalay na matatagpuan ang mga CLI catalog sa ilalim ng bin/cli/locales/.
• Panatilihin nang eksakto ang mga ICU placeholder at tag. Huwag isalin ang mga pangalan ng product/provider/model, mga pangalan ng protocol at header, command, code/JSON identifier, URL, environment variable, o mga protektadong termino gaya ng OmniRoute, OAuth, MCP, at A2A. Ang kasalukuyang listahan ng source ay scripts/i18n/glossary/protected-terms.json.

Nakatuong loop

npm run i18n:sync-ui:dry
npm run i18n:check-ui-coverage
npm run i18n:check-value-drift
npm run i18n:check-glossary
npm run check:cli-i18n          # kapag nagbago ang mga CLI string/catalog
npm run lint

Gabay ito para sa kasalukuyang system, hindi imbitasyong palawakin ang tooling o key model nito. Panatilihing limitado at tiyak ang mga i18n patch habang idinidisenyo ang kapalit na system. Huwag magpatakbo ng mga translation command na tumatawag sa mga external service maliban kung tahasang nangangailangan ang task ng mga nabuong salin at nasuri mo na ang resultang diff.

CLI

Mga contract

• Mga pampublikong command at flag sa bin/cli/, mga nabuong API command, mga exit code, stdout/stderr at mga anyo ng JSON output, gawi ng config/environment, at mga naka-package na file.
• Dapat gamitin ng mga string na nakikita ng user sa CLI ang CLI i18n layer at panatilihing magkatugma ang mga catalog na en/pt-BR.
• Panatilihin ang Node bilang sinusuportahang runtime at ang inilathalang binary contract.

Nakatuong loop

node --import tsx/esm --test tests/unit/cli/<command>.test.ts
npm run check:cli-i18n
npm run build:cli             # mga pagbabago sa nabuo/na-bundle na CLI
npm run check:pack-policy     # mga pagbabago sa package surface
npm run lint

Gamitin ang eksaktong command sa isang pansamantalang data directory kapag nakadepende ang gawi sa pag-parse, mga file, o exit status. Isinasagawa ng CI ang mas malawak na pagsusuri sa package artifact at ecosystem.

Database

Mga contract

• Mga domain module sa ilalim ng src/lib/db/; direktang i-import ang mga partikular na module (inalis na ang lumang re-export layer na localDb.ts).
• Mga SQL migration na may numero at idempotent sa ilalim ng src/lib/db/migrations/, kaligtasan ng transaksyon, gawi sa pag-upgrade, mga index, at bawat caller na apektado ng schema.
• Hindi kailanman direktang nagpapatakbo ng raw SQL ang mga route at handler.

Nakatuong loop

npm run check:migration-numbering
npm run check:db-rules
node --import tsx/esm --test tests/unit/db/<domain>.test.ts
node --import tsx/esm --test tests/unit/db/migration-<number>.test.ts
npm run lint

Subukan kapwa ang isang bagong database at ang pag-upgrade mula sa naunang schema kapag nagdaragdag ng migration. Dapat isara ng mga database test ang mga handle at tawagin ang resetDbInstance() habang naglilinis. Patakbuhin lamang ang npm run test:bun:db kapag nagbago ang best-effort na Bun adapter path; nananatiling awtoritatibo ang Node.

Build / deployment

Mga contract

• Mga root at workspace manifest/lockfile, scripts/build/, standalone assembly ng Next.js, mga nilalaman ng package na dist/, metadata ng Electron platform, mga workflow ng CI, at mga deployment sentinel.
• Dapat manatiling buo ang mga sinusuportahang saklaw ng Node at ang pinahihintulutang paggamit ng Bun sa CLAUDE.md.
• Mananatiling hindi sinusubaybayan ang mga build artifact; nalalapat ang mga patakaran sa dependency, lisensya, workflow, at package.

Nakatuong loop

node --import tsx/esm --test tests/unit/build/<behavior>.test.ts
npm run check:build-scope
npm run check:lockfile         # mga pagbabago sa dependency o lockfile
npm run check:pack-policy      # mga pagbabago sa surface ng inilathalang package
npm run lint

Gamitin lamang ang npm run build nang lokal kapag naaapektuhan ng pagbabago ang compilation, standalone assembly, mga asset, o runtime bundling. Gamitin lamang ang npm run build:release para sa pagpapatunay ng release/deployment. Ang build ng CI ang panghuling cross-platform na signal; kailangan ng mga pagbabago sa Electron na partikular sa platform ang katugmang nakatuong build o ebidensya ng smoke test.

Lokal na loop kumpara sa CI

Patakbuhin nang lokal para sa bawat patch	Nagbibigay ang CI ng malawak na signal
Mga direktang pagsusuri sa gawi at mga category gate sa itaas	Hinating buong unit suite at mga serial test
npm run lint	Mga Vitest suite at ratchet para sa coverage/quality
Typecheck o build lamang kapag kailangan ito ng apektadong contract	Production build, seguridad, docs, dependency, at mga PR-policy gate
Manu-manong interaksiyon/live check lamang kapag hindi mapatunayan ng automation ang gawi	Mga cross-job integration at platform check na naka-configure ayon sa workflow

Ang matagumpay na focused loop ay ebidensiya tungkol sa binagong contract, hindi patunay na papasa ang mga hindi kaugnay na CI check. Gayundin, huwag paghintayin ang bawat lokal na pag-edit sa buong repository matrix.

Checklist sa reconciliation

Bago humiling ng review:

• Kumpirmahing ang PR base ay ang pinakamataas na aktibong release/v* branch pa rin.
• I-fetch ang base na iyon at i-review ang mga commit na naisama mula noong ginawa mo ang iyong branch.
• I-review ang git diff <active-base>...HEAD para sa hindi sinasadya o generated na churn.
• Lutasin ang mga conflict sa catalog at generated document sa pamamagitan ng pag-update sa source at muling pag-generate ng output.
• Patakbuhing muli ang bawat focused test/gate na nakalista sa paglalarawan ng PR pagkatapos ng reconciliation.
• Huwag kailanman pahinain ang mga assertion o alisin ang mga kinakailangang test para lamang umayon sa nabagong base.

Para sa mga panuntunan sa release freeze at retargeting, gamitin ang Modelo ng Branching at Release. Para sa kumpletong imbentaryo ng CI, gamitin ang Reference ng mga Quality Gate.