Jak się udzielić

Gothic Modding Community jest projektem napędzanym przed społeczność. Zachęcamy osoby do wnoszenia swojego wkładu.

Ta strona jest budowana przy pomocy statycznego generatora stron MkDocs oraz skórki Material for MkDocs, wraz z wieloma innymi wtyczkami do MkDocs.

Zależnie od skali i typu kontrybucji, trzeba spełnić inne wymagania wstępne.

Zgłoszenia

Po angielsku można zgłosić problem lub inny komentarz o funkcjonowaniu strony poprzez otworzenie problemu (ang. issue) na serwisie GitHub albo dołącz do nas na platformie Discord.

Wkład bezpośredni

Wkład bezpośredni wykonuje się poprzez stworzenie kopii tego repozytorium (ang. fork) oraz stworzenie prośby o połączenie (ang. pull request PR) na serwisie GitHub wraz ze zmianami do zatwierdzenia.

Nie zmarnuj czasu

Proszę się upewnić, że treść, jaka zostanie dodana, nie występuje już na wersji dev strony. Można skorzystać z funkcjonalności wyszukiwania, żeby przefiltrować GMC różnymi słowami kluczowymi i treściami.

Jak edytować pliki źródłowe?

Pliki źródłowe artykułów są pisane wykorzystując format plików Markdown .md (Markdown cheatsheet). Poza tym ta strona wykorzystuje wtyczkę Python Markdown Extensions, która rozszerza składnię o dodatkowe zasady pozwalające na wstawienie wzmianek jak ta, którą właśnie czytasz.

Mniejsze zmiany

Mniejsze zmiany, jak poprawianie błędów ortograficzny, gramatycznych, czy usuwanie/dodawanie słów do akapitów w jednym pliku, mogą być zrobione szybko poprzez kliknięcie przycisku w prawym górnym rogu artykułu. Otworzy to interfejs edytowania pliku w serwisie GitHub, które po zapisaniu zmian, automatycznie utworzy kopię (ang. fork) oraz gałąź (ang. brach) z łatką, a następnie otworzy prośbę o połączenie (ang. pull request) względem gałęzi dev.

Poprawna gałąź dla prośby o połączenie

Upewnij się, że prośba o połączenie (ang. pull request) jest skierowana do gałęzi dev albo specjalnej gałęzi pre-merge, a nie do gałęzi main.

Większe zmiany

Bardziej złożone zmiany takie jak, edycja wielu plików naraz, dodawanie nowych artykułów, obrazków, czy innych plików, albo zmiana konfiguracji strony jest łatwiej zrobić poprzez użycie zewnętrznych narzędzi na lokalnym PC. Większość z tych operacji można zrobić poprzez interfejs serwisu GitHub, ale jest to raczej uciążliwe oraz trudniej zauważyć problemy wynikające z procesu zmian, ponieważ nie są one widoczne w przeglądarce w ich ostatecznej formie.

Trochę przygotowań jest potrzebnych przed rozpoczęciem prac nad plikami, ponieważ do działania MkDocs wymaga zainstalowanego w systemie Pythona. GitHub działa nad systemem kontroli wersji git, więc jego instalacja jest też wymagana. Podstawowa znajomość obsługi Terminala/Konsoli poleceń/Powershell jest pomocna.

Przygotowanie Systemu (wideo)

Po pierwsze, trzeba zainstalować Python. Można podążać według tego poradnika krok po kroku dla Windowsa albo macOS jak zainstalować Python.

Wideo jest z 2017?!

Proces instalacji Pythona nie zmienił się od tamtego czasu. Jednakże proszę instalować najnowszą wersję Python 3.

Aby móc pracować zdalnie z GitHub, można zainstalować najnowszą wersję git, podążając według tego poradnika.

Jeżeli planujesz tylko edytować zawartość artykułów Markdown, możesz po prostu zainstalować najnowszą wersję Visual Studio Code, żeby mieć interfejs graficzny do zarządzania git oraz podgląd Markdown, albo pracuj z dowolnym znanym edytorem tekstu i omiń konfigurację środowiska.

Jeżeli planujesz bardziej złożone programowanie w Python, możesz podążyć według tego poradnika krok po kroku dla Windowsa lub macOS jak skonfigurować środowisko developerskie z Visual Studio Code (VS Code).

Przygotowanie Systemu (tekst)

Żeby przygotować system do uruchomienia projektu lokalnie, podążaj według tych instrukcji.

Zainstaluj najnowszą wersję Pythona.
Upewnij się, żeby zaznaczyć opcję "Add Python to PATH" podczas instalacji.
Otwórz okno Terminala/Konsoli poleceń/PowerShell.
Sprawdź, że instalacja Pythona była pomyślna, korzystając z tego polecenia (możliwa jest potrzeba restartu okna konsoli):
1
python --version
Zainstaluj najnowszą wersję git, podążając według tego poradnika.
Sprawdź, że instalacja git była pomyślna, korzystając z tego polecenia (możliwa jest potrzeba restartu okna konsoli):
1
git --version
(opcjonalne) Zainstaluj najnowszą wersję Visual Studio Code dla interfejsu graficznego do zarządzania git i podglądem Markdown.

