Contribuire

Chiunque può proporre una nuova capacità o definizione di media per il registro di CapDAG. Il registro è curato dalla comunità, e una definizione ben formata, che colma una lacuna reale ed è documentata in modo abbastanza chiaro da poter essere usata da altri, è candidata all’inclusione. Le proposte si fanno tramite l’issue tracker di GitHub del repository capfab. Il registro della fabric pubblicato è il riferimento canonico per le definizioni attive.

Come funzionano le proposte

Non c’è alcun merge automatico. Ogni proposta viene letta da un maintainer; lavoriamo con chi l’ha inviata per sistemare eventuali imperfezioni; e una volta che la forma è corretta, la nuova definizione compare nel registro versionato e su capdag.com.

Si invia JSON. Consulta capdag.com per esempi attivi di definizioni accettate. Gli schemi delle proposte si trovano in cap.schema.json e media.schema.json.

Che cosa inviare

Apri una issue su capfab usando uno dei template qui sotto.

L’elenco completo dei template è su github.com/machinefabric/capfab/issues/new/choose.

Che cosa rende valida la proposta di una capacità

• Un’operazione reale e distinta. Non riproporre una capacità esistente con tag cosmetici. Input, output, tag dell’operazione ed effetto partecipano tutti al contratto di CapDAG; vedi Predicati e Struttura dei cap URN.
• Una documentazione che dica quando usarla e quando no. Gli utenti finali scoprono le capacità leggendo il campo documentation su capdag.com. Una riga spoglia come “converte X in Y” non dà loro abbastanza elementi per decidere. Spiega quale passo a monte produce questo genere di cosa, quale passo a valle consuma l’output e con quali capacità vicine potrebbero confonderla.
• Una forma degli argomenti che segua gli schemi consolidati. Esamina le definizioni attive simili su capdag.com prima di scrivere la tua.
• Un URN che superi la revisione. Gli URN sono tagged URN; una volta pubblicato, l’URN è la chiave permanente. Scegliere fin dall’inizio i tag giusti è importante.

Che cosa rende valida la proposta di una media def

• Un tipo con una forma chiara e un ruolo chiaro. Le specifiche che si sovrappongono molto a una esistente verranno rimandate indietro perché vengano unite. Se pensi di aver bisogno di una nuova specifica, spiega nella motivazione perché una specifica esistente non va bene: quale flusso viene bloccato, quale tipo esistente è troppo generico o troppo specifico.
• Un media_type, un title e un blocco documentation. La documentation dovrebbe spiegare quando usare questo tipo rispetto ai tipi vicini, non soltanto descrivere che cosa rappresenta preso da solo.
• Estensioni stabili, se pertinenti. Per i tipi di media legati a formati di file, elenca in extensions le estensioni di file canoniche, così che l’acquisizione basata su file possa associare il tipo in base all’estensione.

Rimozioni e modifiche

Le rimozioni vengono valutate in base al loro impatto. Le definizioni del registro sono referenziate da cartucce già distribuite, da pagine pubblicate su capdag.com e dalle notazioni delle macchine salvate dagli utenti. Concorderemo con te un percorso di deprecazione prima di rimuovere qualsiasi cosa sia in uso attivo.

Le modifiche cambiano i metadati di una definizione (titolo, documentazione, tipo di contenuto, estensioni) ma non ne cambiano mai l’URN. L’URN è la chiave permanente; rinominare un URN non è una modifica, è una rimozione più una nuova aggiunta.

Che cosa è fuori ambito

• Implementazioni delle capacità. Il registro capfab è un elenco di definizioni di capacità e di media, non un luogo in cui pubblicare cartucce o implementazioni. Le cartucce vengono distribuite separatamente. Una capacità può esistere nel registro prima che ne esista una qualsiasi implementazione.

Comportamento

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