Publikowanie w DoliNews
Od założenia konta do pierwszego opublikowanego artykułu.
Tutaj informacja jest zawsze opatrzona datą: twoje ogłoszenie podaje zgodność i dojrzałość modułu w dniu publikacji. DoliNews nie twierdzi, że opisuje bieżący stan modułu, mówi tylko, co ogłosiłeś i kiedy. Karta twojego projektu jest natomiast trwała: nie niesie ani zgodności, ani dojrzałości.
Dwie rzeczy warto wiedzieć na początek. Pisanie wymaga konta współtwórcy, czyli dowodu, że rzeczywiście wniosłeś wkład w ekosystem: czytanie i subskrypcja nie wymagają. I każde ogłoszenie przechodzi recenzję: token API daje prawo zgłoszenia, nigdy publikacji. Wymykają się jej tylko jego tłumaczenia, ponieważ tłumaczony tekst został już sprawdzony.
1. Założyć konto
Rejestracja jest wolna i daje konto czytelnika. Od razu wychodzi e-mail weryfikacyjny: zawarty w nim odnośnik jest jednorazowy i aktywuje konto.
Użyj najlepiej adresu, którym podpisujesz commity. Jeśli indeks autorów już go zna, twoje konto staje się kontem współtwórcy w chwili potwierdzenia e-maila, a następny krok cię nie dotyczy.
2. Wykazać swój wkład
Kwalifikacja to co innego niż uwierzytelnienie: najpierw istnieje konto, potem przychodzi dowód. Serwis szuka twojego adresu autora commitów w indeksie zebranym z klonów git repozytoriów odniesienia - nigdy przez API kuźni, żeby weryfikacja przetrwała zniknięcie danego hostingu.
Twój adres nigdy nie jest przechowywany jawnie, ani w indeksie, ani przy dowodzie: zapisany jest tylko jego odcisk z pieprzem.
Gdy adres zostanie rozpoznany, zostaje wykazać, że należy do ciebie. Dwa poziomy:
- Prosty: na adres commitów wysyłany jest kod jednorazowy, ważny godzinę, pięć prób.
- Silny: serwis daje ci zdanie do podpisania kluczem GPG, którym podpisujesz commity; wklejasz swój klucz publiczny i podpis.
Trzy przypadki, w których prosta droga nie działa:
- Twój adres commitów to zanonimizowane przekierowanie, jakie dają kuźnie: nie odbiera poczty, zostają podpis GPG albo zatwierdzenie ręczne.
- Twojego adresu nie ma w żadnym repozytorium odniesienia: poproś zespół o ręczne zatwierdzenie na tej samej stronie, wyjaśniając swoją sytuację. To droga przewidziana dla wydawców bez publicznego repozytorium.
- Ten adres jest już powiązany z innym kontem: jeden odcisk kwalifikuje tylko jedno konto, a dowód cofnięty przez moderację nigdy nie wraca automatycznie.
3. Zgłosić swojego wydawcę
Wydawca to organizacja albo osoba, która publikuje; twoje karty projektów i twoje ogłoszenia należą do niego. Nigdy nie publikuje się we własnym imieniu: bez wydawcy nic nie da się zgłosić. Formularz tworzenia pojawia się, gdy tylko twój dowód wkładu zostanie przyjęty, i pozostaje dostępny na dole strony twoich artykułów. Integracja zaczynająca od zera tworzy swojego wydawcę raczej przez POST /editors. Jesteś właścicielem wydawcy, którego tworzysz, i możesz podłączyć do niego inne konta współtwórców, które będą publikować pod tą samą nazwą.
Jeden własny wydawca na konto: kredyt publikacji i pułap kolejki liczy się na wydawcę. Do pozostałych dołącza się na zaproszenie właściciela.
4. Utworzyć token API
Token służy do publikowania z twojego łańcucha integracji i jest potrzebny w następnym kroku. Nazwij go według zastosowania: sekret pokazuje się tylko raz, przy tworzeniu, i można go cofnąć w każdej chwili.
Używa się go jako nagłówka przy każdym wywołaniu. Zacznij od sprawdzenia, czy odpowiada:
TOKEN="12|..."
curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
https://dolinews.com/api/v1/profileOdpowiedź niesie dwie wartości, od których zależy każdy zapis: is_contributor oraz listę twoich wydawców z ich identyfikatorem. Zapisz ten identyfikator, kolejne wywołania o niego proszą.
Tempo: 120 odczytów i 10 zapisów na minutę. Skrypt wysyłający kilka obrazów pod rząd musi uwzględnić ten drugi limit.
5. Utworzyć kartę swojego projektu
Karta opisuje projekt trwale: nazwa, streszczenie, opis, licencja, otypowane odnośniki do repozytorium, dokumentacji, sklepu lub wsparcia. Nie niesie żadnej zgodności z Dolibarr i jest to zamierzone: karta zostaje na lata, więc każda zawarta w niej informacja z datą stałaby się nieprawdziwa, a nikt by jej nie poprawił.
Kartę tworzy się ze swojego konta lub przez API, jeśli wychodzisz od łańcucha integracji. Artykuł może obejść się bez karty - będzie wtedy ogłoszeniem wydawcy - ale wydanie wersji zasługuje na własną.
# 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/linksSkracacze adresów są odrzucane, a karta Dolistore już zgłoszona przez innego wydawcę wywołuje konflikt, który rozstrzyga moderacja.
6. Zgłosić swoje ogłoszenie
Przez stronę, z widoku twoich artykułów, albo przez API. W obu wypadkach treść jest ta sama, a streszczenie jest obowiązkowe: to je czytelnik przegląda w strumieniu, a jego brak sprawia, że większość dzienników zmian jest nieczytelna.
- Typ odróżnia wydanie wersji od ogłoszenia wydawcy; charakter publikacji - bezpieczeństwo, poprawka, funkcja, zgodność, koniec wsparcia - dotyczy tylko wersji.
- Dojrzałość sięga od alfa do przestarzałej. Domyślnie w strumieniu pojawiają się tylko wersje stabilne: resztę czytelnik wywołuje wprost.
- Zgodność z Dolibarr to zakres wersji głównych, deklarowany zwyczajnie albo jako naprawdę sprawdzony. Nie deklaruj jako sprawdzonego tego, czego nie próbowałeś: zależy od tego filtr po wersji.
- Treść jest w Markdown. Wszystkie odnośniki wychodzące mają nofollow, a artykuł mogą ilustrować tylko obrazy wysłane do serwisu.
Ilustrowane ogłoszenie publikuje się w dwóch krokach: wysłać obrazy, a potem utworzyć artykuł, podając ich adresy w treści, a identyfikatory w media_ids. Bez tych identyfikatorów obrazy zostają osierocone i po dwudziestu czterech godzinach są kasowane.
# 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/articlesZrzut ekranu z działającego Dolibarr prawie zawsze zawiera prawdziwe dane - kontrahentów, kwoty, adresy. Oczyść go przed wysłaniem.
Obraz wyróżniający to obraz, który strumień, karta udostępniania i kanały pokazują przy Twoim ogłoszeniu: wskaż go przez featured_media_id spośród obrazów Twojego wydawcy albo wierszem image: w nagłówku, jeśli korzystasz z narzędzia do publikacji. Jest weryfikowany razem z ogłoszeniem, a jego zmiana po publikacji przechodzi przez rewizję. Bez niego pokazywany jest pierwszy obraz z treści; tłumaczenie pokazuje obraz oryginału.
Kolejkę chronią dwa limity: tempo publikacji na projekt oraz pułap ogłoszeń tego samego wydawcy jednocześnie w recenzji. Ogłoszenie i jego tłumaczenia liczą się jako jedno.
7. Recenzja i to, co dalej
Twój artykuł trafia do kolejki i trzech moderatorów musi go przyjąć, żeby się ukazał. Rozmowa toczy się w prywatnym wątku między tobą a zespołem: tam odpowiadasz, poprawiasz, zgłaszasz ponownie. Zmiana oczekującego artykułu otwiera nową turę recenzji, bo zgoda dotyczy konkretnego tekstu.
Nie ogłaszamy żadnego terminu i nie jest to przeoczenie: zobowiązanie oparte na wolnym czasie ochotników zmieniałoby każde opóźnienie w uchybienie. Strona recenzji pokazuje czas rzeczywiście zaobserwowany i najdłuższe oczekiwanie. Ogłoszenie o bezpieczeństwie idzie przed innymi.
Po opublikowaniu artykułu nie zmienia się go w miejscu: proponujesz poprawkę, która ponownie przechodzi recenzję, artykuł nosi wzmiankę o swojej korekcie, a pierwotna wersja pozostaje dostępna. Tłumaczenie jest pełnoprawnym artykułem, powiązanym ze swoim oryginałem: to, które składasz sam, ukazuje się bez recenzji, a to od tłumacza, któremu powierzyłeś mandat, przechodzi przez jednego recenzenta; nieprzetłumaczone ogłoszenie nigdy nie jest upośledzone w dystrybucji.