Använda Git för att jobba på Debianwebbplatsen

Jobba på Gitförrådet

Låt oss börja på en gång - i denna sektion kommer du lära dig hur du skapar en lokal kopia av huvudförrådet, hur du håller förrådet uppdaterat och hur du skickar in ditt arbete. Vi kommer även att förklara hur du jobbar på översättningar.

Hämta en lokal kopia

Det första du måste göra att installera Git. Sedan - konfigurera Git och mata in ditt namn och din e-postadress. Om du är nybörjare när det gäller Git så är det troligen en god idé att läsa den allmänna Gitdokumentationen först.

Nästa steg är att klona förrådet (med andra ord: göra en lokal kopia av det). Det finns två sätt att göra detta:

Tips: Att klona hela webwml-förrådet kräver en hämtning på runt 1.3 GB data vilket kan vara för mycket om du är på en långsam eller instabil internetanslutning. Därför finns det en möjlighet att definiera ett minimalt djup för en mindre initial hämtning: 

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

Efter att du har hämtat en användbar (grund) kopia av förrådet kan du göra din lokala kopia djupare och eventuellt konvertera den till en fullständigt lokalt förråd:

  git fetch --deepen=1000 # fördjupa förrådet med ytterligare 1000 commits
  git fetch --unshallow   # hämta alla saknade commits, och konvertera förrådet till ett fullständigt

Du kan skapa en checkout för endast en undergrupp av sidorna:

  1. git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. Skapa filen .git/info/sparse-checkout i webwml-mappen för att definiera innehållet som du vill checka ut. Till exempel, om du bara vill hämta root-filerna, engelska, katalanska och spanska översättningarna, ser filen ut så här: 
          /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
  5. Slutligen kan du checka ut förrådet: git checkout --

Skicka in lokala ändringar

Håll ditt lokala förråd uppdaterat

Med några få dagars mellanrum (och åtminstone innan du påbörjar redigeringsarbete!) kommer du att vilja köra

  git pull

för att få alla filer som har ändrats från förrådet.

Det rekommenderas starkt att hålla din lokala git-arbetskatalog ren innan du utför en git pull och arbetar med denna. Om du har icke uppskickade ändringar eller lokala commits som inte finns i fjärrförrådet på aktuell gren kommer git pull att automatiskt skapa merge commits eller kanske till och med misslyckas på grund av konflikter. Vänligen överväg att hålla ofullständigt arbete i en annan gren eller genom att använda kommandon som git stash.

Notera att git är ett distribuerat (och inte centraliserat) versionshanteringssystem. Detta betyder att när du committar ändringar så kommer dessa endast att lagras i ditt lokala förråd. För att dela dessa med andra så måste du pusha dina ändringar till det centraliserade förrådet på salsa.

Exempel: exempel på en ändring i en engelsk fil

Ett exempel på hur man redigerar engelska filer i webbplatsens källkodsförråd följer. Efter du har hämtat en lokal kopia på förrådet mha git clone och innan du påbörjar redigeringsarbetet, kör följande kommando:

  1. git pull
  2. Nu kan du börja redigera och göra ändringar till filerna.
  3. När du är klar, committa din ändringar till ditt lokala förråd: 
        git add path/to/file(s)
    git commit -m "Ditt ändringsmeddelande"
  4. Om du har obegränsad skrivåtkomst till fjärrförrådet webwml, kan du nu skicka dina förändringar direkt till salsaförrådet: git push
  5. Om du inte har direkt skrivåtkomst till webwml-förrådet, skicka dina ändringar med hjälp av en merge request eller kontakta andra utvecklare för att få hjälp.

Stänga Debian-felrapporter med Git-commits

Om du inkluderar Closes: #nnnnnn i ditt commitloggmeddelande, så kommer felnummer #nnnnnn att stängas automatiskt när du pushar dina ändringar. Den exakta formen för detta är samma som i Debians policy.

Länka med hjälpa av HTTP/HTTPS

Många Debianwebbplatser stödjer SSL/TLS, var vänlig använd HTTPS-länkar där det är möjligt och förnuftigt. Några Debian/DebConf/SPI/osv webbplats har inte SSL-stöd eller är endast signerade av SPI och inte av någon SSL CA som är betrodd av webbläsare utanför Debian, så därmed bör vi undvika att länka till https:-versioner av dessa webbplatser så att personer som inte använder Debian får fel som de inte förstår sig på.

Gitförrådet kommer att avvisa commits som innehåller rena HTTP-länkar för Debianwebbplatser som stödjer HTTPS eller innehåller HTTPS-länkar för Debian/DebConf/SPI-webbplatserna som är kända att inte stödja HTTPS eller använder certifikat som endast är signerade av SPI.

Jobba på översättningar

Översättningar skall alltid hållas uppdaterade och up-to-date med dess engelska motsvarighet. Huvudet translation-check i översatta filer används för att spåra vilka versioner av engelska filer som den aktuella översättningen baseras på. Om du ändrar översatta filer, kan du vara tvungen att uppdatera translation-check-huvudet för att matcha git commithashen i motsvarande ändring i den Engelska filen. Du kan hitta denna hash med följande kommando:

  git log sökväg/till/engelsk/fil