Praca lokalna

Aby móc pracować lokalnie:

Stwórz kopię (ang. fork) na serwisie GitHub.
Na lokalnym PC nawiguj do folderu, w którym chcesz sklonować kopię repozytorium, oraz otwórz okno konsoli wewnątrz niego.
Sklonuj kopię repozytorium, korzystając z tego polecenia:
1
git clone https://github.com/user-name/forked-repository-name.git <DIR-PATH>
Zamiast https://github.com/user-name/forked-repository-name.git skorzystaj z własnego linku, który jest widoczny po kliknięciu zielonego przycisku <> Code i wybraniu zakładki HTTPS.

Zamień <DIR-PATH> ze ścieżką do folderu, do którego ma być sklonowane repozytorium albo . jeżeli już jesteś wewnątrz folderu gdzie pliki projektu mają się znajdować.

To automatycznie utworzy zdalne repozytorium origin skierowane względem twojej kopii.

Dodaj zdalne repozytorium upstream korzystając z tego polecenia:

git remote add upstream https://github.com/Gothic-Modding-Community/gmc.git

(opcjonalne) Stwórz wirtualne środowisko i aktywuj je.

Jeżeli pracujesz przy kilku projektach Python, warto stworzyć wirtualne środowisko (ang. Virtual Environment) dla każdego z tych projektów, żeby każdy mógł korzystać z własnego folderu bibliotek z zainstalowanymi modułami/wtyczkami.
1
python -m venv venv
To utworzy folder venv wewnątrz obecnie wybranego folderu w oknie konsoli. Proszę, zostaw tę nazwę, ponieważ jest dodana do pliku .gitignore projektu.

Zależnie od systemu, skorzystaj z jednego z tych poleceń do aktywacji wirtualnego środowiska.
Linux / macOS
1
source venv/bin/activate
Windows Powershell
1
venv\Scripts\activate.ps1
Windows Konsola Poleceń (cmd)
1
venv\Scripts\activate.bat
Po aktywacji indykator (venv) będzie wyświetlany przy nazwie folderu w oknie poleceń.

Nie zamykaj okna poleceń

Wirtualne środowisko musi być ponownie aktywowane, przy każdym otwarciu okna poleceń.
Zainstaluj MkDocs wraz z wtyczkami korzystając z tego polecenia:
1
pip install -r requirements.txt
To zainstaluje wszystkie zależności.
Pobierz (ang. fetch) stan historii git z repozytorium upstream korzystając z tego polecenia:
1
git fetch upstream
Otwórz (ang. checkout) lokalną gałąź opierającą się o gałąź dev repozytorium upstream korzystając z tego polecenia:
1
git checkout -b name-of-branch --track upstream/dev
W miejscu name-of-branch podaj krótką nazwę po angielsku. Odpowiednią nazwą gałęzi jest albo nazwa funkcjonalności, albo krótki opis wprowadzonych zmian np. 3ds-articles, fix-typos-for-contribution. Nie muszą być zbyt skomplikowane, do 4 słów wystarczy.
Uruchom serwer ze zbudowaną stroną projektu, korzystając z tego polecenia:
1
mkdocs serve
Odwiedź lokalną stronę pod tym adresem http://127.0.0.1:8000/gmc/. Po każdej zmianie w plikach projektu strona automatycznie się przebuduje i po chwili przeglądarka automatycznie się odświeży.

Serwer może być zamknięty poprzez skorzystanie ze skrótu klawiszowego Control-C w trakcie gdy okno poleceń jest aktywne.
Jeżeli ukończysz fragment swojej pracy, dodaj pliki i wstaw wpis do historii gita (ang. commit) korzystając z tego polecenia:
1 2
git add . git commit -m "add 3 articles about ZenGin"
Jak widać wiadomość (ang. message) / nazwa do wpisu historii również powinna być w języku angielskim. Odpowiednią wiadomością jest zdanie opisujące zmiany.
Po skończeniu wszystkich prac wyślij (ang. push) swoją gałąź do zdalnego repozytorium origin, korzystając z tego polecenia:
1
git push origin name-of-branch
Stwórz prośbę o połączenie (ang. pull request) względem odpowiedniej gałęzi.

Po wysłaniu lokalnej gałęzi do zdalnego repozytorium origin w oknie poleceń będzie dostępne łącze, które otworzy stronę tworzenia prośby o połączenie. Upewnij się, że jest skierowana względem gałęzi dev oraz, że posiada wszystkie wprowadzone zmiany.
Kolejna kontrybucja:

