Uwaga! To tłumaczenie jest przestarzałe, prosimy przejść do oryginału.

Używanie gita do manipulowania kodem źródłowym witryny

Git jest systemem kontroli wersji, który pomaga zarządzać pracą wielu osób pracujących jednocześnie nad tym samym materiałem. Każdy użytkownik może posiadać lokalną kopię głównego repozytorium. Kopia lokalna może być na tej samej maszynie albo w dowolnym miejscu na świecie. Użytkownicy mogą następnie modyfikować kopię lokalną według własnego uznania i kiedy modyfikowany materiał jest gotowy, zatwierdzają zmiany i wysyłają je z powrotem do głównego repozytorium.

Git nie pozwoli wysłać commita, jeśli repozytorium zdalne posiada nowsze commity (zmiany) niż kopia lokalna w tej samej gałęzi. W takim przypadku, gdy istnieje konflikt, należy najpierw pobrać i zaktualizować kopię lokalną a następnie w razie potrzeby wykonać rebase swoich nowych zmian bazując na ostatniej wersji.

git - dostęp do zapisu

Osoby potrzebujące dostępu do zapisu w repozytorium muszą poprosić o to poprzez stronę internetową https://salsa.debian.org/webmaster-team/webwml po zalogowaniu się na platformę Debian Salsa. Osoby nowe w pracach nad stronami Debiana, nie mające wcześniejszych doświadczeń w tej dziedzinie, powinny wysłać także wiadomość do debian-www@lists.debian.org i przedstawić się. Prosimy napisać coś użytecznego w swej prośbie: nad którym językiem lub częścią witryny planujesz pracować, i kto może za Ciebie poręczyć.

Praca z repozytorium

Sklonuj lokalną kopię repozytorium

Aby móc pracować z repozytorium, na początku należy zainstalować program git. Następnie należy skonfigurować użytkownika oraz adres mailowy na swoim komputerze (aby dowiedzieć się jak to zrobić, proszę odwołać się do ogólnej dokumentacji gita). Po wykonaniu tych czynności można sklonować repozytorium (innymi słowy, utworzyć lokalną kopię) używając jednego z dwóch sposobów.

Zalecanym sposobem pracy nad webwml, jest rozpoczęcie od zarejestrowania się na salsa.debian.org i włączenie dostępu git SSH poprzez przesłanie publicznego klucza SSH do swojego konta. Szczegółowe informacji jak to zrobić znajdują się na stronach pomocy salsa. Po wykonaniu tych czynności można sklonować repozytorium webwml używając następującego polecenia:

   git clone git@salsa.debian.org:webmaster-team/webwml.git

Jeżeli nie mamy konta salsa, alternatywną metodą jest sklonowanie repozytorium przy użyciu protokołu HTTPS:

  git clone https://salsa.debian.org/webmaster-team/webwml.git

Polecenie to utworzy taką samą lokalną kopię repozytorium, ale nie pozwoli bezpośrednio wysyłać zmian

Sklonowanie całego repozytorium webwml będzie wymagało pobrania około 500MB danych, a zatem może to być trudne dla osób z wolnym lub niestabilnym połączeniem internetowym. Aby zmniejszyć ilość danych przy pierwszym pobraniu, można spróbować płytkiego klonowania z minimalnym zagłębieniem:

  git clone git@salsa.debian.org:webmaster-team/webwml.git --depth 1

Po uzyskaniu użytecznego (płytkiego) repozytorium, można pogłębić lokalną płytką kopię i ostatecznie przekonwertować ją do pełnego lokalnego repozytorium:

  git fetch --deepen=1000 # pogłębienie repozytorium o kolejne 1000 commitów
  git fetch --unshallow   # pobranie wszystkich brakujących commitów, konwersja repozytorium do stanu kompletnego

Częściowe sprawdzanie zawartości

W następujący sposób można utworzyć checkout tylko dla wybranego zestawu stron:

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   W webwml: Utwórz plik .git/info/sparse-checkout z następującą zawartością
   (jeśli potrzebujesz podstawowych plików oraz tłumaczeń języka angielskiego, katalońskiego i hiszpańskiego):
      /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
   Następnie:
   $ git checkout --

Przesyłanie lokalnych zmian

Co kilka dni (a zdecydowanie przed rozpoczęciem edycji) należy wykonać

   git pull

aby otrzymać zmienione pliki z repozytorium.

