Doorgaan naar hoofdinhoud
Onofficiële Beta-vertaling

Deze pagina is vertaald door PageTurner AI (beta). Niet officieel goedgekeurd door het project. Een fout gevonden? Probleem melden →

Hoe code bijdragen aan Jellyfin

Deze pagina legt uit hoe onze repositories georganiseerd zijn, hoe je begint met code bewerken en je eerste pull request maakt, en algemene procedures voor pull requests bij Jellyfin.

Waar kun je aan werken?​

Er zijn veel projecten binnen de organisatie om door te bladeren voor bijdragen. Hieronder vind je de twee grootste projecten, één voor backend-ontwikkelaars en één voor frontend-ontwikkelaars.

  • Jellyfin Server: Het servergedeelte, gebouwd met .NET 9 en C#.

  • Jellyfin Web: De belangrijkste clientapplicatie voor browsers, ook gebruikt in sommige andere clients die simpelweg wrappers zijn.

Elke repository heeft eigen documentatie over hoe je met dat project begint, meestal te vinden in de repository README. Bekijk ook de bronstructuur van de organisatie om te zien hoe grotere projecten zijn opgebouwd.

De beste manier om aan ontwikkeling te beginnen is door de issueslijst van de bijbehorende repository te bekijken, een issue te kiezen waar je aan wilt werken, en aan de slag te gaan! Issues worden regelmatig gesorteerd door het beheerteam, met labels die je helpen issues binnen je expertise te vinden. Laat een reactie achter op het issue zodra je begint, om dubbele werkzaamheden te voorkomen.

Belangrijkste issuetypes​

Een overzicht van issuetypes vind je in het gedeelte over issue-richtlijnen.

Wat als er geen issue bestaat?​

Als er nog geen issue is voor je gewenste wijzigingen, maak dan eerst een issue aan en zorg dat je PR(s) ernaar verwijzen. Dit is vooral nuttig voor bugs die door de auteur zelf worden gevonden en opgelost, zodat zowel het oorspronkelijke probleem als de oplossing gedocumenteerd kunnen worden.

Hoe maak je wijzigingen?​

Zodra je iets hebt gevonden om aan te werken, is de volgende stap: wijzigingen in de code aanbrengen, testen en een Pull Request (PR) op GitHub indienen.

Voor de eenvoud gaan de voorbeelden uit van een Linux-ontwikkelaar met SSH-toegang tot GitHub, maar de principes gelden ook voor HTTP-gebaseerde GitHub-interfaces en zijn vertaalbaar naar Windows of macOS.

Als je niet bekend bent met Git, raden we de officiële documentatie aan om te begrijpen hoe dit versiebeheersysteem werkt.

Je repository-kopie instellen​

De eerste stap is een kopie maken van de Git-repository waaraan je wilt bijdragen. Jellyfin hanteert een "fork, feature-branch en PR"-model voor bijdragen.

  1. "Fork" de Jellyfin-repository op GitHub naar je eigen account via de "Fork"-knop in de betreffende repository.

  2. Kloon je fork naar je lokale machine en ga naar de map:

    git clone git@github.com:yourusername/projectname.git
    cd projectname/

  3. Voeg de "upstream"-remote toe om eenvoudig wijzigingen van het hoofdproject op te halen:

    git remote add upstream git@github.com:jellyfin/projectname.git

  4. Om het Jellyfin.Server project succesvol te laten draaien, moet je zowel de server als het web client project uitchecken.

  5. Bouw het Jellyfin Web-project met NPM en kopieer het pad naar de resulterende dist map.

  6. Voeg in je Jellyfin.Server project een omgevingsvariabele genaamd JELLYFIN_WEB_DIR toe, met als waarde het volledige pad naar je dist map.

Je bent nu klaar om te beginnen met bouwen of aanpassen van het project.

Veranderingen aanbrengen in de repository​

