Esportare una porzione deterministica di un workspace con le perspective

Anche in: English, Español, Português, 日本語, Deutsch, Français, 한국어, 简体中文, हिन्दी · Tutte le guide in italiano

Trasparenza: Carbon Forge è sviluppato da 100monkeys.ai, quindi leggete questa guida come il resoconto di chi lo costruisce. L'ha scritta in bozza uno dei nostri agenti di IA a partire dalla documentazione pubblica, soprattutto Perspectives: beam angles through one workspace e la sezione Perspectives di Source control settings, e l'azienda l'ha rivista; questa edizione italiana è una traduzione della guida originale in inglese. La perspective e le chiamate sono gli esempi della documentazione stessa, e le citazioni restano in inglese con la traduzione accanto. Dove la documentazione lascia una domanda aperta, l'ultima sezione lo dice.

Che cos'è una perspective

La documentazione: "A perspective is a named lens through that record. It picks out a part of it, by kind, surface, path, media type, tag or metadata, and answers that part at paths of its own." (Una perspective è una lente con un nome attraverso quel registro. Ne sceglie una parte, per tipo, superficie, percorso, tipo di media, tag o metadati, e restituisce quella parte a percorsi propri.) E: "Nothing is copied to make one." (Per crearne una non si copia nulla.) Due proprietà contano per un'esportazione. È di sola lettura per ambito: "A perspective never discloses. It narrows what the reader already reads and never widens it." (Una perspective non rivela mai. Restringe ciò che il lettore già legge e non lo allarga mai.) E il suo download è deterministico: "The same ref through the same perspective gives the same bytes." (La stessa ref attraverso la stessa perspective dà gli stessi byte.)

Passo 1. Elencate le perspective che il workspace risolve

Chiamate perspectives.list. Ogni workspace ha perspective integrate: all, code, docs, adrs, internal, public (esattamente ciò che viene servito a un lettore anonimo) e una tree:<path> per ogni albero di codice, con radice in quell'albero. Un amministratore dell'istanza può aggiungere perspective per tutta l'istanza, e quelle del workspace vengono per ultime; "The nearest layer wins" (vince il livello più vicino). Ogni risposta indica la sua source e le fonti che overrides. Se una integrata va già bene, passate al passo 3.

Passo 2. Scrivete la vostra nella pagina .perspectives

Le perspective del workspace stanno nella pagina riservata .perspectives, come blocco JSON delimitato o come tabella. L'esempio della documentazione, ridotto a una perspective:

{
  "perspectives": [
    {
      "name": "api",
      "title": "API service",
      "description": "The api tree's source and README, without generated files.",
      "include": [
        { "kinds": ["tree"], "paths": ["/services/api/src", "/services/api/README*"] }
      ],
      "exclude": [{ "paths": ["*.generated.ts"] }],
      "root": "services/api"
    }
  ]
}

