Cómo mejorar tu biblioteca de Android

10 mejores prácticas y consejos

Si está desarrollando una biblioteca de Android (de código abierto o no), es una buena idea seguir algunas pautas para garantizar una alta calidad y también simplificar la vida de sus usuarios y colaboradores. Aquí hay algunos ejemplos de las mejores prácticas que recomendé y también consejos que puede seguir.

1. Prefijos de recursos

Si alguno de sus usuarios anula por error un recurso de Android de su biblioteca, puede ser muy peligroso. Por ejemplo, podrían crear un recurso de cadena con el mismo nombre que definió dentro de su biblioteca.

Una forma de evitar esto (o al menos reducir las posibilidades de un conflicto de nombres) es asignar un prefijo a todos los recursos de su biblioteca.

El prefijo podría ser, por ejemplo, el nombre de su biblioteca o el nombre del paquete. Debe agregarlo a todos los archivos dentro de los siguientes directorios

  • res / dibujable
  • res / layout
  • res / menu
  • res / xml
  • res / raw

Además anteponga el prefijo al nombre de estos tipos de recursos

  • cuerda
  • plurales
  • color
  • dimen
  • declarable
  • estilo
  • bool

También puede declarar el prefijo de su biblioteca en su build.gradle para que Android Studio lo sepa.

android {
    resourcePrefix 'YOUR_PREFIX_'
}
El cuadro de diálogo Recursos de extracción de Android Studio completa automáticamente su prefijo

2. Depurar y liberar clasificadores

Si tiene código de depuración o utilidades de desarrollo en su biblioteca, no los incluya en su artefacto de lanzamiento (.aar). Puede usar clasificadores para generar dos artefactos diferentes de su biblioteca de acuerdo con sus tipos de compilación:

  • el artefacto de depuración debe incluir todo el código productivo de su biblioteca, más cualquier código de depuración o utilidades que puedan usar sus usuarios durante el desarrollo.
  • el artefacto de lanzamiento solo debe incluir el código de su biblioteca que se incluirá en el APK de producción.

Para publicar todas las variantes de su biblioteca, debe agregar la siguiente configuración al build.gradle de su biblioteca

android {
    Publicar no predeterminado verdadero
}

Luego asigne su código en los directorios de depuración, principal o de lanzamiento de acuerdo con sus necesidades y cuando cargue su biblioteca tendrá dos artefactos

  • ARTIFACT_ID-VERSION-debug.aar
  • ARTIFACT_ID-VERSION-release.aar

Los usuarios de la biblioteca deben incluir sus dependencias según sus necesidades. Por ejemplo

debugCompile ('GROUP_ID: ARTIFACT_ID: VERSION: debug @ aar') {
    transitivo = verdadero;
}
releaseCompile ('GROUP_ID: ARTIFACT_ID: VERSION: release @ aar') {
    transitivo = verdadero;
}

3. Definir un esquema de versiones

Sus usuarios merecen saber qué tipo de cambios se incluyen en una versión con solo un vistazo rápido a su número de versión.

¿Estás rompiendo la compatibilidad? ¿Es solo una versión de parche? Seguir las pautas de versiones semánticas es una buena idea para las versiones de su biblioteca.

Dado un número de versión MAJOR.MINOR.PATCH, incremente el:
Versión PRINCIPAL cuando realiza cambios de API incompatibles,
Versión MENOR cuando agrega funcionalidad de una manera compatible con versiones anteriores, y
Versión PATCH cuando realiza correcciones de errores compatibles con versiones anteriores.

Le sugiero que elija un esquema de versiones y lo documente en su wiki.

4. Notas de lanzamiento disponibles al público

Sus usuarios necesitarán conocer todos los detalles de cada versión que publique, incluidas nuevas funciones, mejoras, errores resueltos, código obsoleto y pasos de migración.

Una forma de resolver esto es tener un registro de cambios.

Un registro de cambios es un archivo que contiene una lista curada y ordenada cronológicamente de cambios notables para cada versión de un proyecto.

El sitio keepachangelog.com define algunas convenciones útiles sobre cómo escribir buenos registros de cambios.