Przed kolejną kontrybucją, zawsze skorzystaj z tego polecenia:
1
git fetch upstream
żeby mieć pewność, że posiadasz najnowszą historię zmian z repozytorium upstream. Następnie podążaj ponownie od 8. podpunktu i zawsze twórz nową gałąź przed wprowadzeniem zmian.
1
git status
Tym poleceniem możesz sprawdzić, czy nie masz żadnych zmian w strukturze projektu względem repozytorium upstream.

Preferencje budowy strony

Podczas pracy z projektem można ustawić różne zmienne środowiskowe, żeby przystosować konfigurację do własnych preferencji:

GMC_DEV_LOCALE - to dwuznakowy identyfikator języka (np. en, pl), ustawia język testowy. To ustawi ten języki jako domyślny oraz jedyny renderowany podczas budowy strony. Pomaga w zmniejszeniu czasu budowy strony oraz pozwala na łatwe zmienianie języka zamiast modyfikowania pliku konfiguracyjnego. Przez zmiany w pluginie mkdocs-static-i18n jest to jedyny sposób na tymczasową zmianę domyślnego języka
GMC_BUILD_ALTERNATES - wartość True albo False, aktywuje budowanie strony wraz z alternatywnymi językami. Domyślnie alternatywne języki są pomijane, aby zmenijszyć czas budowy strony.
GMC_ENABLE_ON_PUBLISH - wartość True albo False, aktywuje wszystkie finalne procesy, jak dodanie daty ostatniej aktualizacji, minimalizacja zasobów itp.

Dla otwartego okna poleceń można tymczasowo je ustawić:

Linux
export GMC_DEV_LOCALE=en export GMC_BUILD_ALTERNATES=False; mkdocs serve

Windows Powershell
$env:GMC_DEV_LOCALE="en"
$env:GMC_BUILD_ALTERNATES="False"
mkdocs serve

Windows Konsola Poleceń (cmd)
set GMC_DEV_LOCALE=en
set GMC_BUILD_ALTERNATES=False
mkdocs serve

Wydajność budowy strony

Aby przyśpieszyć proces budowy strony podczas pracy, upewnij się, że tylko 1 język jest budowany i rozważ użycie opcji --dirtyreload:

1	`mkdocs serve --dirtyreload`

To sprawi, że tylko zmienione pliki .md będą na nowo budowane. Jednakże, zmiany plików szablonowych (ang. template) w folderze overrides nie będą widoczne, ponieważ takie zmiany wymagają pełnej przebudowy.

Prześlij plik

Jeżeli praca z git albo Markdown jest nieprzystępna lub niemożliwa to możesz przesłać plik w formacie Google Docs na serwer Discord GMC, sformatujemy go i dodamy treść do strony.

Tylko nowa zawartość po angielsku

Ta opcja jest ograniczona tylko dla nowej treści w języku angielskim. Nie możemy wykorzystać tego sposobu dla tłumaczeń. Dla tłumaczeń wyślij przetłumaczony plik .md poprzez zgłoszenie, jeżeli nie chcesz pracować bezpośrednio z git, ani dodać pliku poprzez interfejs GitHub.

Tłumaczenia

Żeby dostarczyć wsparcie dla wielu języków, nasza strona korzysta ze wtyczki MkDocs i18n.

Dodaj wsparcie dla nowego języka

Żeby wspierać nowy język, musi być dodany:

Wcięcia mają znaczenie

Musisz zachować poprawną ilość wcięć, czyli odstępów między wpisami.

W konfiguracji mkdocs.yml, w tym przykładzie dodajemy język xx:

plugins:
  - i18n:
      # ...
      languages:
        en:
          name: en - English
          build: true
        xx:
          name: xx - Language Name
          build: true

W pliku overrides/main.html, żeby dodać tekst ogłoszenia dla zawartości nieprzetłumaczonej:

{%
    set announcement = {
        "en": "This page has not yet been translated into LANGUAGE, therefore it is displayed in English.",
        "xx": "yyy",
    }
%}
{%
    set call_to_action = {
        "en": "Support us and translate!",
        "xx": "yyy",
    }
%}

Odwiedź oficjalną stronę skórki. Upewnij się, że tłumaczenie skórki jest tam kompletne. Jeżeli nie jest, podążaj według poradnika kontrybucji skórki i wróć tutaj, nie trzeba czekać na zmiany w skórce.

Dodaj przetłumaczone strony

Każdy plik .md w folderze docs może mieć przetłumaczoną wersję.
Żeby dodać tłumaczenie strony dla danego języka, stwórz kopię strony z dodaną końcówką tego języka. Na przykład index.md będzie index.xx.md dla języka xx bazując na ustawieniach z pliku mkdocs.yml.

Każdy nieprzetłumaczony artykuł posiada przycisk w górnym prawym rogu obok tytułu. Pozwala na szybkie dodanie tłumaczenia poprzez interfejs serwisu GitHub bez potrzeby konfiguracji plików lokalnie.