Pubblicare su DoliNews
Dall'apertura dell'account al primo articolo pubblicato.
Qui l'informazione è sempre datata: il vostro annuncio indica la compatibilità e la maturità del modulo il giorno in cui lo pubblicate. DoliNews non pretende di descrivere lo stato attuale di un modulo, ma solo ciò che avete annunciato, e quando. La scheda del vostro progetto, invece, è permanente: non porta né compatibilità né maturità.
Due cose da sapere prima di cominciare. Scrivere richiede un account contributore, cioè la prova di aver davvero contribuito all'ecosistema: leggere e abbonarsi no. E ogni annuncio passa dalla revisione: un token d'API dà il diritto di inviare, mai quello di pubblicare. Solo le sue traduzioni vi sfuggono, poiché il testo che traducono è già stato riletto.
1. Aprire l'account
La registrazione è libera e dà un account lettore. Parte subito un'email di verifica: il link che contiene è monouso e attiva l'account.
Usate preferibilmente l'indirizzo con cui firmate i vostri commit. Se quell'indirizzo è già noto all'indice degli autori, il vostro account diventa contributore nel momento stesso in cui verificate l'email, e il passo successivo non vi riguarda.
2. Dimostrare il vostro contributo
La qualificazione è distinta dall'autenticazione: prima esiste l'account, poi arriva la prova. Il servizio cerca il vostro indirizzo di autore dei commit in un indice raccolto da cloni git dei repository di riferimento - mai tramite l'API di una forge, perché la verifica sopravviva alla scomparsa di un fornitore.
Il vostro indirizzo non è mai conservato in chiaro, né nell'indice né sulla prova: viene memorizzata solo la sua impronta con pepe.
Una volta riconosciuto l'indirizzo, resta da dimostrare che è vostro. Due livelli:
- Semplice: un codice monouso viene inviato all'indirizzo di commit, valido un'ora, cinque tentativi.
- Forte: il servizio vi dà una frase da firmare con la chiave GPG che firma i vostri commit; voi incollate la chiave pubblica e la firma.
Tre casi in cui la via semplice non si applica:
- Il vostro indirizzo di commit è una redirezione anonimizzata, del tipo fornito dalle forge: non riceve email, restano la firma GPG o la convalida manuale.
- Il vostro indirizzo non compare in alcun repository di riferimento: chiedete la convalida manuale al team dalla stessa pagina, spiegando la vostra situazione. È la via prevista per gli editori senza repository pubblico.
- Questo indirizzo è già collegato a un altro account: un'impronta qualifica un solo account, e una prova revocata dalla moderazione non viene mai restituita da un automatismo.
3. Dichiarare il vostro editore
L'editore è l'organizzazione o la persona che pubblica; le vostre schede progetto e i vostri annunci gli appartengono. Non si pubblica mai a nome proprio: senza editore non si può inviare nulla. Il modulo di creazione vi viene proposto non appena la vostra prova di contributo è accettata, e resta accessibile in fondo alla pagina dei vostri articoli. Un'integrazione che parte da zero crea piuttosto il suo editore con POST /editors. Siete proprietari dell'editore che create e potete collegarvi altri account contributore, che pubblicheranno con lo stesso nome.
Un editore posseduto per account: il credito di pubblicazione e il tetto della coda si contano per editore. Agli altri ci si unisce su invito del loro proprietario.
4. Creare un token API
Il token serve a pubblicare dalla vostra catena di integrazione, ed è necessario al passo successivo. Chiamatelo secondo il suo uso: il segreto compare una sola volta, alla creazione, e si revoca in qualsiasi momento.
Si usa come intestazione a ogni chiamata. Cominciate col verificare che risponda:
TOKEN="12|..."
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
https://dolinews.com/api/v1/profileLa risposta porta i due valori da cui dipende ogni scrittura: is_contributor e l'elenco dei vostri editori con il loro identificativo. Annotate quell'identificativo, le chiamate successive lo chiedono.
Ritmo: 120 letture e 10 scritture al minuto. Uno script che carica più immagini di seguito deve tenere conto del secondo limite.
5. Creare la scheda del vostro progetto
La scheda descrive il progetto in modo permanente: nome, sintesi, descrizione, licenza, collegamenti tipizzati al repository, alla documentazione, al negozio o al supporto. Non porta alcuna compatibilità Dolibarr, ed è voluto: una scheda resta in piedi per anni, quindi ogni informazione datata che contenesse diventerebbe falsa senza che nessuno la corregga.
La scheda si crea dal vostro conto, o tramite l'API se partite da una catena di integrazione. Un articolo può fare a meno della scheda - sarà allora un annuncio di editore - ma un'uscita di versione merita la sua.
# Créer la fiche
curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"editor_id":3,"name":"Mon module",
"summary":"Ce que fait le module, en une phrase.",
"license":"GPL-3.0-or-later"}' \
https://dolinews.com/api/v1/projects
# Ajouter un lien typé : dolistore, shop, demo, doc, repo, support, other
curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"type":"repo","url":"https://example.org/mon-module","label":"Dépôt git"}' \
https://dolinews.com/api/v1/projects/mon-module/linksGli accorciatori di URL sono rifiutati, e una scheda Dolistore già rivendicata da un altro editore apre un conflitto che la moderazione risolve.
6. Inviare il vostro annuncio
Dal sito, nella pagina dei vostri articoli, oppure dall'API. In entrambi i casi il contenuto è lo stesso, e la sintesi è obbligatoria: è quella che il lettore scorre nel flusso, e la sua assenza è ciò che rende illeggibili la maggior parte dei registri di rilascio.
- Il tipo distingue l'uscita di una versione dall'annuncio di editore; la natura della pubblicazione - sicurezza, correzione, funzionalità, compatibilità, fine vita - vale solo per una versione.
- La maturità va da alfa a obsoleto. Solo le versioni stabili compaiono nel flusso per impostazione predefinita: il lettore chiede il resto esplicitamente.
- La compatibilità con Dolibarr è un intervallo di versioni maggiori, e si dichiara semplicemente oppure come realmente provata. Non dichiarate provato ciò che non avete provato: il filtro per versione dipende da questo.
- Il corpo è in Markdown. I collegamenti in uscita portano tutti nofollow, e solo le immagini caricate sul servizio possono illustrare un articolo.
Un annuncio illustrato si pubblica in due tempi: caricare le immagini, poi creare l'articolo citandone gli indirizzi nel corpo e gli identificativi in media_ids. Senza quegli identificativi le immagini restano orfane e vengono cancellate dopo ventiquattro ore.
# 1. Déposer une capture. Elle est ré-encodée, ses métadonnées disparaissent.
curl -H "Authorization: Bearer $TOKEN" \
-F file=@capture.png -F editor_id=3 -F alt="Écran de configuration" \
https://dolinews.com/api/v1/media
# 2. Créer l'article et le soumettre dans le même appel
curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"editor_id":3,"project_id":7,"type":"release",
"title":"Mon module 2.1","version":"2.1.0","locale":"fr_FR",
"focus":"bugfix_major","maturity":"stable","dolibarr_min":20,
"summary":"Ce que cette version change, en quelques lignes.",
"body":"## Corrections\n\n",
"media_ids":[42],"submit":true}' \
https://dolinews.com/api/v1/articlesUna schermata di un Dolibarr in servizio contiene quasi sempre dati reali - soggetti, importi, indirizzi. Ripulitela prima di inviarla.
L'immagine in evidenza è quella che il flusso, la scheda di condivisione e i feed mostrano per il vostro annuncio: sceglietela con featured_media_id tra le immagini del vostro editore, oppure con la riga image: dell'intestazione se usate lo strumento di pubblicazione. Viene revisionata con l'annuncio, e cambiarla dopo la pubblicazione passa per una revisione. Senza di essa viene mostrata la prima immagine del testo; una traduzione mostra quella dell'originale.
Due limiti proteggono la coda: un ritmo di pubblicazione per progetto e un tetto di annunci dello stesso editore contemporaneamente in revisione. Un annuncio e le sue traduzioni contano per uno.
7. La revisione, e quel che segue
Il vostro articolo entra in coda e tre moderatori devono accettarlo perché esca. Gli scambi avvengono in un filo privato tra voi e il team: lì rispondete, correggete, inviate di nuovo. Modificare un articolo in attesa apre un nuovo giro di revisione, perché un consenso riguarda un testo preciso.
Non viene annunciato alcun tempo, e non è una dimenticanza: impegnarsi sul tempo libero di volontari trasformerebbe ogni ritardo in un'inadempienza. La pagina della revisione mostra il tempo realmente osservato e l'attesa più vecchia. Un annuncio di sicurezza passa avanti.
Una volta pubblicato, un articolo non si modifica più sul posto: lei propone una revisione, che ripassa dalla revisione, l'articolo porta la menzione della sua correzione e la versione originale resta consultabile. Una traduzione è un articolo a pieno titolo, legata al suo originale: quella che deposita lei stesso appare senza revisione, quella di un traduttore da lei incaricato passa davanti a un revisore; un annuncio non tradotto non è mai svantaggiato nella diffusione.