Om du gör en ny översättning av en fil, vänligen använd copypage.pl-skriptet så kommer det att göra en ny mall för ditt språk, och inkludera ett korrekt översättningshuvud.

Översättningsändringar med smart_change.pl

smart_change.pl är ett skript som är designat för att göra det lättare att uppdatera original-filer och dess översättningar tillsammans. Det finns två sätt att göra detta, beroende på vilken typ av ändringar du gör.

Här följer hur du använder smart_change.pl och hur du bara uppdaterar translation-check-huvudet när du jobbar på filer manuellt:

  1. Gör ändringarna till originalfil(erna), och committa dina ändringar
  2. Uppdatera översättningar
  3. Kör smart_change.pl -c COMMIT_HASH (använd commit-hashen för ändringarna i original-filen). Detta kommer att snappa upp förändringarna och uppdatera huvuden i de översatta filerna.
  4. Granska ändringarna (exempelvis med git diff)
  5. Committa översättningsändringarna.

Eller, om du använder smart_change med ett reguljärt uttryck för att göra flera ändringar över filer i ett pass:

  1. Kör smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
  2. Granska förändringarna (t.ex. med git diff)
  3. Committa original-filerna
  4. Kör smart_change.pl origfile1 origfile2 (vilket är utan reguljära uttrycket den här gången); det kommer nu att endast uppdatera huvudena i de översatta filerna
  5. Slutligen, committa översättningsändringarna

Detta är mer komplicerat än tidigare (det kräver två commits), men oundvikligt på grund av hur git commit-hashen fungerar.

Skrivåtkomst till Gitförrådet

Källkoden till Debians webbsajt hanteras i Git och hittas på https://salsa.debian.org/webmaster-team/webwml. Som standard har inte gäster rättigheter att skicka commits till källkodsförrådet. Om du vill bidra till Debians webbplats behöver du någon sorts tillåtelse att få skrivåtkomst till förrådet.

Obegränsade skrivrättigheter

Om du behöver obegränsade skrivrättigheter till förrådet (om du exempelvis är på väg att bli en frekvent bidragslämnare), var vänlig efterfråga detta via webbgränssnittet på https://salsa.debian.org/webmaster-team/webwml efter att du har loggat in på salsa-plattformen.

Om du är ny på utveckling av Debian's webbsida och inte har någon tidigare erfarenhet, var vänlig kontakta även debian-www@lists.debian.org med en introduktion om dig själv innan du efterfrågar obegränsade skrivrättigheter. Vänligen skriv något användbart i din introduktion, så som vilket språk du vill jobba med eller vilken del av webbplatsen som du kommer att jobba på och vem som kommer att gå i god för dig.

Merge Requests

Om du inte har intentionen att få obegränsade skrivrättigheter till förrådet eller inte har möjligheten till detta, så kan du alltid skicka Merge Requests och låta andra utvecklare undersöka och acceptera ditt arbete. Var vänlig skicka Merge Requests enligt standardförfarandet som det tillhandahålls av Salsa Gitlab-plattformen via dess webbgränssnitt och läs följande två dokument:

Vänligen notera att Merge Requests inte övervakas av alla webbplatsutvecklare och kan därmed kanske inte behandlas i tid. Om du inte är säker på om ditt bidrag skulle accepteras, vänligen skicka e-post till sändlistan debian-www och efterfråga en granskning.

Få aviseringar

Om du arbetar på Debians webbplats, så vill du antagligen veta vad som sker i förrådet webwml. Det finns två sätt att hålla sig uppdaterad: commitaviseringar och aviseringar för merge requests.

Commit-aviseringar

Vi har satt upp konfigurationen av projektet webwml i Salsa så att commits visas i IRC-kanalen #debian-www.

Om du vill få aviseringar via e-post när det finns commits i webwml-förrådet vänligen prenumerera på pseudopaketet www.debian.org via tracker.debian.org och aktivera nyckelordet vcs där, genom att följa dessa steg (en gång endast):

  1. Öppna en webbläsare och gå till https://tracker.debian.org/pkg/www.debian.org
  2. Prenumerera på pseudopaketet www.debian.org. (Du kan autentisera via SSO eller registrera en e-post och lösenord, om du inte redan har använt tracker.debian.org för andra ändamål).
  3. Gå till https://tracker.debian.org/accounts/subscriptions, och sedan till modify keywords, kryssa i vcs (om den inte redan är ikryssad) och spara.
  4. Från och med nu kommer du att få e-post när någon committar till webwml-förrådet.

Få Merge-Request-aviseringar

Om du vill få aviseringar via e-post när det finns nya Merge Requests skickade till webwml-förrådet på Salsa Gitlab-plattformen, kan du konfigurera dina notifierings-inställningar för webwml-förrådet via webgränssnittet, och följa dessa steg:

  1. Logga in på ditt Salsa-konto och gå till projekt-sidan.
  2. Klicka på ringklocke-ikonen på översidan av projekt-sidan.
  3. Välj notifieringsnivån som du önskar.