Ir al contenido principal
Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Cómo contribuir código a Jellyfin

Esta página explica cómo están organizados nuestros repositorios, cómo comenzar a editar código y crear tu primer pull request, junto con procedimientos generales para pull requests en Jellyfin.

¿En qué deberías trabajar?​

Existen muchos proyectos dentro de la organización para explorar y contribuir. Aquí resumimos los dos principales: uno para desarrolladores backend y otro para frontend.

  • Jellyfin Server: La parte del servidor, desarrollada con .NET 9 y C#.

  • Jellyfin Web: La aplicación cliente principal para navegadores, también utilizada en otros clientes que son solo wrappers.

Cada repositorio incluye su propia documentación sobre cómo comenzar con el proyecto, generalmente en el README del repositorio. También puedes consultar el árbol de fuentes de la organización para ver cómo están estructurados los proyectos más grandes.

La mejor forma de empezar a desarrollar es revisar la lista de issues del repositorio correspondiente, encontrar un issue que te interese trabajar y ¡comenzar a programar! El equipo administrativo clasifica los issues regularmente y asigna etiquetas que ayudan a identificar tareas acordes a tu nivel. Cuando comiences a trabajar en un issue, comenta indicando tu intención de abordarlo para evitar duplicación de esfuerzos.

Tipos principales de issues​

Puedes encontrar una lista de tipos de issues en la sección de directrices para issues.

¿Y si no existe un issue?​

Si no existe un issue relacionado con los cambios que quieres realizar, primero crea un issue para registrarlo, luego asegúrate de que tu PR(s) referencien dicho issue. Esto es especialmente útil para errores que son encontrados y corregidos por el autor, permitiendo documentar y rastrear tanto el problema original como su solución.

¿Cómo deberías realizar cambios?​

Una vez que encuentres algo para trabajar o mejorar, el siguiente paso es modificar el código, probar los cambios y luego enviar un Pull Request (PR) en GitHub.

Por simplicidad, los ejemplos asumen que el desarrollador usa Linux con acceso SSH a GitHub, pero los conceptos son aplicables a interfaces HTTP de GitHub y pueden adaptarse a Windows o macOS.

Si no estás familiarizado con Git, te recomendamos la documentación oficial para entender cómo funciona este sistema de control de versiones.

Configura tu copia del repositorio​

El primer paso es configurar una copia del repositorio Git del proyecto al que quieres contribuir. Jellyfin sigue un modelo de contribución "fork, rama de función y PR".

  1. En GitHub, haz "Fork" del repositorio de Jellyfin al que deseas contribuir, usando el botón "Fork" en tu cuenta personal.

  2. Clona tu fork en tu máquina local e ingresa al directorio:

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

  3. Añade el remoto "upstream" para sincronizar cambios del proyecto principal fácilmente:

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

  4. Para que el proyecto Jellyfin.Server se ejecute correctamente, debes clonar tanto el servidor como el cliente web.

  5. Compila el proyecto Jellyfin Web con NPM y copia la ubicación de la carpeta dist resultante.

  6. En tu proyecto Jellyfin.Server, añade una variable de entorno llamada JELLYFIN_WEB_DIR con el valor de la ruta completa a tu carpeta dist.

Ahora estarás listo para comenzar a construir o modificar el proyecto.

Realizar cambios en el repositorio​

Una vez que tengas tu repositorio configurado, puedes comenzar a trabajar.

  1. Actualiza tus ramas locales con respecto a la rama master del upstream para trabajar con los últimos cambios:

    git fetch --all
    git rebase upstream/master

  2. Crea una rama local de características desde master para realizar tus cambios:

    git checkout -b my-feature master

  3. Realiza tus cambios y commits en esta rama local de características.

  4. Repite el paso 1 en tu rama de características una vez finalizado tu trabajo, para asegurarte de que no hay conflictos con otros cambios realizados desde que comenzaste.

  5. Sube tu rama de características local a tu fork en GitHub:

    git push --set-upstream origin my-feature

  6. En GitHub, crea un nuevo Pull Request (PR) contra la rama master del upstream siguiendo las recomendaciones que se indican más adelante.

  7. Una vez que tu PR sea fusionado, asegúrate de mantener tus ramas locales actualizadas:

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

  8. Elimina tu rama de características local si ya no la necesitas:

    git branch -d my-feature

CONTRIBUTORS.md​

Si es tu primera vez contribuyendo código a un repositorio específico, por favor añádete al archivo CONTRIBUTORS.md en la sección Jellyfin Contributors. Aunque GitHub realiza este seguimiento, tener un documento escrito facilita la claridad si el código abandona GitHub y permite que cualquiera pueda ver rápidamente quién ha trabajado en el proyecto para efectos de derechos de autor o reconocimiento.

Ramas oficiales​

Ramas de características​