Si usa GitHub Issues como rastreador de problemas, puede echar un vistazo a este generador de registro de cambios que automatiza el proceso de mantener ese archivo siempre actualizado.

También le recomiendo que use las versiones de Github e incluya su registro de cambios como parte de la descripción de cada versión que cree. Por ejemplo, puedes echar un vistazo a https://github.com/maxirosson/jdroid/releases

5. Publicar en los repositorios Maven Central / Jcenter

Si publica todos los artefactos de su biblioteca en los repositorios de Maven Central o Jcenter, está simplificando la configuración de sus usuarios; porque no tendrán que agregar repositorios personalizados en sus archivos build.gradle.

Puede leer más sobre cómo publicar en Maven Central aquí, pero tenga en cuenta que debe ser el propietario del dominio que elija como ID de grupo para sus dependencias.

Los últimos consejos funcionan tanto para bibliotecas de código abierto como privadas. Aquí hay algunos consejos adicionales que funcionan exclusivamente para bibliotecas de código abierto.

6. Contribuyendo README

Si usa GitHub para alojar el código de su biblioteca, puede incluir un archivo .github / CONTRIBUTING.md con pautas de contribución. Luego, cada vez que un colaborador abra una solicitud de extracción o cree un problema, verá su archivo de pautas.

Los documentos contribuyentes detallan los detalles acerca de cómo el responsable de un proyecto quisiera ver parches o funciones contribuidas. Esto puede incluir qué pruebas escribir, estilo de sintaxis de código o áreas en las que centrarse para parches.

Puede ver un ejemplo aquí y obtener más información aquí.

7. Convención de ramificación y etiquetas de Git

Es tan importante que defina y haga pública su estrategia de ramificación y etiquetas de git, para que sus colaboradores puedan saber mejor dónde trabajar. Por ejemplo, les hará saber en qué rama está la versión más estable de su biblioteca y dónde está la última versión de vanguardia.

8. Integración pública continua

Tener una herramienta pública de integración continua les permitirá a los usuarios y colaboradores de su biblioteca conocer la estabilidad de sus sucursales.

Travis es una excelente herramienta de integración continua y es gratuita para proyectos de código abierto. También está integrado con el mecanismo de solicitud de extracción de Github y puede incluir una insignia de Travis con el estado de compilación de su rama en su archivo README

[! [Estado de compilación] (https://api.travis-ci.org/REPO_OWNER/REPO_NAME.svg?branch=master)] (https://travis-ci.org/REPO_OWNER/REPO_NAME)
Insignia de estado de construcción de Travis

9. Rastreador de problemas públicos

Un rastreador de problemas públicos que permita a sus usuarios y colaboradores cargar errores, solicitudes de características o mejoras es una buena idea para promover la colaboración.

Si usa GitHub como repositorio de git, GitHub Issues es un buen comienzo. Si su proyecto es grande o más complejo, tal vez necesite una herramienta más sofisticada como Jira o Redmine.

10. Publicar fuentes

No olvides publicar tu código fuente en el repositorio de dependencias (es decir, Maven Central o Jcenter). Esta buena práctica ayudará al IDE de su usuario a cargar automáticamente las fuentes. Esto es muy útil para aumentar la comprensión de los elementos internos de su biblioteca y también alentar un uso adecuado de la misma.

Agregar estas líneas a su build.gradle cargará automáticamente sus fuentes como parte de la tarea de carga de uploadArchives.

task ('androidSourcesJar', tipo: Jar) {
   clasificador = 'fuentes'
   de android.sourceSets.main.java.sourceFiles, android.sourceSets.debug.java.sourceFiles
}

artefactos {
   archivos project.tasks.androidSourcesJar
}

¿Te gustó esta historia?
¡Recomiende (haciendo clic en el botón de aplaudir ) o comparta esta historia para que otras personas puedan leerla! También puede donar (haciendo clic en el siguiente botón Donar) y ayudarme a seguir escribiendo. ¡Gracias!

Te invito a jugar Geo Seeker, mi nuevo juego de Android. https://geoseekergame.com