Publicar no DoliNews
Da abertura da conta ao primeiro artigo publicado.
Aqui a informação está sempre datada: o seu anúncio indica a compatibilidade e a maturidade do módulo no dia em que o publica. O DoliNews não pretende descrever o estado atual de um módulo, apenas o que anunciou, e quando. A ficha do seu projeto, essa, é permanente: não leva compatibilidade nem maturidade.
Duas coisas a saber antes de começar. Escrever exige uma conta contribuidora, ou seja a prova de que contribuiu realmente para o ecossistema: ler e subscrever não exigem. E todo o anúncio passa pela revisão: um token de API dá o direito de submeter, nunca o de publicar. Só as suas traduções lhe escapam, pois o texto que traduzem já foi revisto.
1. Abrir a conta
O registo é livre e dá uma conta de leitor. Um email de verificação parte de imediato: a ligação que contém é de uso único e ativa a conta.
Use de preferência o endereço com que assina os seus commits. Se esse endereço já é conhecido do índice de autores, a sua conta passa a contribuidora no momento em que verifica o email, e o passo seguinte não lhe diz respeito.
2. Provar a sua contribuição
A qualificação é distinta da autenticação: a conta existe primeiro, a prova vem depois. O serviço procura o seu endereço de autor de commits num índice recolhido de clones git dos repositórios de referência - nunca pela API de uma forja, para que a verificação sobreviva ao desaparecimento de um alojamento.
O seu endereço nunca é guardado em claro, nem no índice nem na prova: só é armazenada a sua impressão com pimenta.
Uma vez reconhecido o endereço, falta provar que é seu. Dois níveis:
- Simples: é enviado um código de uso único para o endereço de commit, válido uma hora, cinco tentativas.
- Forte: o serviço dá-lhe uma frase para assinar com a chave GPG que assina os seus commits; cola a sua chave pública e a assinatura.
Três casos em que a via simples não se aplica:
- O seu endereço de commit é um reencaminhamento anonimizado, do tipo que as forjas fornecem: não recebe email, restam a assinatura GPG ou a validação manual.
- O seu endereço não aparece em nenhum repositório de referência: peça a validação manual à equipa a partir dessa mesma página, explicando a sua situação. É a via prevista para os editores sem repositório público.
- Este endereço já está ligado a outra conta: uma impressão qualifica apenas uma conta, e uma prova revogada pela moderação nunca é devolvida por um automatismo.
3. Declarar o seu editor
O editor é a organização ou a pessoa que publica; as suas fichas de projeto e os seus anúncios pertencem-lhe. Nunca se publica em nome próprio: sem editor, nada pode ser submetido. O formulário de criação é-lhe proposto assim que a sua prova de contribuição é aceite, e continua acessível no fundo da página dos seus artigos. Uma integração que parte do zero cria antes o seu editor com POST /editors. É proprietário do editor que cria e pode ligar-lhe outras contas de contribuidor, que publicarão com o mesmo nome.
Um editor em propriedade por conta: o crédito de publicação e o teto da fila contam-se por editor. Aos outros junta-se por convite do seu proprietário.
4. Criar um token de API
O token serve para publicar a partir da sua cadeia de integração, e é necessário no passo seguinte. Dê-lhe o nome do seu uso: o segredo só aparece uma vez, na criação, e revoga-se a qualquer momento.
Usa-se como cabeçalho em cada chamada. Comece por verificar que responde:
TOKEN="12|..."
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
https://dolinews.com/api/v1/profileA resposta traz os dois valores de que depende toda a escrita: is_contributor, e a lista dos seus editores com o respetivo identificador. Anote esse identificador, as chamadas seguintes pedem-no.
Ritmo: 120 leituras e 10 escritas por minuto. Um script que envia várias imagens seguidas tem de contar com o segundo limite.
5. Criar a ficha do seu projeto
A ficha descreve o projeto de forma permanente: nome, resumo, descrição, licença, ligações tipificadas ao repositório, à documentação, à loja ou ao suporte. Não leva qualquer compatibilidade Dolibarr, e é deliberado: uma ficha permanece durante anos, por isso qualquer informação datada que contivesse tornar-se-ia falsa sem que ninguém a corrigisse.
A ficha cria-se a partir da sua conta, ou pela API se partir de uma cadeia de integração. Um artigo pode dispensar ficha - será então um anúncio de editor - mas um lançamento de versão merece a 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/linksOs encurtadores de URL são recusados, e uma ficha Dolistore já reivindicada por outro editor gera um conflito que a moderação resolve.
6. Submeter o seu anúncio
Pelo site, na página dos seus artigos, ou pela API. Nos dois casos o conteúdo é o mesmo, e o resumo é obrigatório: é ele que o leitor percorre no fio, e a sua ausência é o que torna ilegíveis a maioria dos registos de lançamento.
- O tipo distingue o lançamento de versão do anúncio de editor; a natureza da publicação - segurança, correção, funcionalidade, compatibilidade, fim de vida - só vale para uma versão.
- A maturidade vai de alfa a obsoleto. Só as versões estáveis aparecem no fio por omissão: o leitor pede o resto explicitamente.
- A compatibilidade com o Dolibarr é um intervalo de versões maiores, e declara-se simplesmente ou como realmente testada. Não declare testado o que não experimentou: o filtro por versão depende disso.
- O corpo é em Markdown. As ligações externas levam todas nofollow, e só as imagens enviadas para o serviço podem ilustrar um artigo.
Um anúncio ilustrado publica-se em dois tempos: enviar as imagens, depois criar o artigo citando os seus endereços no corpo e os seus identificadores em media_ids. Sem esses identificadores, as imagens ficam órfãs e são apagadas ao fim de vinte e quatro horas.
# 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/articlesUma captura de um Dolibarr em serviço contém quase sempre dados reais - terceiros, montantes, moradas. Limpe-a antes de a enviar.
A imagem em destaque é a que o fio, o cartão de partilha e os feeds mostram para o seu anúncio: designe-a com featured_media_id entre as imagens do seu editor, ou com a linha image: do cabeçalho se usar a ferramenta de publicação. É revista com o anúncio, e alterá-la após a publicação passa por uma revisão. Sem ela, mostra-se a primeira imagem do corpo; uma tradução mostra a do original.
Dois limites protegem a fila: um ritmo de publicação por projeto, e um teto de anúncios do mesmo editor em revisão ao mesmo tempo. Um anúncio e as suas traduções contam como um.
7. A revisão, e o que se segue
O seu artigo entra na fila e três moderadores têm de o aceitar para que apareça. As trocas fazem-se num fio privado entre si e a equipa: responde lá, corrige, volta a submeter. Alterar um artigo em espera abre uma nova volta de revisão, porque um acordo incide sobre um texto preciso.
Não se anuncia qualquer prazo, e não é um esquecimento: comprometer-se com o tempo livre de voluntários transformaria cada atraso num incumprimento. A página da revisão mostra o prazo realmente observado e a espera mais antiga. Um anúncio de segurança passa à frente.
Uma vez publicado, um artigo não se modifica no lugar: propõe uma revisão, que volta a passar pela revisão, o artigo leva a menção da sua correção e a versão de origem continua acessível. Uma tradução é um artigo por direito próprio, ligada ao seu original: a que submete você mesmo aparece sem revisão, a de um tradutor que mandatou passa por um revisor; um anúncio não traduzido nunca é desfavorecido na difusão.