Skip to main content

Publicación de bibliotecas

⏱ Dedicación recomendada: 0 minutos
Esto considera el contenido visible y relevante, e ignora texto colapsado o marcado como opcional.

r8vnhill/echo-app-kt

La publicación de bibliotecas es una etapa clave en el desarrollo de software, ya que permite compartir y distribuir código reutilizable con otros proyectos o desarrolladorxs. Existen diversas formas de hacerlo, desde subir archivos de release manualmente hasta utilizar un repositorio de paquetes como GitHub Packages para gestionar versiones y dependencias de manera más eficiente.

📌 Versionado semántico (SemVer)​

Antes de publicar una biblioteca, es importante definir un esquema de versionado adecuado para garantizar compatibilidad y control sobre los cambios.

Versionado Semántico (SemVer)

Un esquema comúnmente usado es SemVer (Semantic Versioning), que sigue la estructura MAJOR.MINOR.PATCH:

  • MAJOR: Cambios incompatibles con versiones anteriores.
  • MINOR: Nuevas características compatibles con versiones anteriores.
  • PATCH: Correcciones de errores sin cambios en la API.

Ejemplo: 1.2.3 donde 1 es la versión mayor, 2 es la menor y 3 es el parche.

Este esquema permite que otrxs desarrolladorxs comprendan fácilmente la compatibilidad de una nueva versión y reduzcan el riesgo de romper integraciones en sus proyectos.

🚀 Publicando un release​

La primera forma que veremos de publicar una biblioteca es hacer un release en GitHub. Para ello, debemos seguir los siguientes pasos:

Versión más "sencilla" utilizando gh
gh release create v1.0.0 `
    .\lib\build\libs\lib-1.0.0-all.jar `
    .\lib\build\libs\lib-1.0.0-docs.jar `
    --title "Release v1.0.0" `
    --notes "Added functionality to echo a message with a timestamp"
  1. Crear un release en GitHub: Ir a la sección de "Releases" en el repositorio de la biblioteca y hacer clic en "Create a new release". Aquí debemos especificar la versión del release, un título y una descripción detallada de los cambios realizados.
  2. Subir los archivo JAR: Subir los archivos JAR generados por la biblioteca, que contienen el código compilado y la documentación.
  3. Publicar el release: Una vez completados los pasos anteriores, hacer clic en "Publish release" para publicar el release en GitHub.

📦 GitHub Packages​

GitHub Packages es un sistema integrado en GitHub que permite almacenar, gestionar y compartir paquetes de software dentro del ecosistema de GitHub, facilitando la distribución y reutilización en diferentes proyectos.

🔑 Principales características​

  • Soporte para múltiples formatos: GitHub Packages admite una variedad de tipos de paquetes, incluidos Maven, Gradle, npm, NuGet, RubyGems y Docker, entre otros.
  • Integración completa con GitHub: Puedes publicar, versionar y compartir paquetes directamente desde tus repositorios de GitHub, lo que facilita la colaboración y el control de versiones.
  • Distribución sencilla: Publicar tu biblioteca en GitHub Packages te permite integrarla de manera rápida en otros proyectos, simplificando su reutilización y acceso para tus colaboradores.

A continuación, procederemos a publicar nuestra biblioteca en GitHub Packages, lo que nos permitirá incluirla fácilmente en otros proyectos.

🔐 Generar un token de acceso​

Para publicar paquetes en GitHub Packages, necesitamos un token de acceso personal con los permisos adecuados. Sigue estos pasos para generar un token de acceso:

  1. Ir a la configuración de tu cuenta: En GitHub, haz clic en tu avatar en la esquina superior derecha y selecciona "Settings" (Configuración).
  2. Acceder a los tokens de acceso: En la barra lateral izquierda, selecciona "Developer settings" (Configuración de desarrollador) y luego "Personal access tokens" (Tokens de acceso personal).
  3. Generar un nuevo token: Haz clic en "Tokens (classic)", luego en "Generate new token" (Generar nuevo token) y "Generate new token (classic)" (Generar nuevo token clásico).
  4. Configurar los permisos: Selecciona los permisos necesarios para publicar paquetes en GitHub Packages, como "write:packages" y "read:packages". Coloca un nombre descriptivo para el token y haz clic en "Generate token" (Generar token).
  5. Guardar el token: Copia el token generado y guárdalo en un lugar seguro, ya que no podrás verlo nuevamente.