Una regola corrisponde quando corrispondono tutti i campi che nomina; include prende tutto ciò che corrisponde a una qualsiasi regola, ed exclude toglie tutto ciò che corrisponde a una qualsiasi regola, "even when an include rule matched it" (anche quando una regola include l'aveva preso). I percorsi sono glob in stile gitignore e non possono iniziare con !. Con root impostato, la radice viene tolta da ogni percorso, quindi questa perspective restituisce src/main.ts e README.md. Gli alberi di codice vengono valutati file per file. Template come monorepo, service, library o docs-site possono scrivere la pagina per voi con perspectives.adopt, oppure con Adopt in Settings, Workspace, Source control.

Una riga sbagliata non viene saltata. "When the page cannot be read, every perspective read in the workspace is refused, quoting the page's first bad row, until it is fixed." (Quando la pagina non si può leggere, ogni lettura tramite perspective nel workspace viene rifiutata, citando la prima riga sbagliata della pagina, finché non viene corretta.) La pagina mostra un pannello, Perspectives on this page, che ricontrolla a ogni salvataggio.

Passo 3. Vedetene l'anteprima su una ref

perspectives.preview conta ciò che la perspective contiene su una ref, per tipo, e restituisce i primi percorsi proiettati, 100 per default e al massimo 500. "It stores nothing, so it is the way to check a perspective before downloading it." (Non salva nulla, quindi è il modo per controllare una perspective prima di scaricarla.) Nel browser, lo stesso conteggio appare accanto al selettore nella barra delle ref del browser del codice: Selects <n> pages, <n> atoms, <n> code trees, <n> files, <n> library entries at <ref>.

Passo 4. Scegliete una ref che non si sposta

Una ref è trunk (default), lane:<label>, cut:<name> o snapshot:<id>. Il job di esportazione risolve la ref quando viene eseguito, "so trunk is the trunk at that moment. Name a cut or a snapshot for a point that does not move." (quindi trunk è il trunk in quel momento. Indicate un cut o uno snapshot per un punto che non si sposta.) Per un download che volete riprodurre, indicate un cut. Una lane in conflitto viene rifiutata finché il conflitto non è risolto.

Passo 5. Esportate e scaricate l'archivio

perspectives.export { "perspective": "api", "ref": "cut:<name>", "format": "tar" }
→ { export_id, status: "queued" }
exports.status { ... }   // until it answers a download_url

Interrogate exports.status con l'id dell'esportazione finché non restituisce una download_url; chi l'ha richiesta riceve anche un'email con un link. L'archivio si chiama <workspace>-<perspective>-<ref>.zip o .tar. Dentro, una pagina o un atomo è un file Markdown con frontmatter per titolo, tipo e metadati; un file di codice conserva i suoi byte e il suo modo; un link simbolico resta un link simbolico. Le voci sono ordinate per byte del percorso, ogni file porta l'ora della ref, nulla è compresso e non viene scritto alcun proprietario. Uno zip contiene al massimo 65.535 voci e 4 GiB; oltre, usate tar. Nel browser, scegliete zip o tar e premete Download accanto all'anteprima.

Passo 6. Verificate ogni file sul manifesto

Ogni archivio esportato contiene .carbon/perspective.json, in formato carbon-perspective/1. Indica l'istanza, il workspace, la perspective così come è stata risolta e la ref: un cut o uno snapshot tramite il suo id di snapshot, il trunk o una lane tramite composition_sha256. Ogni voce elenca:

path, kind, entity_id, revision_id, content_hash, seal_hash, mode, size, sha256

Calcolate l'hash di ogni file e confrontatelo con sha256; confrontate revision_id, content_hash e seal_hash con il registro. La documentazione: con il manifesto, "a reader can check every file against the record it came from" (un lettore può verificare ogni file sul registro da cui proviene). È questo che fa dell'archivio una porzione del registro e non "a copy that can drift into a second truth." (una copia che può derivare fino a diventare una seconda verità).

Passo 7. Riportate le modifiche tramite una lane

"A download is read-only by design. Nothing in the archive is read back." (Un download è di sola lettura per progetto. Nulla dell'archivio viene riletto.) Per riportare il lavoro fatto sull'archivio, scrivetelo con una chiamata a strumento, mettetelo su una lane e integratela, oppure importatelo, così che ogni modifica porti il proprio attore e la propria intenzione. Working in lanes spiega la lane, e la nostra guida Cut a release in Carbon Forge and push it to GitHub (in inglese) spiega come fare il cut da cui esportate.

Cosa la documentazione lascia senza risposta

• La dimensione del limite di esportazione. Un download che lo supera fallisce con una frase che indica il limite, ma la documentazione non dice il valore predefinito.
• Per quanto tempo una download_url resta valida e per quanto viene conservata un'esportazione.
• Chi può modificare .perspectives. Adottare un template è un'azione da amministratore; la pagina stessa "is edited like any other page" (si modifica come qualsiasi altra pagina), il che si legge come qualsiasi editor.
• Uno strumento per verificare un archivio sul suo manifesto. Il formato è descritto; la verifica è lasciata allo script di ciascun lettore.