Documentazione di FabricLoom

Contribuire

Come cartucce e definizioni entrano in MachineFabric

In questa sezione

Panoramica

MachineFabric è un piccolo progetto aperto. Tre cose nel sistema sono curate dalla community, e ognuna ha il proprio flusso di lavoro basato su issue GitHub:

  • Cartucce: eseguibili confezionati che forniscono capacità. Vengono proposte su cartridge-shelf, revisionate dai maintainer e integrate nel manifesto canonico delle cartucce distribuito con ogni installazione di FabricLoom.
  • Capacità: le operazioni nominate che le cartucce possono servire, identificate da URN con tag. Vengono proposte su capfab e pubblicate nel registro CapDAG.
  • Specifiche media: gli input e output tipizzati che le capacità consumano e producono, anch’essi identificati da URN con tag. Seguono lo stesso flusso delle capacità e si propongono su capfab.

Nulla nel sistema viene integrato automaticamente. Un essere umano legge ogni proposta, la discute sull’issue e la integra quando i maintainer sono soddisfatti. Questa pagina spiega in dettaglio il flusso delle cartucce. La guida alla contribuzione di CapDAG copre i flussi delle capacità e delle specifiche media.

Proporre una cartuccia

Proponi una cartuccia

Proponi un URL git pubblico che punta al repository sorgente della cartuccia. Chiunque può proporre una cartuccia, propria o di qualcun altro. I requisiti di inclusione seguono. Se non sei sicuro di qualcuno di essi, proponi comunque e li discuteremo insieme sull’issue.

Requisiti di inclusione

  • Repository pubblico. Le proposte devono essere accessibili pubblicamente senza autenticazione. Repo privati, URL che richiedono autenticazione e archivi compressi non sono accettati. L’URL deve essere un vero URL git pubblico.
  • Forma URL .git. L’URL proposto deve includere il protocollo (di solito https://) e l’estensione .git, per esempio https://github.com/<owner>/<name>.git.
  • Almeno una release con tag che segue il versionamento semantico. Preferiamo cartucce che distribuiscono installer .pkg firmati e notarizzati, ma il minimo è un tag a cui possiamo puntare.
  • Si compila e gira su macOS usando gli strumenti standard per cartucce CapDAG. La cartuccia può essere implementata in qualsiasi linguaggio purché produca un singolo eseguibile che parla il protocollo Bifaci.
  • URN cap validi. Ogni capacità che la cartuccia serve deve avere un URN analizzabile con la libreria capdag, con tag di direzione in e out che fanno riferimento a URN media già nel registro standard. Se la tua cartuccia ha bisogno di una capacità o specifica media che non esiste ancora, proponila su capfab insieme a questa proposta e le revisioneremo insieme.
  • Si comporta correttamente sulla macchina dell’utente. Nessuna esfiltrazione di dati, nessun mining di criptovalute e nessun traffico di rete inatteso. Rifiutiamo le cartucce che violano chiaramente questo requisito e rimuoviamo quelle accettate che si rivelano tali.

Cosa succede dopo

  1. Apri l’issue con uno o più URL di repository e una frase per URL che spiega cosa fa la cartuccia e quali URN cap serve.
  2. Un maintainer apre una PR che aggiunge ogni URL a submitted.txt. L’issue resta aperta durante la revisione. Possiamo fare domande nel thread dell’issue o chiedere modifiche nel tuo repo.
  3. Quando siamo soddisfatti, aggiungiamo la cartuccia al manifesto canonico e spostiamo l’URL da submitted.txt ad accepted.txt. L’issue viene chiusa con un link alla voce live.
  4. Se decidiamo di non accettare una proposta, l’issue viene chiusa con la motivazione. L’issue chiusa è il registro pubblico, e non esiste una lista separata dei rifiuti.

Rimozione di una cartuccia

Rimuovi una cartuccia

Puoi richiedere che una cartuccia accettata venga rimossa dal manifesto. Valutiamo le rimozioni in base al loro impatto. Le cartucce accettate sono referenziate da installazioni attive e dalle notazioni machine salvate dagli utenti, quindi definiamo con te un percorso di deprecazione prima di rimuovere qualcosa in uso attivo. Le richieste dell’autore o del maintainer della cartuccia hanno il peso maggiore. Le richieste degli utenti vengono esaminate più attentamente per valutare se la cartuccia possa essere invece riparata.

Segnalare una vulnerabilità

Segnala una vulnerabilità

Per problemi di sicurezza che riguardano una cartuccia accettata, come esfiltrazione di dati, contatti con host inattesi o altri comportamenti anomali, apri il template di segnalazione. Non includere exploit funzionanti o credenziali in un’issue pubblica. Organizzeremo un canale privato se il problema lo richiede. Di solito rimuoviamo la cartuccia dal manifesto durante l’indagine, poi accettiamo una versione corretta o la lasciamo rimossa.

Bug, funzionalità e domande

Bug, funzionalità o domanda

Qui va tutto ciò che non è una proposta, una rimozione o una segnalazione di sicurezza. Include domande su come funziona lo shelf, suggerimenti per il processo di proposta e bug nei metadati elencati.

Dove si trova il confine tra cartridge-shelf e capfab

I due repo gestiscono superfici diverse:

  • Una cartuccia è un’implementazione: un binario eseguibile che serve una o più capacità. Proponila su cartridge-shelf.
  • Una capacità è un’operazione nominata: un URN come cap:in="media:document;ext=pdf";extract;out=media:enc=utf-8 che descrive cosa può fare un’implementazione. Proponila su capfab.
  • Una specifica media è un payload tipizzato: un URN come media:document;ext=pdf che descrive un tipo di input o output. Proponila su capfab.

Una cartuccia che serve cap non ancora nel registro richiede di solito issue su entrambi i repo. Le issue capfab descrivono le nuove cap e specifiche media, e l’issue cartridge-shelf descrive l’implementazione. I maintainer coordinano le due revisioni in modo che la cartuccia non venga accettata prima degli URN da cui dipende.

Codice di condotta

Sii gentile e utile. Se un maintainer ti chiede di rivedere una proposta, è perché vogliamo integrarla.