Importante

¡No compartas tu token de acceso personal con otras personas! Este token te da acceso a tu cuenta de GitHub y a los recursos asociados.

Ahora, debemos tener acceso desde el script de construcción a este token y a nuestro nombre de usuario de GitHub. Para ello, podemos utilizar variables de entorno o un archivo de configuración externo. Utilizaremos un archivo de configuración para mantener la información segura y accesible desde el script de construcción.

🛠️ Crear un archivo de configuración​

Crea un archivo de configuración llamado github.properties en el directorio raíz de tu proyecto con la siguiente estructura:

github.properties
github.token=ghp_tu-token
github.username=tu-usuario

⚙️ Configurar Gradle para publicar en GitHub Packages​

Lo primero que haremos será crear un nuevo plugin de convenciones llamado publish.conventions.gradle.kts con el siguiente contenido:

publish.conventions.gradle.kts
plugins {
    `maven-publish`
}

Esto nos permitirá configurar las convenciones de publicación de Maven en nuestro proyecto. A continuación, definiremos una extensión llamada ArtifactExtension en el paquete extensions que contendrá la información necesaria para publicar nuestro artefacto en GitHub Packages.

convention-plugins/src/main/kotlin/extensions/ArtifactExtension.kt
package extensions

abstract class ArtifactExtension {

    abstract var artifactName: String

    abstract var artifactVersion: String
}

Luego, crearemos la extensión en publish.conventions.gradle.kts y lo utilizaremos en el build de nuestra biblioteca.

convention-plugins/src/main/kotlin/publish.conventions.gradle.kts
import extensions.ArtifactExtension

// ...

project.extensions.create<ArtifactExtension>("artifact")
convention-plugins/src/main/kotlin/publish.conventions.gradle.kts
// ...
val githubProperties = Properties().apply {
    load(rootProject.file("github.properties").reader())
}

val githubToken: String = githubProperties.getProperty("github.token")
val githubUser: String = githubProperties.getProperty("github.username")

afterEvaluate { }
¿Qué acabamos de hacer?

En este paso, cargamos las propiedades del archivo github.properties que contienen el token de acceso y el nombre de usuario de GitHub. Registraremos la tarea de publicación después de evaluar el proyecto, ya que necesitamos acceder a las extensiones y tareas que se definen durante la evaluación.

🚫 .gitignore​

Es MUY IMPORTANTE que agregues el archivo github.properties al .gitignore para evitar subir tus credenciales a GitHub. A continuación te proporcionamos un ejemplo de archivo .gitignore que puedes utilizar:

.gradle
build
.idea
**/build/
!src/**/build/
gradle-app.setting
!gradle-wrapper.jar
!gradle-wrapper.properties
.gradletasknamecache
.project
.classpath
*.class
*.log
*.ctxt
.mtj.tmp/
*.jar
*.war
*.nar
*.ear
*.zip
*.tar.gz
*.rar
hs_err_pid*
replay_pid*

github.properties
gitignore.io

Si necesitas un .gitignore personalizado, puedes utilizar gitignore.io para generar uno basado en tus necesidades específicas.

🚀 Publicar en GitHub Packages​

Con la configuración de Gradle lista para publicar en GitHub Packages, puedes ejecutar el siguiente comando para subir tu biblioteca:

./gradlew publish

Este comando generará los artefactos de la biblioteca y los enviará a GitHub Packages, haciéndolos accesibles para su uso en otros proyectos.

¡Y eso es todo! 🎉 Ahora has aprendido a publicar tu biblioteca en GitHub Packages, facilitando compartir tu código con otrxs desarrolladorxs de manera rápida y eficiente. 🤝✨

📥 Utilizar la biblioteca publicada​

Para utilizar la biblioteca que has publicado en GitHub Packages en otro proyecto, debes agregarla como una dependencia a tu proyecto.

Primero, agreguemos la biblioteca a nuestro catálogo de versiones:

libs.versions.toml
[versions]
# ...
echolib = "1.0.0" # Versión de la librería

