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 om de opslagplaats te klonen met behulp van het
HTTPS-protocol. Houd er rekening mee dat hierdoor de lokale kopie van de
opslagplaats aangemaakt zal worden, maar u op deze manier niet in staat zult
zijn om rechtstreeks wijzigingen terug toe te passen 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
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:
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 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:
git pull
- Nu kunt u met bewerken beginnen en de bestanden aanpassen.
- 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"
- Als u onbeperkte schrijftoegang heeft tot de
externe
webwml
-opslagplaats, kunt u uw wijzigingen nu rechtstreeks toepassen in de Salsa-opslagplaats:git push
- 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:
- 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 te werken met reguliere expressies om in één beweging verschillende aanpassingen in meerdere bestanden te maken:
- 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 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:
- 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)
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 tracker.debian.org en activeer daar het
trefwoord vcs
door deze stappen te volgen (slechts één keer):
- 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.