Använda git för att manipulera webbplatsens källkod

Introduktion

Git är ett versionshanteringssystem som hjälper till att hantera flera personer som jobbar på samma material samtidigt. Varje användare kan ha en lokal kopia av ett huvudförråd. De lokala kopiorna kan befinna sig på samma maskin, eller över hela världen. Användare kan sedan modifiera sin lokala kopia som de vill och sedan när det modifierade materialet är färdigt så kan de committa ändringar och sedan skicka till huvudförrådet.

Git kommer inte att låta dig pusha en commit direkt om fjärrförrådet har några nyare commits (ändringar) än din lokala kopia på samma gren. I sådana fall där en konflikt sker, var vänlig hämta och uppdatera din lokala kopia först och rebase dina nya modifikationer på den senaste ändringen.

Skrivrättigheter till Git-förrådet

Hela Debianwebbplatsens källkod hanteras med Git. Den finns vid https://salsa.debian.org/webmaster-team/webwml. Som standard har gäster inte rättigheter har pusha commits till källkodsförrådet. Du behöver någon sorts rättighet för 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.

Skriv till förrådet via 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. (läs Arbetsflöde vid projektförgreningar och När du arbetar i en förgrening för ytterligare detaljer).

Merge Requests övervakas inte 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.

Jobba med förrådet

Hämta en lokal kopia av förrådet

Först och främst måste du installera git för att jobba med förrådet. Sedan måste du konfigurera din e-post och användarnamn på din dator (vänligen se allmän git-dokumentation för att se hur man gör detta). Sedan kan du klona förrådet (med andra ord - göra en lokal kopia av det) på ett av två sätt.

Det rekommenderade sättet att jobba med webwml är att först registrera ett konto på salsa.debian.org och aktivera git SSH-åtkomst genom att ladda upp en publik SSH-nyckel till ditt salsa-konto. Se salsas hjälpsidor flr ytterligare detaljer om hur man gör det. Sedan kan du klona webwml-förrådet med hjälp av följande kommando:

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

Om du inte har ett salsa-konto är en alternativ metod att klona förrådet med hjälp av HTTPS-protokollet:

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

Detta kommer att ge dig samma förråd lokalt, men du kommer inte att kunna pusha ändringar direkt tillbaks på detta sätt.

En kloning av fullständiga webwml-förrådet skulle kräva hämtning av runt 500MB data, och kan därmed vara svårt för dem med långsam eller instabil internetuppkoppling. Du kan försöka med "grund" kloning med minimalt djup först för mindre initial dataöverföring:

  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 fullständigt återställa den till ett komplett 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

Ofullständig innehållshämtning

Du kan skapa en checkout för endast en undergrupp av sidorna så här:

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   I webwml: Skapa filen .git/info/sparse-checkout med innehåll som detta
   (om du endast vill ha basfilerna, Engelska, Catalanska och Spanska översättningarna):
      /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
   och sedan:
   $ git checkout --

Skicka in lokala ändringar

Håll ditt lokala förråd uppdaterat

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

   git pull

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

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 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 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:

   $ git pull

Gör nu ändringar till filer. När du är klar, kan du committa dina ändringar till det lokala förådet med hjälp av

   $ git add sökväg/till/fil(er)
   $ git commit -m "Ditt ändringsmeddelande"

Om du har obegränsade skrivrättigheter till förrådet kan du nu pusha dina ändringar direkt till Salsa-förrådet:

   $ git push

Om du inte har direkt skrivåtkomst till webwml-förrådet, var vänlig överväg att tillhandahålla dina ändringar med hjälp av en Merge Request som det tillhandahålls av Salsa Gitlab-plattformen eller fråga andra utvecklare om hjälp.

Det är allt som behövs när det gäller enkel användning av git för att manipulera Debians webbplats källkod. För mer information om git, var vänlig se Git's dokumentation.

Stänga Debianfelrapporter mha 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.

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 commit hashen i motsvarande ändring i den Engelska filen. Du kan hitta denna hash med

$ 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.

För att använda smart_change.pl för att endast uppdatera translation-check-huvudena när du arbetar med filer manuellt:

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.

Få aviseringar

Få commit-aviseringar

Vi har satt upp konfigurationen av projektet 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):

Få Merge-Requst-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: