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:
- Een account aanmaken op https://salsa.debian.org en SSH-toegang
mogelijk maken door een openbare SSH-sleutel naar uw Salsa-account te
uploaden. Raadpleeg de Hulppagina's over Salsa
voor meer details. Daarna kunt u de
webwml
-opslagplaats klonen met het volgende commando:git clone git@salsa.debian.org:webmaster-team/webwml.git
- Een andere mogelijkheid is de opslagplaats te klonen met het
HTTPS-protocol. Houd er rekening mee dat dit de lokale kopie van de
opslagplaats wel zal aanmaken, maar u zult dan lokale wijzigingen
niet rechtstreeks kunnen laten opnemen in de hoofdopslagplaats:
git clone https://salsa.debian.org/webmaster-team/webwml.git
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:
git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
cd webwml
git config core.sparseCheckout true
- Maak het bestand
.git/info/sparse-checkout
aan binnen de mapwebwml
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/
- 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:
git pull
- Nu kunt u met bewerken beginnen en de bestanden aanpassen.
- Als u klaar bent, leg dan uw wijzigingen vast in uw lokale
opslagplaats:
git add pad/naar/bestand(en) git commit -m "Uw vastleggingsbericht"
- Als u onbeperkte schrijftoegang heeft tot de
externe
webwml
-opslagplaats, kunt u uw wijzigingen nu rechtstreeks laten opnemen in de Salsa-opslagplaats:git push
- 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:
- Breng de wijzigingen aan in het/de origine(e)l(e) bestand(en), en leg deze vast.
- Werk de vertalingen bij.
- 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. - Controleer de wijzigingen (bijv. met
git diff
). - 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:
- Geef het commando
smart_change.pl -s s/FOO/BAR/ origbestand1 origbestand2 ...
- Controleer de wijzigingen (bijv. met
git diff
). - Leg het/de origine(e)l(e) bestand(en) vast.
- 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. - 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:
- Project forking workflow (Werkwijze bij het maken van een kopie (een zogenaamde fork) van een project
- When you work in a fork (Wanneer u in een kopie werkt)
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:
- Open een webbrowser en ga naar https://tracker.debian.org/pkg/www.debian.org.
- 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). - Ga naar https://tracker.debian.org/accounts/subscriptions, en dan
naar
modify keywords
, vinkvcs
aan (als het nog niet aangevinkt is) en bewaar. - 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:
- Log in op uw Salsa-account en ga naar de projectpagina.
- Klik op het bel-icoontje bovenaan de hoofdpagina van het project.
- Selecteer het meldingsniveau waaraan u de voorkeur geeft.