Git gebruiken om aan de website van Debian te werken

Werken op de Git-opslagplaats

Laten we er meteen aan beginnen — in dit deel leert u hoe u een lokale kopie van de hoofdopslagplaats kunt maken, hoe u die kopie up-to-date kunt houden en hoe u uw werk kunt indienen. We zullen ook uitleggen hoe u aan vertalingen kunt werken.

Een lokale kopie ophalen

Eerst moet u Git installeren. Daarna moet u Git configureren en uw naam en e-mailadres opgeven. Indien u een nieuwe gebruiker van Git bent, is het wellicht een goed idee om eerst de algemene documentatie over Git te lezen.

Uw volgende stap is de opslagplaats klonen (met andere woorden: er een lokale kopie van maken). Er zijn twee manieren om dit te doen:

Tip: Om de volledige webwml-opslagplaats te klonen, moet u ongeveer 1,3 GB data downloaden, wat te veel zou kunnen zijn als u een langzame, onstabiele internetverbinding gebruiktt. Daarom is het mogelijk een minimale diepte te specificeren voor een kleinere initiële download: 

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

Nadat een bruikbare (ondiepe) kopie van de opslagplaats is verkregen, kunt u de diepte ervan vergroten en dit uiteindelijk omzetten naar een volledige lokale opslagplaats:

  git fetch --deepen=1000 # de opslagplaats verdiepen met nog eens 1.000 vastleggingen
  git fetch --unshallow   # alle ontbrekende vastleggingen ophalen en de opslagplaats daarmee vervolledigen

U kunt ook een kopie maken van slechts een gedeelte van de pagina's:

  1. git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. Maak het bestand .git/info/sparse-checkout aan binnen de map webwml om te definiëren van welke inhoud u een kopie wilt maken. Bijvoorbeeld, indien u enkel de basisbestanden en de Engelse, Franse en Nederlandse vertaling wilt ophalen, zal het bestand er zo uitzien: 
          /*
      !/[a-z]*/
      /english/
      /french/
      /dutch/
  5. Tenslotte kunt u nu de opslagplaats kopiëren: git checkout --

Lokale wijzigingen indienen

Uw lokale kopie van de opslagplaats up-to-date houden

Om de paar dagen (en zeker voordat u met bewerken begint!) moet u het volgende commando uitvoeren:

  git pull

om alle gewijzigde bestanden op te halen uit de opslagplaats.

Het wordt sterk aanbevolen om uw lokale Git-werkmap schoon te houden voordat u het commando git pull uitvoert en begint met het bewerken van bestanden. Als u nog niet-vastgelegde wijzigingen heeft of lokale vastleggingen die niet aanwezig zijn in de huidige tak in de externe opslagplaats, zal het uitvoeren van het commando git pull automatisch samenvoegingsconflicten creëren of zelfs mislukken ten gevolge van conflicten. Denk eraan om uw onvoltooide werk in een aparte tak te houden of commando's te gebruiken zoals git stash.

Opmerking: Git is een gedistribueerd (en geen gecentraliseerd) versiebeheersysteem. Dit betekent dat wanneer u wijzigingen vastlegt, deze enkel in uw lokale opslagplaats opgeslagen worden. Om deze met anderen te delen, zult u uw wijzigingen ook moeten laten opnemen in de centrale opslagplaats op Salsa.

Voorbeeld: enkele bestanden bewerken

