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 indien u een langzame, onstabiele internetverbinding heeft. Daarom bestaat de mogelijkheid om een minimale diepte te definiëren voor een kleinere initiële download: 

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

Nadat u een bruikbare (ondiepe) kopie van de opslagplaats verkregen heeft, kunt u deze lokale kopie verder uitdiepen en uiteindelijk omzetten naar een volledige lokale kopie van de opslagplaats:

  git fetch --deepen=1000 # de opslagplaats verder uitdiepen met 1.000 extra vastleggingen
  git fetch --unshallow   # alle ontbrekende vastleggingen ophalen en de kopie van de opslagplaats omzetten naar een volledig exemplaar

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 kopie van de opslagplaats opgeslagen worden. Om deze met anderen te delen, zult u uw wijzigingen ook naar de centrale opslagplaats op Salsa moeten toepassen.

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 kopie van de 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 toepassen in de Salsa-opslagplaats: git push
  5. Als u geen directe schrijftoegang heeft tot de webwml-opslagplaats, moet u uw wijzigingen indienen met een merge request (samenvoegingsverzoek) of contact opnemen met andere ontwikkelaars voor hulp.

Bugs in Debian sluiten met Git-vastleggingen

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

Links met HTTP/HTTPS

Veel Debian-websites ondersteunen SSL/TLS. Gebruik daarom waar mogelijk en raadzaam HTTPS-links. Echter, sommige Debian/DebConf/SPI/enz. websites hebben ofwel geen ondersteuning voor HTTPS of maken enkel gebruik van het CA van SPI (en geen SSL-CA waarin alle browsers vertrouwen stellen). Om te vermijden dat niet-Debian-gebruikers geconfronteerd worden met foutmeldingen, moet u voor dergelijke sites geen links met HTTPS gebruiken.

De git-opslagplaats weigert vastleggingen die gewone HTTP-links bevatten voor Debian-websites die HTTPS ondersteunen of die HTTPS-links bevatten voor de websites van Debian/DebConf/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 te werken met reguliere expressies om in één beweging verschillende aanpassingen in meerdere bestanden te maken:

  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 onder Git en ze bevindt zich op https://salsa.debian.org/webmaster-team/webwml. Standaard mogen gasten geen vastleggingen toepassen in de broncode-opslagplaats. Indien u wilt bijdragen tot de website van Debian, zult u een of andere vorm van toestemming nodig hebben om schrijftoegang te krijgen tot de opslagplaats.

Onbeperkte schrijftoegang

Als u onbeperkte schrijftoegang tot de opslagplaats nodig heeft, bijv. wanneer u zinnens bent om 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 nieuwkomer bent wat de ontwikkeling van de website van Debian betreft, en geen eerdere ervaring heeft, zend dan ook een e-mail naar debian-www@lists.debian.org waarin u zichzelf voorstelt, vooraleer u om onbeperkte schrijftoegang vraagt. Wees zo vriendelijk om wat meer over uzelf te vertellen, bijvoorbeeld aan welk deel van de website u van plan bent te gaan werken, welke talen u spreekt, en ook of er een ander teamlid van Debian voor u garant kan staan.

Samenvoegingsverzoeken (Merge Requests)

Het is niet noodzakelijk om onbeperkte schrijftoegang tot de opslagplaats te krijgen — u kunt altijd een samenvoegingsverzoek of merge request indienen en andere ontwikkelaars uw werk laten nakijken en aanvaarden. Volg de standaardprocedure voor het indienen van een merge request zoals die door het Salsa GitLab-platform geboden wordt via zijn webinterface en lees de volgende twee documenten:

Merk op dat niet alle website-ontwikkelaars merge requests opvolgen. Daarom kan het even duren vooraleer u feedback krijgt Als u zich afvraagt of uw bijdrage al dan niet geaccepteerd zal worden, stuur dan een e-mail naar de mailinglijst debian-www en vraag om een revisie.

Meldingen ontvangen

Als u werkt aan de website van Debian, zult u wellicht willen weten wat er in de opslagplaats webwml gebeurt. Er zijn twee manieren om op de hoogte 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 wanneer er vastleggingen gebeuren in de webwml-opslagplaats, abonneer u dan op het pseudopakket www.debian.org via ttracker.debian.org en activeer daar het trefwoord vcs door deze stappen te volgen (slechts één keer):

  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.