Publiceren op DoliNews
Van het openen van het account tot het eerste gepubliceerde artikel.
Hier is informatie altijd gedateerd: uw aankondiging vermeldt de compatibiliteit en de rijpheid van de module op de dag dat u ze publiceert. DoliNews beweert niet de huidige toestand van een module te beschrijven, alleen wat u hebt aangekondigd, en wanneer. De fiche van uw project is daarentegen blijvend: ze draagt compatibiliteit noch rijpheid.
Twee dingen om te weten voor u begint. Schrijven vereist een bijdragersaccount, dat wil zeggen een bewijs dat u werkelijk aan het ecosysteem hebt bijgedragen: lezen en abonneren niet. En elke aankondiging gaat door de beoordeling: een API-token geeft het recht in te dienen, nooit het recht te publiceren. Alleen haar vertalingen ontsnappen eraan, omdat de tekst die zij vertalen al is nagelezen.
1. Het account openen
Registreren is vrij en levert een lezersaccount op. Er vertrekt meteen een verificatiemail: de link erin is eenmalig en activeert het account.
Gebruik bij voorkeur het adres waarmee u uw commits ondertekent. Is dat adres al bekend bij de auteursindex, dan wordt uw account bijdragersaccount op het moment dat u de e-mail bevestigt, en de volgende stap gaat u niet aan.
2. Uw bijdrage aantonen
Kwalificatie staat los van authenticatie: eerst bestaat het account, daarna komt het bewijs. De dienst zoekt uw commit-auteursadres in een index die uit git-klonen van de referentierepository's is verzameld - nooit via de API van een forge, zodat de verificatie het verdwijnen van een hoster overleeft.
Uw adres wordt nooit leesbaar bewaard, niet in de index en niet bij het bewijs: alleen de gepeperde hash wordt opgeslagen.
Zodra het adres is herkend, moet u nog aantonen dat het van u is. Twee niveaus:
- Eenvoudig: er gaat een eenmalige code naar het commit-adres, een uur geldig, vijf pogingen.
- Sterk: de dienst geeft u een zin om te ondertekenen met de GPG-sleutel die uw commits ondertekent; u plakt uw publieke sleutel en de handtekening.
Drie gevallen waarin de eenvoudige weg niet opgaat:
- Uw commit-adres is een geanonimiseerde doorstuuradres, zoals forges die uitdelen: het ontvangt geen e-mail, dus blijven de GPG-handtekening of de handmatige goedkeuring over.
- Uw adres komt in geen enkele referentierepository voor: vraag het team op diezelfde pagina om handmatige goedkeuring en leg uw situatie uit. Dat is de weg voor uitgevers zonder publieke repository.
- Dit adres hoort al bij een ander account: een hash kwalificeert maar één account, en een door de moderatie ingetrokken bewijs wordt nooit door een automatisme teruggegeven.
3. Uw uitgever aanmelden
De uitgever is de organisatie of de persoon die publiceert; uw projectfiches en uw aankondigingen horen bij hem. Men publiceert nooit op eigen naam: zonder uitgever kan er niets worden ingediend. Het aanmaakformulier verschijnt zodra uw bijdragebewijs is aanvaard, en blijft bereikbaar onderaan de pagina van uw artikelen. Een integratie die bij nul begint maakt haar uitgever eerder aan met POST /editors. U bent eigenaar van de uitgever die u aanmaakt en kunt er andere bijdragersaccounts aan koppelen, die onder dezelfde naam zullen publiceren.
Eén eigen uitgever per account: het publicatietegoed en het maximum van de wachtrij tellen per uitgever. Bij andere komt men op uitnodiging van hun eigenaar.
4. Een API-token aanmaken
Het token dient om te publiceren vanuit uw integratieketen, en is nodig bij de volgende stap. Noem het naar zijn gebruik: het geheim verschijnt maar één keer, bij het aanmaken, en is op elk moment in te trekken.
Het gaat als header mee bij elke aanroep. Controleer eerst of het antwoordt:
TOKEN="12|..."
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
https://dolinews.com/api/v1/profileHet antwoord bevat de twee waarden waarvan elke schrijfactie afhangt: is_contributor, en de lijst van uw uitgevers met hun identificator. Noteer die identificator, de volgende aanroepen vragen erom.
Tempo: 120 leesacties en 10 schrijfacties per minuut. Een script dat meerdere afbeeldingen achter elkaar uploadt moet rekening houden met de tweede grens.
5. De fiche van uw project aanmaken
De fiche beschrijft het project blijvend: naam, samenvatting, beschrijving, licentie, getypeerde links naar de repository, de documentatie, de winkel of de ondersteuning. Ze draagt geen Dolibarr-compatibiliteit, en dat is bewust: een fiche blijft jarenlang staan, dus elke gedateerde informatie erin zou onwaar worden zonder dat iemand die corrigeert.
De fiche wordt vanuit uw account aangemaakt, of via de API als u van een integratieketen vertrekt. Een artikel kan zonder fiche - het is dan een uitgeversaankondiging - maar een versie-uitgave verdient de hare.
# 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/linksURL-verkorters worden geweigerd, en een Dolistore-fiche die al door een andere uitgever is opgeëist leidt tot een conflict dat de moderatie beslecht.
6. Uw aankondiging indienen
Via de site op de pagina van uw artikelen, of via de API. In beide gevallen is de inhoud dezelfde, en de samenvatting is verplicht: zij is wat de lezer in de stroom doorneemt, en haar afwezigheid maakt de meeste release-logboeken onleesbaar.
- Het type onderscheidt de versie-uitgave van de uitgeversaankondiging; de aard van de publicatie - beveiliging, correctie, functie, compatibiliteit, einde levensduur - geldt alleen voor een versie.
- De rijpheid loopt van alfa tot verouderd. Alleen stabiele versies verschijnen standaard in de stroom: de lezer vraagt de rest uitdrukkelijk op.
- De Dolibarr-compatibiliteit is een reeks hoofdversies, en wordt eenvoudig opgegeven of als werkelijk beproefd. Geef niet als beproefd op wat u niet hebt geprobeerd: het versiefilter hangt ervan af.
- De tekst is Markdown. Uitgaande links dragen allemaal nofollow, en alleen afbeeldingen die naar de dienst zijn geüpload mogen een artikel illustreren.
Een geïllustreerde aankondiging verschijnt in twee stappen: de afbeeldingen uploaden, daarna het artikel aanmaken met hun adressen in de tekst en hun identificatoren in media_ids. Zonder die identificatoren blijven de afbeeldingen ouderloos en worden ze na vierentwintig uur gewist.
# 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/articlesEen schermafbeelding van een draaiende Dolibarr bevat bijna altijd echte gegevens - relaties, bedragen, adressen. Maak ze schoon voordat u ze verstuurt.
De uitgelichte afbeelding is de afbeelding die de stroom, de deelkaart en de feeds bij uw aankondiging tonen: wijs haar aan met featured_media_id uit de afbeeldingen van uw uitgever, of met de regel image: in de kop als u het publicatiehulpmiddel gebruikt. Ze wordt samen met de aankondiging beoordeeld, en haar na publicatie wijzigen gaat via een revisie. Zonder uitgelichte afbeelding wordt de eerste afbeelding uit de tekst getoond; een vertaling toont die van het origineel.
Twee grenzen beschermen de wachtrij: een publicatietempo per project, en een maximum aan aankondigingen van dezelfde uitgever die tegelijk in beoordeling zijn. Een aankondiging en haar vertalingen tellen als één.
7. De beoordeling, en wat daarna komt
Uw artikel komt in de wachtrij en drie moderatoren moeten het aanvaarden voordat het verschijnt. Het overleg loopt in een besloten draad tussen u en het team: daar antwoordt u, verbetert u, dient u opnieuw in. Een wachtend artikel wijzigen opent een nieuwe beoordelingsronde, want een akkoord slaat op een bepaalde tekst.
Er wordt geen termijn toegezegd, en dat is geen vergetelheid: je vastleggen op de vrije tijd van vrijwilligers zou van elke vertraging een tekortkoming maken. De beoordelingspagina toont de werkelijk waargenomen termijn en de langste wachttijd. Een veiligheidsaankondiging gaat voor.
Eenmaal gepubliceerd wordt een artikel nooit ter plaatse gewijzigd: u stelt een herziening voor, die opnieuw door de beoordeling gaat, het artikel draagt de vermelding van zijn correctie en de oorspronkelijke versie blijft raadpleegbaar. Een vertaling is een volwaardig artikel, verbonden met zijn origineel: die u zelf indient verschijnt zonder beoordeling, die van een vertaler die u hebt gemandateerd gaat langs een beoordelaar; een onvertaalde aankondiging wordt in de verspreiding nooit benadeeld.