Laten we eens kijken naar een meer praktisch voorbeeld en een typische bewerkingssessie. We gaan ervan uit dat u een lokale kopie van de opslagplaats verkregen heeft met het commando git clone. De volgende stappen zijn dan:

  1. git pull
  2. Nu kunt u met bewerken beginnen en de bestanden aanpassen.
  3. Als u klaar bent, leg dan uw wijzigingen vast in uw lokale opslagplaats: 
        git add pad/naar/bestand(en)
    git commit -m "Uw vastleggingsbericht"
  4. Als u onbeperkte schrijftoegang heeft tot de externe webwml-opslagplaats, kunt u uw wijzigingen nu rechtstreeks laten opnemen in de Salsa-opslagplaats: git push
  5. Als u geen directe schrijftoegang heeft tot de webwml-opslagplaats, dien dan uw wijzigingen in met een samenvoegingsverzoek (merge request of vraag andere ontwikkelaars om hulp.

Bugs in Debian sluiten met Git-vastleggingen

Als u bij uw vastlegging in het logboekbericht Closes: #nnnnnn opneemt, dan zal bugnummer #nnnnnn automatisch gesloten worden wanneer u uw wijzigingen laat opnemen. De precieze vorm ervan is dezelfde als die welke vermeld wordt in de Debian beleidsrichtlijnen.

Linken met gebruik van HTTP/HTTPS

Veel Debian-websites ondersteunen SSL/TLS, gebruik dus HTTPS-links waar dat mogelijk en verstandig is. Echter, sommige Debian, DebConf, SPI, enz. websites hebben ofwel geen ondersteuning voor HTTPS, of maken alleen gebruik van de CA van SPI (en geen SSL-CA die door alle browsers wordt vertrouwd). Om te vermijden dat niet-Debian-gebruikers foutmeldingen krijgen, gelieve niet naar die sites te linken met gebruik van HTTPS.

De git-opslagplaats weigert vastleggingen die gewone HTTP-links bevatten naar Debian-websites die HTTPS ondersteunen of die HTTPS-links bevatten naar de websites van Debian, DebConf en SPI waarvan bekend is dat ze geen HTTPS ondersteunen, of certificaten gebruiken die alleen zijn ondertekend door SPI.

Aan vertalingen werken

Een vertaling moet altijd up-to-date gehouden worden met het overeenkomstige Engelse bestand. De kopregel translation-check in vertaalde bestanden wordt gebruikt om bij te houden op welke versie van het Engelse bestand de huidige vertaling gebaseerd is. Indien u een vertaald bestand wijzigt, moet u de kopregel translation-check bijwerken, zodat die overeenkomt met de Git-vastleggingsfrommel van de overeenkomstige aanpassing van het Engelse bestand. U kunt deze frommel terugvinden met:

  git log pad/naar/het/Engelse/bestand

Indien u een nieuwe vertaling gaat maken van een bestand, moet u het script copypage.pl gebruiken. Dit maakt een sjabloon aan voor uw taal, met inbegrip van de correcte vertalingskopregel.

Vertalingen aanpassen met smart_change.pl

smart_change.pl is een script dat ontworpen is om het gezamenlijk updaten van originele bestanden en hun vertalingen makkelijker te maken. U kunt het op twee manieren gebruiken, afhankelijk van welke wijzigingen u aanbrengt.

Wanneer u handmatig aan de bestanden werkt, is dit de manier waarop u smart_change.pl kunt gebruiken en de wijze waarop u de kopregels over translation-check gewoon kunt updaten:

  1. Breng de wijzigingen aan in het/de origine(e)l(e) bestand(en), en leg deze vast.
  2. Werk de vertalingen bij.
  3. Voer het commando smart_change.pl -c VASTLEGGINGS-HASH uit (gebruik de vastleggingshash van de wijzigingen aan het/de origine(e)l(e) bestand(en)). Dit zal de aanpassingen oppikken en in de vertaalde bestanden de kopregel updaten.
  4. Controleer de wijzigingen (bijv. met git diff).
  5. Leg de wijzigingen in de vertalingen vast.

Een andere mogelijkheid is het toepassen van een reguliere expressie om in één keer een wijziging in meerdere bestanden door te voeren:

  1. Geef het commando smart_change.pl -s s/FOO/BAR/ origbestand1 origbestand2 ...
  2. Controleer de wijzigingen (bijv. met git diff).
  3. Leg het/de origine(e)l(e) bestand(en) vast.
  4. Geef het commando smart_change.pl origbestand1 origbestand2 (d.w.z. ditmaal zonder de reguliere expressie). Dit zal nu enkel de kopregels in de vertaalde bestanden updaten.
  5. Leg tenslotte de gewijzigde vertalingen vast.

Toegegeven, dit heeft wat meer voeten in de aarde dan het eerste voorbeeld, omdat er twee vastleggingen nodig zijn, maar dit is onvermijdelijk door de manier waarop de Git-vastleggingshashes werken.

Schrijftoegang tot de Git-opslagplaats

De broncode van de website van Debian wordt beheerd met Git en ze bevindt zich op https://salsa.debian.org/webmaster-team/webwml. Standaard mogen gasten geen vastleggingen toepassen in de broncode-opslagplaats. Als u wilt bijdragen aan de website van Debian, zult u schrijftoegang tot de opslagplaats moeten verkrijgen.

Onbeperkte schrijftoegang

Als u onbeperkte schrijftoegang tot de opslagplaats nodig heeft, bijv. als u van plan bent frequente bijdragen te gaan leveren, vraag dan schrijftoegang aan via de https://salsa.debian.org/webmaster-team/webwml webinterface nadat u inlogde op het Salsa-platform van Debian.

Als u een nieuw bent bij de ontwikkeling van de Debian-website en geen eerdere ervaring heeft, wilt u dan ook een e-mail zenden naar debian-www@lists.debian.org om uzelf voor te stellen, voordat u onbeperkte schrijftoegang vraagt. Wilt u ons dan ook wat meer over uzelf vertellen, zoals aan welk gedeelte van de website u wilt gaan werken, welke talen u spreekt, en ook of een ander teamlid van Debian voor u in kan staan.

Samenvoegingsverzoeken (Merge Requests)

Het is niet noodzakelijk onbeperkte schrijftoegang tot de opslagplaats te verkrijgen — u kunt altijd een samenvoegingsverzoek (Engels: merge request) indienen en andere ontwikkelaars uw werk laten nakijken en aanvaarden. Volg daarvoor de standaardprocedure voor samenvoegingsverzoeken die geboden wordt door de webinterface van het Salsa GitLab-platform en lees de volgende twee documenten:

Gelieve er nota van te nemen dat niet alle website-ontwikkelaars op de uitkijk staan voor samenvoegingsverzoeken. Daarom kan het enige tijd duren voordat u wat terug hoort. Als u zich afvraagt of uw bijdrage wel toegepast zal worden, zend dan een e-mail naar de mailinglijst debian-www en vraag om een beoordeling.

Meldingen ontvangen

Als u werkt aan de website van Debian, zult u waarschijnlijk willen weten wat er in de opslagplaats webwml gaande is. Er zijn twee manieren om daarbij betrokken te blijven: vastleggingsmeldingen en meldingen van samenvoegingsverzoeken.

Vastleggingsmeldingen ontvangen

We hebben het webwml-project in Salsa zo geconfigureerd dat vastleggingen worden getoond in het IRC-kanaal #debian-www.

Als u via e-mail meldingen wilt ontvangen over vastleggingen in de opslagplaats van webwml, abonneer u dan op het pseudopakket www.debian.org via tracker.debian.org en activeer daar het trefwoord vcs door eenmalig de volgende stappen te doorlopen:

  1. Open een webbrowser en ga naar https://tracker.debian.org/pkg/www.debian.org.
  2. Teken in op het pseudopakket www.debian.org. (U kunt authenticeren via SSO of een e-mail en wachtwoord registreren, indien u niet reeds gebruik maakte van tracker.debian.org voor andere doeleinden).
  3. Ga naar https://tracker.debian.org/accounts/subscriptions, en dan naar modify keywords, vink vcs aan (als het nog niet aangevinkt is) en bewaar.
  4. Vanaf dan zult u een e-mail ontvangen wanneer iemand een vastlegging in de webwml-opslagplaats doet.

Meldingen over samenvoegingsverzoeken ontvangen

Als u een melding via e-mail wilt ontvangen wanneer er een nieuw samenvoegingsverzoek ingediend werd op de webwml-opslagplaats in Salsa, kunt u uw instellingen voor meldingen in de webinterface configureren door deze stappen te volgen:

  1. Log in op uw Salsa-account en ga naar de projectpagina.
  2. Klik op het bel-icoontje bovenaan de hoofdpagina van het project.
  3. Selecteer het meldingsniveau waaraan u de voorkeur geeft.