Zodra je je repository hebt, kun je aan de slag.

  1. Synchroniseer je lokale branches met de upstream master branch zodat je werkt met de laatste wijzigingen:

    git fetch --all
    git rebase upstream/master

  2. Maak een lokale feature branch aan vanaf master om je wijzigingen in door te voeren:

    git checkout -b my-feature master

  3. Breng je wijzigingen aan en commit deze op deze lokale feature branch.

  4. Herhaal stap 1 op je lokale feature branch zodra je klaar bent, om te zorgen dat er geen conflicten zijn met andere wijzigingen sinds je begon.

  5. Push je lokale feature branch naar je GitHub fork:

    git push --set-upstream origin my-feature

  6. Maak op GitHub een nieuwe PR aan tegen de upstream master branch, volgens de onderstaande richtlijnen.

  7. Zodra je PR is samengevoegd, zorg ervoor dat je je lokale branches up-to-date houdt:

    git fetch --all
    git checkout master
    git rebase upstream/master
    git push -u origin master

  8. Verwijder je lokale feature branch als je hem niet meer nodig hebt:

    git branch -d my-feature

CONTRIBUTORS.md​

Als je voor het eerst code bijdraagt aan een bepaalde repository, voeg jezelf dan toe aan het CONTRIBUTORS.md bestand onder de sectie Jellyfin Contributors. Hoewel GitHub dit bijhoudt, maakt een geschreven document zaken duidelijker als de code GitHub verlaat, en laat het iedereen snel zien wie aan het project heeft gewerkt voor auteursrecht of erkenning!

Officiële Branches​

Feature Branches​

Van tijd tot tijd kunnen er grote projecten ontstaan die meerdere PR's en bijdragen van verschillende mensen vereisen. Voor deze taken moeten specifieke feature branches worden aangemaakt, gebaseerd op master. Dit helpt om het werk te laten voortgang zonder master lange tijd te verstoren, en stelt geïnteresseerden in staat in hun eigen tempo te werken in plaats van te racen om een feature voor de volgende release te repareren. Neem contact op met een Core teamlid om een feature branch aan te maken.

Zodra de feature waarvoor een branch is gemaakt klaar is, kan deze in één keer worden samengevoegd in master en kan de feature branch worden verwijderd. Voor zeer langdurige features kunnen bepaalde "stabiele" momentopnamen indien nodig in master worden samengevoegd.

De Master Branch​

De master branch is het primaire gezicht van het project en de belangrijkste ontwikkelingsbranch. Behalve voor noodhotfixes voor releases, moeten alle PR's gericht zijn op master. Over het algemeen mag geen enkele PR master breken, en alle PR's moeten vooraf worden getest om dit te voorkomen. We zijn ook maar mensen en dit kan nog steeds gebeuren, maar over het algemeen kun je veilig bouwen op master als je de nieuwste versie van Jellyfin wilt.

Een Pull Request testen​

Om iemand anders's pull request te testen, moet je de wijzigingen importeren in je lokale repository.

  1. Haal de wijzigingen van een pull request op en koppel ze aan een nieuwe lokale branch:

    git fetch upstream pull/<PR_ID>/head:my-testing-branch
    opmerking

    <PR_ID> is het pull request-nummer op GitHub.

  2. Check uit op de nieuwe lokale branch:

    git checkout my-testing-branch

  3. Voer eventuele benodigde tests of builds uit, keer daarna terug naar master en verwijder de branch:

    git checkout master
    git branch -D my-testing-branch

Richtlijnen voor Pull Requests​

