Advarsel! Denne oversættelse er for gammel, benyt venligst originalen.

Brug af Git til at håndtere webstedets kildekode

Introduktion

Git er et versionsstyringssystem, som hjælper med at håndtere, at der er mange personer, der på samme tid arbejder på det samme materiale. Enhver bruger kan have en lokal kopi af et hovedarkiv. De lokale kopier kan være på den samme maskine eller et helt andet sted i verden. Brugerne kan dernæst ændre deres lokale kopi, som de ønsker, og når det ændrede materiale er parat, commit'es ændringerne og push'es (skubbes) tilbage til hovedarkivet.

Git tillader ikke at man push'er en commit direkte, hvis fjernarkivet indeholder nyere commits (ændringer), end man har i sin lokale kopi i den samme branch (forgrening). I sådanne tilfælde hvor konflikter kan opstå, skal man først hente ændringerne og opdatere sin lokale kopi, og dernæst efter behov rebase sine nye ændringer oven på den seneste commit.

Skriveadgang til Git

Hele Debians websteds kildekode håndteres i Git, på adressen https://salsa.debian.org/webmaster-team/webwml. Som standard har gæster ikke tilladelse til at push'e commit ind i kildekodearkivet. For at få skriveadgang til arkivet, skal man have tildelt rettighed dertil.

Ubegrænset skriveadgang

Hvis du har brug for ubegrænset skriveadgang til arkivet (fx hvis du er ved at blive en hyppig bidragyder), så overvej at bede om skriveadgang gennem webbrugerfladen på https://salsa.debian.org/webmaster-team/webwml, efter du har logget på Debians Salsa-platform. Hvis udvikling af Debians websted er nyt for dig, og du ikke har tidligere erfaring, så send også en mail til [email protected] med en introduktion af dig selv, før du beder om ubegrænset adgang. Skriv noget nyttigt i din introduktion, så som hvilket sprog eller hvilken del af webstedet, du planlægger at arbejde på, og hvem der kan stå inde for dig.

Skrivning til arkivet gennem Merge Requests

Hvis du ikke har i sinde at få ubegrænset skriveadgang til arkivet eller ikke er i stand til at få det, kan du altid indsende en Merge Request og lade andre udviklere gennemgå og acceptere dit arbejde. Indsend Merge Requests jævnfør den almindelige procedure, som stilles til rådighed af Salsa GitLab-platformen gennem dens webgrænseflade (læs Project forking workflow og When you work in a fork for flere oplysninger).

Ikke alle webstedets udviklere holder øje med Merge Requests, hvorfor der kan gå et stykke tid, før der sker noget. Hvis du er usikker på om dit bidrag kan accepteres, så send en mail på engelsk til postlisten debian-www, og bed om et review.

Arbejde i arkivet

Få en lokal kopi af arkivet

Først skal du installere Git, for at kunne arbejde med arkivet. Dernæst opsættes din bruger og mailoplysninger på din computer (se Gits generelle dokumentation for oplysninger om hvordan dette gøres). Herefter kan du klone arkivet (med andre ord, lave en lokal kopi af det) på to forskellige måder.

Den anbefalede måde at arbejde på webwml, er først at registrere en konto på salsa.debian.org, og aktivere adgang til Git via SSH, ved at uploade en offentlig SSH-nøgle til din salsakonto. Se salsas hjælpesider for flere oplysninger om hvordan det gøres. Dernæst kan du klone webwml-arkivet med følgende kommando:

  git clone [email protected]:webmaster-team/webwml.git

Hvis du ikke har en salsakonto, er der en alternativ metode til kloning af arkivet ved hjælp af HTTPS-protokollen:

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

Det giver dig en lokal kopi af det samme arkiv, men den vil ikke være i stand til at push'e ændringer direkte tilbage på denne måde.

Kloning af hele webwml-arkivet kræver, at der hentes omkring 500 megabyte data, hvilket kan være et problem for dem, med langsomme eller ustabile internetforbindelser. Du kan i stedet prøve en begrænset kloning med en minimal dybde, for i første omgang at overføre færre data:

  git clone [email protected]:webmaster-team/webwml.git --depth 1

Efter at have hentet et brugbart (begrænset) arkiv, kan du fordybe den lokale begrænsede kopi, og med tiden konvertere den til et komplet lokalt arkiv:

  git fetch --deepen=1000 # fordyb arkivet med yderligere 1000 commits
  git fetch --unshallow   # hent alle manglende commits, konverter arkivet til et komplet arkiv

Delvis checkout af indhold

På følgende måde kan du oprette en checkout, som kun indeholder en delmængde af siderne:

  $ git clone --no-checkout [email protected]:webmaster-team/webwml.git
  $ cd webwml
  $ git config core.sparseCheckout true
  I webwml: Opret filen .git/info/sparse-checkout med indhold som det følgende (hvis
  du kun ønsker grundlæggende filer, engelsk, samt danske og svenske oversættelser):
    /*
    !/[a-z]*/
    /english/
    /danish/
    /swedish/
  Then:
  $ git checkout --

Overførsel af lokale ændringer

Hold dit lokale arkiv ajour

En gang i mellem (og helt sikkert inden du går i gang med at redigere!), skal du udføre en

  git pull

for at hente alle ændrede filer fra arkivet.

Det anbefales kraftigt, at sørge for at din lokale git-arbejdsmappe er renset før der udføres en git pull og efterfølgende redigeringsarbejde. Hvis du har ændringer, som ikke er commit'et eller lokale commit, som ikke findes i det fjerne arkiv i den aktuelle forgrening, vil en git pull automatisk oprette merge-konflikter eller endda helt afbryde på grund af konflikter. Overvej at holde dit ufuldendte arbejde i en anden forgrening eller benyt kommandoer så som git stash.+