[libraries]
# ...
echo = { module = "com.github.tu-usuario:echo-app-lib", version.ref = "echolib" }
# ...
warning

Ten en cuenta que si nombraras la versión como echo-lib en vez de echolib, habría un conflicto de nombres, ya que tanto echo como echo-lib tendrían el mismo prefijo. Esto haría que Gradle no pudiera diferenciar entre echo de libs.versions.echo y libs.versions.echo.lib. Otra solución sería renombrar echo a echo-app.

Luego, indicamos a Gradle que busque el paquete en GitHub Packages:

settings.gradle.kts
// ...
val githubProperties = Properties().apply {
    load(rootProject.file("github.properties").reader())
}

val githubToken: String = githubProperties.getProperty("github.token")
val githubUser: String = githubProperties.getProperty("github.username")

@Suppress("UnstableApiUsage")
dependencyResolutionManagement {
    repositories {
        mavenCentral()

        maven {
            url = uri("https://maven.pkg.github.com/tu-usuario/tu-repositorio")
            credentials {
                username = githubUser
                password = githubToken
            }
        }
    }
}

Finalmente, agregamos la dependencia en nuestro proyecto:

app/build.gradle.kts
// ...
dependencies {
    implementation(libs.echo)
}

¡Listo! Ahora solo sincroniza el proyecto, y la biblioteca estará disponible para su uso en tu aplicación.

❓ ¿Cuándo usar Releases vs. GitHub Packages?​

MétodoCuándo usarlo
GitHub ReleasesCuando necesitas compartir una versión específica de la biblioteca en un formato descargable, como un .jar o .zip. Ideal para distribuciones manuales y accesibles sin configuración adicional.
GitHub PackagesCuando necesitas gestionar dependencias de manera automática en proyectos que usan Maven o Gradle. Facilita la integración con otros proyectos y versiones futuras.

🎯 Conclusiones​

Publicar bibliotecas es un paso esencial en el desarrollo de software, ya que permite compartir código reutilizable con otrxs desarrolladorxs y proyectos. A lo largo de esta lección, hemos explorado dos formas de distribuir una biblioteca: GitHub Releases y GitHub Packages, cada una con sus propias ventajas y casos de uso.

Además, revisamos la importancia del versionado semántico (SemVer) para garantizar compatibilidad entre versiones y evitar interrupciones en el código de quienes consumen nuestra biblioteca.

🔑 Puntos clave​

  • Versionado Semántico: Usar SemVer (MAJOR.MINOR.PATCH) permite comunicar claramente cambios en la API de una biblioteca.
  • GitHub Releases: Útil para distribuir versiones descargables sin necesidad de gestionar dependencias.
  • GitHub Packages: Facilita la integración con Maven y Gradle, permitiendo incluir la biblioteca en otros proyectos sin necesidad de descargas manuales.
  • Automatización con Gradle: Configurar publish.conventions.gradle.kts simplifica la publicación de la biblioteca y mantiene la gestión de versiones organizada.
  • Gestión de credenciales: Usar github.properties evita exponer datos sensibles en el código fuente y mantiene la seguridad del acceso.

🧰 ¿Qué nos llevamos?​

Publicar bibliotecas no es solo compartir código, sino construir herramientas que otras personas puedan utilizar, mejorar y expandir. Al adoptar buenas prácticas en versionado, compatibilidad y distribución, facilitamos la integración y fomentamos un ecosistema más sólido y colaborativo.

Si queremos ofrecer una biblioteca fácil de descargar y usar sin configuración adicional, GitHub Releases es una gran opción. Pero si buscamos que nuestra biblioteca crezca y sea adoptada en múltiples proyectos de manera eficiente, GitHub Packages nos permite gestionar versiones de forma automatizada y mantener un flujo de trabajo profesional.

Dominar estos procesos no solo mejora la calidad de nuestro software, sino que también nos posiciona dentro de una comunidad de desarrolladorxs que crean, mantienen y colaboran en herramientas abiertas y reutilizables. Al compartir conocimientos y mejores prácticas, ayudamos a que más personas contribuyan y se beneficien del ecosistema que construimos juntxs. 🚀✨

📖 Referencias​

🔥 Recomendadas​