Aussi en: English, Español, Português, 日本語, Deutsch, 한국어, 简体中文, Italiano, हिन्दी · Tous les guides en français

Transparence : nous développons Carbon Forge chez 100monkeys.ai ; lisez donc ceci comme le récit du fabricant. Ce guide a été rédigé par l'un de nos agents d'IA à partir de la documentation publique (en anglais), principalement Perspectives: beam angles through one workspace et la section Perspectives de Source control settings, et relu par l'entreprise ; cette version française est une traduction du guide original en anglais. La perspective et les appels sont les exemples de la documentation. Là où la documentation laisse une question ouverte, la dernière section le dit.

Ce qu'est une perspective

La documentation : "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." (Une perspective est une lentille nommée sur ce registre. Elle en choisit une partie, par type, surface, chemin, type de média, tag ou métadonnées, et sert cette partie à ses propres chemins.) Et : "Nothing is copied to make one." (Rien n'est copié pour en créer une.) Deux propriétés comptent pour un export. Sa portée est en lecture seule : "A perspective never discloses. It narrows what the reader already reads and never widens it." (Une perspective ne divulgue jamais rien. Elle restreint ce que le lecteur lit déjà et ne l'élargit jamais.) Et son téléchargement est déterministe : "The same ref through the same perspective gives the same bytes." (La même ref à travers la même perspective donne les mêmes octets.)

Étape 1. Lister les perspectives que l'espace de travail résout

Appelez perspectives.list. Chaque espace de travail a des perspectives intégrées : all, code, docs, adrs, internal, public (exactement ce que reçoit un lecteur anonyme) et une tree:<path> par arbre de code, enracinée dans cet arbre. Un administrateur d'instance peut en ajouter pour toute l'instance, et celles de l'espace de travail viennent en dernier ; "The nearest layer wins" (la couche la plus proche l'emporte). Chaque réponse nomme sa source et les sources qu'elle overrides. Si une perspective intégrée convient déjà, passez à l'étape 3.

Étape 2. Écrire la vôtre sur la page .perspectives

Les perspectives d'un espace de travail vivent sur la page réservée .perspectives, sous forme de bloc JSON délimité ou de tableau. L'exemple de la documentation, réduit à une 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"
    }
  ]
}

Une règle correspond quand chaque champ qu'elle nomme correspond ; include prend tout ce à quoi une règle correspond, et exclude retire tout ce à quoi une règle correspond, "even when an include rule matched it" (même quand une règle include y correspondait). Les chemins sont des globs façon gitignore et ne peuvent pas commencer par !. Avec root, la racine est retirée de chaque chemin, si bien que celle-ci sert src/main.ts et README.md. Les arbres de code sont jugés fichier par fichier. Des modèles comme monorepo, service, library ou docs-site peuvent écrire la page pour vous via perspectives.adopt, ou Adopt sous Settings, Workspace, Source control.

Une ligne erronée n'est pas ignorée. "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." (Quand la page ne peut pas être lue, toute lecture de perspective dans l'espace de travail est refusée, en citant la première ligne erronée de la page, jusqu'à correction.) La page affiche un panneau, Perspectives on this page, qui revérifie à chaque enregistrement.

Étape 3. La prévisualiser à une ref

perspectives.preview compte ce que la perspective contient à une ref, par type, et renvoie les premiers chemins projetés, 100 par défaut et 500 au plus. "It stores nothing, so it is the way to check a perspective before downloading it." (Elle ne stocke rien : c'est donc le moyen de vérifier une perspective avant de la télécharger.) Dans le navigateur, le même décompte apparaît à côté du sélecteur dans la barre de ref du navigateur de code : Selects <n> pages, <n> atoms, <n> code trees, <n> files, <n> library entries at <ref>.

Étape 4. Choisir une ref qui ne bouge pas

Une ref est trunk (par défaut), lane:<label>, cut:<name> ou snapshot:<id>. La tâche d'export résout la ref au moment où elle s'exécute, "so trunk is the trunk at that moment. Name a cut or a snapshot for a point that does not move." (donc trunk est le trunk à cet instant. Nommez un cut ou un snapshot pour un point qui ne bouge pas.) Pour un téléchargement que vous voulez reproduire, nommez un cut. Une lane en conflit est refusée jusqu'à ce que le conflit soit résolu.

Étape 5. Exporter et télécharger l'archive

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

Interrogez exports.status avec l'identifiant de l'export jusqu'à ce qu'il renvoie une download_url ; le demandeur reçoit aussi un e-mail avec un lien. Le fichier s'appelle <workspace>-<perspective>-<ref>.zip ou .tar. À l'intérieur, une page ou un atome est un fichier Markdown avec un frontmatter pour son titre, son type et ses métadonnées ; un fichier de code garde ses octets et son mode ; un lien symbolique reste un lien symbolique. Les entrées sont triées par octets de chemin, chaque fichier porte l'heure de la ref, rien n'est compressé et aucun propriétaire n'est écrit. Un zip contient au plus 65 535 entrées et 4 Gio ; au-delà, prenez un tar. Dans le navigateur, choisissez zip ou tar et appuyez sur Download à côté de l'aperçu.

Étape 6. Vérifier chaque fichier contre le manifeste

Chaque archive contient .carbon/perspective.json, au format carbon-perspective/1. Il nomme l'instance, l'espace de travail, la perspective telle qu'elle a été résolue, et la ref : un cut ou un snapshot par son identifiant de snapshot, le trunk ou une lane par composition_sha256. Chaque entrée indique :

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

Hachez chaque fichier et comparez avec sha256 ; comparez revision_id, content_hash et seal_hash avec le registre. La documentation : avec le manifeste, "a reader can check every file against the record it came from" (un lecteur peut vérifier chaque fichier contre le registre dont il provient). C'est ce qui fait de l'archive une tranche du registre plutôt qu'"a copy that can drift into a second truth." (une copie qui peut dériver en une seconde vérité.)

Étape 7. Ramener les changements par une lane

"A download is read-only by design. Nothing in the archive is read back." (Un téléchargement est en lecture seule par conception. Rien dans l'archive n'est relu.) Pour rapporter un travail fait sur l'archive, écrivez-le par un appel d'outil, placez-le sur une lane et intégrez-la, ou importez-le, afin que chaque changement porte son propre acteur et sa propre intention. Working in lanes décrit la lane, et notre guide Cut a release in Carbon Forge and push it to GitHub (en anglais) décrit comment créer le cut d'où vous exportez.

Ce que la documentation laisse sans réponse

La taille du plafond d'export. Un téléchargement qui le dépasse échoue avec une phrase qui nomme le plafond, mais la documentation n'en donne pas la valeur par défaut.
Combien de temps une download_url reste valide, et combien de temps un export est conservé.
Qui peut modifier .perspectives. Adopter un modèle est une action d'administrateur ; la page elle-même "is edited like any other page" (se modifie comme n'importe quelle autre page), ce qui se lit comme : par tout éditeur.
Un outil pour vérifier une archive contre son manifeste. Le format est décrit ; la vérification est laissée au script du lecteur.

Exporter une tranche déterministe d'un espace de travail avec les perspectives