Uwaga: git jest rozproszonym (nie scentralizowanym) systemem kontroli wersji. Oznacza to, że kiedy robimy commit zmian, są one zachowywane tylko w naszym lokalnym repozytorium. Aby udostępnić je innym, należy wysłać nasze zmiany do centralnego repozytorium na salsa.

Zatem edycja pliku w języku angielskim będzie przebiegać następująco:

   $ git pull

Następnie wprowadzamy zmiany w plikach. Potem wysyłamy zmiany do lokalnego repozytorium używając polecenia:

   $ git add ścieżka/do/pliku(ów)
   $ git commit -m "Opis zmian"

Następnie wysyłamy zmiany do repozytorium Salsa:

   $ git push

To jest skrócony opis tego, jak używać gita do manipulowania kodem źródłowym stron Debiana. Aby uzyskać więcej informacji, proszę zapoznać się z dokumentacją gita.

Zamykanie błędów przy użyciu commitów

Jeżeli dołączymy Closes: #nnnnnn w logu commita, wtedy błąd o numerze #nnnnnn będzie zamknięty automatycznie po wysłaniu zmian. Dokładna forma tego wpisu jest taka sama jak w polityce Debiana.

Linkowanie przy użyciu HTTP/HTTPS

Wiele stron Debiana wspiera SSL, dlatego należy używać linków HTTPS gdzie jest to możliwe i sensowne. Jakkolwiek niektóre strony Debian/DebConf/SPI/itp albo nie wspierają HTTPS w ogóle, albo używają tylko SPI CA (i nie używają zaufanych przez wszystkie przeglądarki SSL CA). Aby uniknąć powodowania komunikatów o błędach dla użytkowników spoza Debiana, nie należy stosować do takich stron linków z HTTPS.

Repozytorium git odrzuci commity zawierające czyste linki HTTP do stron Debiana, które wspierają HTTPS lub zawierające linki HTTPS do stron Debian/DebConf/SPI, o których wiemy że albo nie wspierają HTTPS albo używają certyfikatów podpisanych tylko przez SPI.

Praca nad tłumaczeniami

Po zmianie tłumaczonego pliku, należy zaktualizować nagłówek translation-check, aby odpowiadał identyfikatorowi (hash) commita z odpowiednią zmianą w pliku angielskim. Identyfikator ten znajdziemy korzystając z polecenia

$ git log path/to/english/file

Jeżeli tworzymy nowe tłumaczenie pliku, możemy użyć skryptu copypage.pl, który utworzy szablon dla naszego języka, dołączając odpowiedni nagłówek tłumaczenia.

Tłumaczenie zmian przy użyciu skryptu smart_change.pl

smart_change.pl jest skryptem zaprojektowanym aby ułatwić wspólną aktualizację oryginalnego pliku oraz jego tłumaczeń. Istnieją dwa sposoby użycia tego skryptu, w zależności od zmian jakie chcemy wprowadzić.

Aby użyć smart_change tylko do aktualizacji nagłówka translation-check, kiedy pracujemy nad plikiem ręcznie:

  1. Wprowadzamy zmiany w oryginalnym pliku(ach) i robimy commit
  2. Aktualizujemy tłumaczenia
  3. Uruchamiamy smart_change.pl - zostaną pobrane zmiany i zaktualizowane nagłówki w przetłumaczonych plikach
  4. Przeglądamy zmiany (np. przy użyciu "git diff")
  5. Robimy commit zmian w tłumaczeniach

Albo, jeżeli używamy smart_change z wyrażeniami regularnymi do zrobienia wielu zmian w wielu plikach w jednym kroku:

  1. Uruchamiamy smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
  2. Przeglądamy zmiany (np. przy użyciu git diff)
  3. Robimy commit oryginalnego pliku(ów)
  4. uruchamiamy smart_change.pl origfile1 origfile2 (np. bez regexp tym razem); teraz będą zaktualizowane nagłówki w przetłumaczonych plikach
  5. Na końcu, robimy commit zmian w tłumaczeniach

Ten sposób jest bardziej skomplikowany niż poprzedni (wymagający dwóch commitów), ale nieunikniony ze względu na sposób, w jaki działają hashe commitów w git.

Otrzymywanie powiadomień

Skonfigurowaliśmy projekt webwml na Salsa w taki sposób, aby commity pokazywały się na kanale IRC #debian-www.

Aby otrzymywać powiadomienia poprzez e-mail kiedy pojawią się commity w repozytorium, należy zapisać się do pseudopakietu www.debian.org poprzez tracker.debian.org i aktywować tam słowo kluczowe vcs wykonując następujące kroki (tylko raz):