Niniejsze repozytorium służy do zarządzania treścią wiadomości z tzw. webhooków na serwerze Discord Przygody Reksia (kanały takie jak #regulamin, #info, #faq itd.). Służy również jako zapis historii zmian.
Zawartość wiadomości z repozytorium jest automatycznie wgrywana na serwer, ale w ściśle określonym momencie, o którym będzie napisane później. Na razie zostawiam Cię z wiedzą, że podążając kolejnymi krokami przewodnika nie musisz się obawiać, że coś przypadkiem zepsujesz albo przedwcześnie opublikujesz.
Przypisy zawierają mało istotne informacje z punktu widzenia edytora. Polecam przeczytać je na sam koniec, żeby się nie rozpraszać.
Dane wiadomości przechowywane są w folderze data. Mają strukturę hierarchiczną, co (mam nadzieję) ułatwia nawigację.
Każdy podfolder folderu data (np. info) przechowuje powiązany tematycznie zestaw wiadomości. Przyjmijmy, że odpowiada to definicji kanału1.
W każdym folderze kanału poszczególne wiadomości zawarte są wewnątrz folderów ponumerowanych po kolei. Dla info np. 001_spis-tresci, 002_kanaly, 003_watki itd.2 3
W folderze powiązanym z konkretną wiadomością można znaleźć4 następujące pliki i podfoldery:
- plik
content.md- zawartość wiadomości; jest w formacie Markdown5 - plik
references.txt- linki do powiązanych wiadomości na Discordzie, na których ma być wykonana edycja; jeśli chcemy stworzyć nową wiadomość, to ten plik pomijamy - folder
embeds- podfolder opisujący kolejne embedy (struktura opisana niżej); znowu numerowane:01,02,03itd.2 - folder
attachments- podfolder na załączniki; tutaj po prostu wrzucamy pliki i numerki umieszczamy na początku ich nazwy, np.01_DoubleCounter_verify.png
W folderze powiązanym z pojedynczym embedem (tj. w numerowanym podfolderze wewnątrz folderu embeds) można znaleźć4 następujące pliki:
- plik
title.md- tytuł; jest w formacie Markdown5 - plik
description.md- treść embeda; jest w formacie Markdown5 - plik
color.txt- kolor ramki embeda; wartość w formacie hex, czyli np.#FF0000to czerwony - można sobie podejrzeć np. na tej stronie - plik
url.txt- link skojarzony z embedem - otwiera się, jak się kliknie tytuł embeda (przykład: strony fandomowe we #współpraca-partners) - plik
thumbnail.txt- link do obrazka wyświetlanego z boku embeda w roli ikony (przykład: strony fandomowe we #współpraca-partners)
Wystarczy wpisać w wiadomości na Discordzie np. oznaczenie użytkownika, a następnie poprzedzić je znakiem ucieczki: \. Mamy do tego kanał #testy-i-weryfikacje.
Przykłady:
\@dove6 -> <@450069032968650762>
\@Pani Administrator -> <@&1224305247695147079>
\#testy-i-weryfikacje -> <#909039526599622696>
\:szloch: -> <:szloch:909063765520171109>
Działamy w obrębie GitHuba, co pozwala na śledzenie historii zmian i wzajemną kontrolę poprzez komentarze. Jednocześnie wymaga to jednak wpasowania się w ramy obowiązującego systemu. Niniejsza instrukcja ma za zadanie właśnie wyłożyć krok po kroku, w jaki sposób edytuje się tu rzeczy.
Gałąź (ang. branch) to taka prywatna6 piaskownica, w której możemy sobie wykonywać przeróżne zmiany do momentu, aż nam się spodoba, uznamy robotę za skończoną i będziemy mogli przedstawić pracę do oceny.
Aby utworzyć nową gałąź, należy kliknąć przycisk z symbolem gałęzi w lewym górnym rogu strony (jak na obrazku powyżej). Wpisujemy wymyśloną dla gałęzi nazwę. Unikalną, ale najlepiej-krotka-i-bez-polskich-znakow. Nazwę musimy zapamiętać, żeby później móc na tę gałąź się przełączać i na niej pracować. Jak już wpiszemy nazwę (:warning: ważne, bo wcześniej przycisk się nie pokaże), to klikamy "Create branch ... from main":
To, że pracujemy obecnie na konkretnej gałęzi możemy poznać po tym, że jej nazwa wyświetla się na przycisku gałęzi w lewym górnym rogu:
Należy zwracać uwagę na to, żeby pracować na konkretnej gałęzi, a nie na głównej gałęzi main. Aby przełączyć się na wybraną gałąź, wpisujemy jej nazwę w wyszukiwarkę i wybieramy:
Przyjmijmy, że chcemy zmienić kolor pierwszego embeda w drugiej wiadomości w FAQ. Szukamy odpowiedniego pliku (data/faq/002_sekcja-wstepna/embeds/01/color.txt).
Następnie klikamy ikonę ołówka "✏️" w prawym górnym rogu widoku zawartości pliku:
i dokonujemy zmian w treści. Po wszystkim należy zapisać zmiany zielonym przyciskiem "Commit changes...":
W pole "Commit message" wpisujemy krótki, zwięzły opis zmian (normalnie po polsku), a w "Extended description" można dodać jakieś szczegóły, ale nie trzeba. Zatwierdzamy zielonym przyciskiem "Commit changes":
Jeśli chcemy stworzyć nowy plik, to przechodzimy do folderu, w którym ma być umieszczony, a następnie klikamy przycisk "Add file" i wybieramy "Create new file":
Otworzy nam się widok edytora. Pierwsze, co musimy zrobić, to podać nazwę nowego pliku:
/). Np. wpisanie 02/description.md spowoduje utworzenie nowego folderu 02, a w nim pliku description.md:
Nie trzeba wpisywać całej ścieżki (np. przygody-reksia-discord-webhooks/data/faq/002/embeds/02/description.md), tylko nowy kawałek (np. 02/description.md).
Dalej procedura przebiega jak przy modyfikacji: wpisujemy coś w treść i zapisujemy poprzez "Commit changes...".
Musimy najpierw znaleźć dany plik. Jak już będziemy mieć widok na jego treść, to otwieramy menu "..." w prawym górnym rogu i wybieramy "Delete file":
Przechodzimy do strony z listą gałęzi: https://github.com/PrzygodyReksiaDiscord/webhooks/branches
(Można na nią trafić, klikając na stronie głównej przycisk "Branches":
Korzystamy z wyszukiwarki, żeby znaleźć wybraną gałąź. Następnie klikamy na trzy kropki z prawej strony wpisu i wybieramy "New pull request":
W nowym oknie wyświetla nam się, że po ocenie gałąź zostanie włączona do gałęzi głównej main. Możemy dodać tytuł ("Add a title") oraz opis ("Add a description") pracy wykonanej na gałęzi. Po wszystkim klikamy "Create pull request":
Osoby oceniające można dodać z prawej strony, w sekcji "Reviewers". Należy nacisnąć ikonę zębatki i wyszukać osoby, a następnie je wklikać:
Sekcja "Assignees" to osoby odpowiedzialne za zmiany. Zwykle dodajemy tu siebie - przyciskiem "assign yourself":
Na górze strony pull requesta są zakładki:
Lista zmian widoczna jest w zakładce "Files changed":
Gdy proces oceny zakończy się pomyślnie, pozostaje zatwierdzić wszystko przyciskiem "Merge pull request" (na dole zakładki "Conversations"):
targets.txt po krótszej nazwie, np. $RULES_WEBHOOK_URL (uwaga na symbol dolara na początku).
Footnotes
-
Co nie jest do końca prawdą. Regulamin na przykład jest wrzucany równolegle na dwa kanały (jeden oryginalny i jedna kopia dla niezweryfikowanych). ↩
-
Nie ma znaczenia tak naprawdę, czy wszystkie numerki są zajęte i następują bezpośrednio po sobie. Wszystkie nazwy folderów są zbierane i sortowane alfabetycznie, więc to jest tylko takie uproszczenie dla edytującego. ↩ ↩2
-
Folder kanału zawiera też plik
targets.txt, gdzie w kolejnych liniach wypisane są nazwy webhooków powiązanych z tym kanałem. ↩ -
Można, ale nie trzeba. Pozycje z listy są w większości opcjonalne. Jeśli któryś okaże się wymagany, to pipeline zacznie krzyczeć, ale tym już się będzie martwił autor niniejszego repozytorium. ↩ ↩2
-
Pozwala to podejrzeć bezpośrednio na GitHubie, jak treść będzie mniej więcej (no nie w pełni, niestety) wyglądać na Discordzie. Chodzi o formatowanie (wytłuszczenie, kursywę, podkreślenie, przekreślenie), listy, nagłówki, niektóre emotki. ↩ ↩2 ↩3
-
Oczywiście można pracować na jednej gałęzi wspólnie. Chodzi natomiast o to, że zmiany nie sa publicznie widoczne, dopóki siedzą sobie na swojej gałęzi. Dopiero po włączeniu ich do głównej gałęzi (
main) webhooki dokonują aktualizacji wiadomości. ↩