Ocasionalmente, pueden surgir proyectos importantes que requieran múltiples PRs y contribuciones de varias personas. Para estas tareas, se deben crear ramas específicas basadas en master. Esto permite que el trabajo avance sin romper master durante largos períodos y da flexibilidad a los colaboradores. Para crear una rama de características, comunícate con un miembro del equipo Core.

Una vez que la funcionalidad de una rama esté lista, puede fusionarse en master y eliminarse la rama. Para funcionalidades de larga duración, se pueden fusionar versiones estables en master según sea necesario.

La rama Master​

La rama master es la rama principal de desarrollo. Excepto para correcciones críticas de emergencia, todos los PRs deben apuntar a master. Como regla general, ningún PR debe romper master y todas las solicitudes deben probarse antes de fusionarse. Aunque somos humanos y pueden ocurrir errores, generalmente master debe ser estable para quienes deseen la última versión de Jellyfin.

Probar un Pull Request​

Para probar el pull request de otra persona, debes importar los cambios a tu repositorio local.

  1. Obtén los cambios de una solicitud de extracción (pull request) y vincúlalos a una nueva rama local:

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

    <PR_ID> corresponde al número de la solicitud de extracción en GitHub.

  2. Cambia a la nueva rama local:

    git checkout my-testing-branch

  3. Realiza las pruebas o compilaciones necesarias, luego vuelve a la rama principal y elimina la rama temporal:

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

Directrices para Solicitudes de Extracción (Pull Requests)​

Al enviar una nueva solicitud de extracción (PR), asegúrate de seguir estas pautas. Si no estás familiarizado, te recomendamos leer Cómo escribir un mensaje de confirmación en Git, un excelente recurso para redactar mensajes útiles.

  • Antes de enviar una PR, compacta ("squash") las confirmaciones menores para mantener el historial limpio. Una confirmación debe representar un cambio significativo: evita compactar todos los cambios juntos en PRs grandes, pero también elimina confirmaciones como "arreglado esto" o "error tipográfico" que solo generan ruido en el historial del proyecto.

  • Escribe un título descriptivo que resuma rápidamente los cambios. Por ejemplo, "Agrega soporte LDAP a Jellyfin". Como se menciona en Cómo escribir un mensaje de confirmación en Git, usa siempre el modo imperativo y mantén el título breve pero informativo. El título eventualmente será una entrada en el registro de cambios, así que utiliza mayúsculas correctamente sin signos de puntuación; el equipo central podría ajustar los títulos para cumplir con este estándar antes de fusionar.

  • Para cambios que no sean triviales y requieran más explicación que el título, sigue la plantilla de PR y describe en el cuerpo con tanto detalle como sea necesario:

    1. Por qué se realizan los cambios. Referencia incidencias específicas con palabras clave (fixes, closes, addresses, etc.) cuando sea posible.

    2. Cómo abordaste el problema (si aplica) y describe brevemente los cambios, especialmente en PRs extensas.

  • Si tu solicitud de extracción aún no está finalizada, márcala como "borrador" al crearla. Mientras tenga esta etiqueta, no se fusionará y las revisiones serán solo comentarios. Cuando estés satisfecho con el estado final, elimina esta etiqueta; ¡olvidarlo podría hacer que tu PR pase desapercibida! Las PRs inactivas podrían recibir recordatorios del equipo sobre su estado y cerrarse si no hay respuesta.

  • Evita reorganizar ("rebase") y forzar subidas ("force-push") en solicitudes de extracción grandes o complejas, especialmente después de revisiones. Esto obliga a revisiones innecesarias para verificar que los cambios siguen siendo válidos y se compilan correctamente.

  • Espera revisiones y discusiones. Si no puedes respaldar tus cambios con una buena descripción y soporte técnico, reconsidera si deberían implementarse. Todas las PRs a dev requieren al menos una aprobación de un miembro del equipo administrativo, aunque fomentamos revisiones de cualquier colaborador, especialmente si conoces el área. Más ojos siempre son mejores.

  • Todas las PRs requieren revisión de al menos dos miembros del equipo antes de fusionarse en master, ¡aunque son bienvenidas las revisiones de cualquier colaborador! Tras la segunda revisión, la PR podrá fusionarse inmediatamente o solicitarse más retroalimentación explícitamente si es necesario.

Compilación y Pruebas dentro de un Contenedor Docker​

Debemos instalar todas las dependencias de desarrollo y obtener el código dentro del contenedor antes de compilar y ejecutar.

nota

Ejecuta cada comando en una línea separada. El contenedor de prueba se llama jftest. Dentro de Docker, cuando se termina el ejecutable principal, la sesión se reinicia; simplemente vuelve a acceder para continuar. Por esto también lo detenemos explícitamente para recargar la nueva versión.

Rama Principal (Master)​

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)

Solicitud de Extracción (Pull Request)​

Primero, completa los pasos anteriores para configurar tu contenedor y compilar la rama principal.

nota

<PR_ID> es el número de la pull request en 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)