Bij het indienen van een nieuwe PR, zorg ervoor dat je de volgende zaken doet. Lees als je dat nog niet gedaan hebt How to Write a Git Commit Message, dit is een uitstekende bron voor het schrijven van nuttige commitberichten.

  • Squash "rommel-commits" samen voordat je een PR indient om de geschiedenis overzichtelijk te houden. Één commit hoort één significante wijziging te beslaan: vermijd het samensquashen van alle wijzigingen, vooral bij grote PR's die veel bestanden raken, maar laat ook geen "dit gefixt", "oeps typo"-commits in je branchgeschiedenis staan aangezien dit overbodige rommel veroorzaakt in de uiteindelijke projectgeschiedenis.

  • Schrijf een duidelijke titel die kort beschrijft wat er gewijzigd is. Bijvoorbeeld: "Voeg LDAP-ondersteuning toe aan Jellyfin". Zoals vermeld in How to Write a Git Commit Message, gebruik altijd de gebiedende wijs en houd de titel kort maar beschrijvend. De titel wordt uiteindelijk een changelog-entry, dus gebruik hoofdlettergebruik maar geen leestekens; het kernteam kan titels aanpassen om beter aan deze standaard te voldoen voor het mergen.

  • Voor alles behalve de meest triviale wijzigingen die volledig in de (korte) titel beschreven kunnen worden, volg de PR-sjabloon en schrijf een PR-body om zo gedetailleerd mogelijk te beschrijven:

    1. Waarom de wijzigingen worden gemaakt. Verwijs naar specifieke issues met trefwoorden (fixes, closes, addresses, etc.) waar mogelijk.

    2. Hoe je het probleem hebt aangepakt (indien van toepassing) en beschrijf kort de wijzigingen, vooral bij grote PR's.

  • Markeer je pull request als "draft" bij het openen als deze nog niet af is. Zolang dit label actief is, wordt de pull request niet gemergd en blijven reviews beperkt tot commentaar. Verwijder dit label zodra je tevreden bent met de eindstatus; vergeten dit te doen kan resulteren in onbedoelde verwaarlozing van je PR als actief in ontwikkeling! Inactieve WIP's kunnen af en toe een ping van het team krijgen voor een statusupdate en worden gesloten bij geen reactie.

  • Vermijd rebasen en force-pushen bij grote of complexe pull requests waar mogelijk, vooral na reviews. Het dwingt tot onnodige hercontroles om te verifiëren of de wijzigingen nog correct zijn en correct bouwen.

  • Reken op review en discussie. Als je je wijzigingen niet kunt onderbouwen met een goede beschrijving en door review, overweeg dan of het überhaupt gedaan zou moeten worden. Alle PR's naar dev vereisen minstens één goedkeurende review van een kernteamlid, maar we verwelkomen en moedigen reviews van alle contributors aan, vooral in domeinen waar je kennis van hebt. Meer ogen zijn altijd beter.

  • Alle PR's vereisen een review door minstens twee teamleden voor merging in master, hoewel reviews van alle contributors welkom zijn! Na de tweede teamreview kan de PR direct gemerged worden, of er kan expliciet om meer feedback van andere contributors gevraagd worden indien nodig.

Bouwen en testen in een Docker-container​

We moeten alle ontwikkelafhankelijkheden installeren en de code binnen de container ophalen voordat we kunnen compileren en uitvoeren.

opmerking

Voer elk commando op een aparte regel uit. De container waarin we testen heet jftest. Binnen Docker wordt de sessie opnieuw gestart wanneer het entrypoint-executable eindigt, dus exec gewoon opnieuw om verder te gaan. Dit is ook waarom we het expliciet stoppen om de nieuwe versie te laden.

Master Branch​

docker exec -ti jftest bash
apt-get update && apt-get install -y git gnupg curl autoconf g++ make libpng-dev gifsicle automake libtool gcc musl-dev nasm ca-certificates
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl -LO https://packages.microsoft.com/config/debian/12/prod.list && mv prod.list /etc/apt/sources.list.d/microsoft-prod.list
apt-get update && apt-get install -y dotnet-sdk-8.0
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
apt-get update && apt-get install -y nodejs
cd /opt && git clone https://github.com/jellyfin/jellyfin.git && git clone https://github.com/jellyfin/jellyfin-web.git
cd jellyfin/ && DOTNET_CLI_TELEMETRY_OPTOUT=1 && DOTNET_CLI_HOME="/tmp/" dotnet publish Jellyfin.Server --configuration Debug --output="/jellyfin" --self-contained --runtime linux-x64
cd /opt/jellyfin-web && npm install && npm run build:development && cp -r /opt/jellyfin-web/dist /jellyfin/jellyfin-web
apt-get remove -y gnupg curl && apt-get clean -y autoclean && apt-get autoremove -y
kill -15 $(pidof jellyfin)

Pull Request​

Voltooi eerst de bovenstaande stappen om je container in te stellen voor het bouwen van de master branch.

opmerking

<PR_ID> is het pull request-nummer op GitHub.

docker exec -ti jftest bash
cd /opt/jellyfin
git fetch origin pull/<PR_ID>/head:my-testing-branch
git merge my-testing-branch
dotnet build
kill -15 $(pidof jellyfin)