Bemærk: Git er et distribueret (ikke centraliseret) versionsstyringssystem. Det betyder at når du commit'er ændringer, bliver de kun gemt i dit lokale arkiv. For at dele dine ændringer med andre, skal du også push'e (skubbe) dem til arkivet i Salsa.

Eksempel på redigering af engelske filer

Et eksempel på hvordan en engelsk fil redigeres i webstedets kildekodearkiv, kan ses herunder. Efter at have få en lokal kopi af arkivet ved hjælp af git clone og før redigeringsarbejdet begynder, skal følgende kommando udføres:

  $ git pull

Foretag nu dine filændringer. Når du er færdig, skal du commit'e ændringerne til dit lokale arkiv, med

  $ git add sti/til/fil(er)
  $ git commit -m "Your commit message"

Commitmeddelelsen skal skrives på engelsk.

Hvis du har ubegrænset skriveadgang til det fjerne webwml-arkiv, kun du nu skubbe dine ændringer direkte til Salsa-arkivet:

  $ git push

Hvis du ikke har direkte skriveadgang til webwml-arkivet, så overvej at indesende dine ændringer ved hjælp af Merge Request-funktionen, som findes i Salsa GitLab-platformen, eller bed andre udviklere om hjælp.

Det er et meget grundlæggende resume af hvordan Git bruges til at kildekoden til Debians websted. For flere oplysninger om Git, kan du læse Gits dokumentation.

Lukning af Debian-fejl i Git-commits

Hvis du medtager Closes: #nnnnnn i din commitmeddelelse, vil fejl nummer #nnnnnn blive lukket automatisk når du push'er dine ændringer. Det nøjagtige format er det samme, som i Debian Policy.

Links med HTTP/HTTPS

Mange af Debians websteder understøtter SSL/TLS, benyt derfor HTTPS-links, hvor det er muligt og giver mening. Dog har nogle websteder tilhørende Debian/DebConf/SPI/osv., enten ikke HTTPS-understøttelse eller anvender kun SPI's egen certifikatmyndighed (og ikke en SSL-certifikatmyndighed, som alle webbrowsere stoler på). For at undgå fejlmeddelelser, for besøgende der ikke Debian, skal der ikke oprettes HTTPS-links til sådanne websteder.

Git-arkivet afviser commits indeholdende almindelige HTTP-links til Debians websteder, som understøttter HTTPS, eller hvis de indeholder HTTPS-links til de Debian-/DebConf-/SPI-websteder, som vi véd enten ikke understøtter HTTPS eller anvender certifikater, som kun er signeret af SPI.

Arbejde med oversættelser

Oversættelser bør altid holde ajour med deres tilsvarende engelsksprogede filer. Headeren translation-check i oversatte filer, anvendes til at holde styr på hvilken version af den engelskesprogede fil, den aktuelle oversættelse er baseret på. Hvis du ændrer oversate filer, skal du opdatere translation-check-headeren til at svare til Git-commithashværdien i den tilhørende ændring af den engelsksprogede fil. Du kan finde hashværdien med:

  $ git log sti/til/engelsk/fil

Hvis du foretager en ny oversættelse af en fil, så benyt skriptet copypage.pl, da det opretter en skabelon for dit sprog, herunder den korrekte translation-header.

Oversættelsesændringer med smart_change.pl

smart_change.pl er et skript beregnet til at gøre det lettere at opdatere originale filer og deres oversættelser på samme tid. Der er to måder at anvende skriptet på, afhængigt af hvilke ændringer, du laver.

For at anvende smart_change til blot at opdatere translation-check-headere, når du manuelt arbejder på filer:

  1. Foretag ændringerne i de(n) original(e) fil(er), og udfør commit
  2. Opdater oversættelser
  3. Udfør smart_change.pl - det opsamler ændringerne og opdaterer headerne i de oversatte filer
  4. Gennemse ændringerne (fx med git diff)
  5. Commit oversættelsesændringerne

Eller, hvis du anvender smart_change med et regulært udtræk, for at foretage adskillige ændringer på tværs af filer i ét gennemløb:

  1. Kør smart_change.pl -s s/FOO/BAR/ origfil1 origfil2 ...
  2. Gennemse ændringerne (fx med git diff)
  3. Commit de(n) original(e) fil(er)
  4. Kør smart_change.pl origfil1 origfil2 (dvs. denne gang uden regexp'en); det vil nu kun opdatere headerne i de oversatte filer
  5. Slutteligt commit'es ændringerne til oversættelserne

Det er mere kompliceret end tidligere (behov for to commits), men uundgåeligt på grund af den måde, Gits commithashes fungerer.

Modtag notifikationer

Modtag commit-notifikationer

I Salsa har vi opsat projektet således, at commits vises i IRC-kanalen

Hvis du ønsker at modtage notifikationer via mail, når der er commits til webwml-arkivet, så tilmeld dig pseudopakken www.debian.org via tracker.debian.org, og aktiver dér nøgleordet vcs, ved kun en enkelt gang at gøre som følger:

Modtag Merge Request-notifikationer

Ønsker du at modtage notifikationsmails når der er indsendes nye Merge Requests til webwml-arkivets webgrænseflade på Salsa GitLab-platformen, kan du opsætte dine notifikationsindstillinger for webwml-arkivet i webgrænsefladen: