Comment améliorer votre bibliothèque Android

10 meilleures pratiques et astuces

Si vous développez une bibliothèque Android (open source ou non), il est judicieux de suivre certaines directives afin de garantir une haute qualité et de simplifier la vie de vos utilisateurs et collaborateurs. Voici quelques exemples des meilleures pratiques que j'ai recommandées et des conseils que vous pouvez suivre.

1. Préfixes de ressources

Si l'un de vos utilisateurs remplace une ressource Android de votre bibliothèque par erreur, cela peut être très dangereux. Par exemple, ils pourraient créer une ressource chaîne avec le même nom que celui défini dans votre bibliothèque.

Une façon d'éviter cela (ou au moins de réduire les risques de conflit de nom) consiste à attribuer un préfixe à toutes les ressources de votre bibliothèque.

Le préfixe pourrait être, par exemple, votre nom de bibliothèque ou votre nom de package. Vous devriez l'ajouter à tous les fichiers dans les répertoires suivants

  • res / drawable
  • res / mise en page
  • res / menu
  • res / xml
  • res / raw

De plus, ajoutez le préfixe au nom de ces types de ressources

  • chaîne
  • les pluriels
  • Couleur
  • dimen
  • déclarer-styleable
  • style
  • bool

Vous pouvez également déclarer le préfixe de votre bibliothèque sur votre build.gradle afin d’en informer Android Studio.

Android {
    resourcePrefix 'YOUR_PREFIX_'
}
La boîte de dialogue Android Studio Extract Resource complète automatiquement votre préfixe

2. Classificateurs de débogage et de libération

Si vous avez du code de débogage ou des utilitaires de développement sur votre bibliothèque, ne les incluez pas dans votre artefact de version (.aar). Vous pouvez utiliser des classificateurs pour générer deux artefacts différents de votre bibliothèque en fonction de vos types de construction:

  • l'artefact de débogage doit inclure tout votre code de bibliothèque productif, ainsi que tout code ou utilitaire de débogage à utiliser par vos utilisateurs lors du développement.
  • l'artefact de version ne doit inclure que le code de votre bibliothèque qui sera inclus sur l'APK de production.

Pour publier toutes vos variantes de bibliothèque, vous devez ajouter la configuration suivante au build.gradle de votre bibliothèque.

Android {
    publishNonDefault true
}

Puis allouez votre code sur les répertoires debug, main ou release selon vos besoins et lorsque vous téléchargerez votre bibliothèque, vous aurez deux artefacts.

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

Vous, utilisateurs de la bibliothèque, devez inclure vos dépendances en fonction de leurs besoins. Par exemple

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

3. Définir un schéma de version

Vos utilisateurs méritent de savoir quel type de modifications sont inclus dans une version avec un simple coup d'œil sur votre numéro de version.

Êtes-vous briser la compatibilité? Est-ce juste une version de correctif? Suivre les directives de versioning sémantique est une bonne idée pour le versioning de votre bibliothèque.

Avec un numéro de version MAJOR.MINOR.PATCH, incrémentez le:
Version majeure lorsque vous apportez des modifications incompatibles à l'API,
Version mineure lorsque vous ajoutez des fonctionnalités de manière rétro-compatible, et
Version PATCH lorsque vous apportez des corrections de bogues compatibles en amont.

Je vous suggère de choisir un schéma de gestion des versions et de le documenter sur votre wiki.

4. Notes de publication disponibles

Vos utilisateurs devront connaître tous les détails de chaque version que vous publiez, y compris les nouvelles fonctionnalités, les améliorations, les bogues résolus, le code obsolète et les étapes de la migration.

Un moyen de résoudre ce problème consiste à créer un journal des modifications.

Un journal des modifications est un fichier contenant une liste organisée, classée par ordre chronologique, de modifications importantes pour chaque version d'un projet.

Le site keepachangelog.com définit certaines conventions utiles concernant la rédaction de bons journaux de modification.

Si vous utilisez GitHub Issues en tant que suivi des problèmes, vous pouvez jeter un coup d'œil à ce générateur de journal des modifications qui automatise le processus de mise à jour permanente de ce fichier.

Je vous recommande également d'utiliser Github Releases et d'inclure votre journal des modifications dans la description de chaque version créée. Par exemple, vous pouvez consulter https://github.com/maxirosson/jdroid/releases

5. Publier sur les référentiels Maven Central / Jcenter

Si vous publiez tous les artefacts de votre bibliothèque dans les référentiels Maven Central ou Jcenter, vous simplifiez la configuration de vos utilisateurs. car ils n’auront pas besoin d’ajouter de référentiels personnalisés à leurs fichiers build.gradle.

Vous pouvez en savoir plus sur la publication sur Maven Central ici, mais sachez que vous devez être le propriétaire du domaine que vous avez choisi comme identifiant de groupe pour vos dépendances.

Les derniers conseils fonctionnent pour les bibliothèques open source ou privées. Voici quelques astuces supplémentaires qui fonctionnent exclusivement pour les bibliothèques open source.

6. LISEZ-MOI contributif

Si vous utilisez GitHub pour héberger le code de votre bibliothèque, vous pouvez inclure un fichier .github / CONTRIBUTING.md avec des directives de contribution. Ensuite, chaque contributeur qui ouvre une demande d'extraction ou crée un problème, il verra votre fichier de directives.

Les documents de contribution décrivent en détail la manière dont le responsable du projet souhaite voir les correctifs ou les fonctionnalités apportés. Cela peut inclure les tests à écrire, le style de syntaxe du code ou les zones sur lesquelles se concentrer pour les correctifs.

Vous pouvez voir un exemple ici et obtenir plus d'informations ici.

7. Convention Git Branching & Tags

Il est si important de définir et de rendre publique votre stratégie git branching & tags afin que vos collaborateurs puissent mieux savoir où travailler. Par exemple, il leur indiquera quelle branche est la version la plus stable de votre bibliothèque et où se trouve la dernière version de pointe de celle-ci.

8. Intégration publique continue

Avoir un outil d’intégration continue public permettra aux utilisateurs et aux contributeurs de votre bibliothèque de connaître la stabilité de vos succursales.

Travis est un excellent outil d’intégration continue gratuit pour les projets open source. Il est également intégré au mécanisme de demande de retrait de Github et vous pouvez inclure un badge Travis avec le statut de votre branche dans votre fichier README.

[! [Statut de la construction] (https://api.travis-ci.org/REPO_OWNER/REPO_NAME.svg?branch=master)] (https://travis-ci.org/REPO_OWNER/REPO_NAME)
Badge d'état de construction Travis

9. Traqueur de problème public

Un outil de suivi des problèmes publics permettant à vos utilisateurs et à vos collaborateurs de télécharger des bogues, des demandes de fonctionnalités ou des améliorations est une bonne idée pour promouvoir la collaboration.

Si vous utilisez GitHub en tant que référentiel git, GitHub Issues est un bon début. Si votre projet est grand ou plus complexe, vous aurez peut-être besoin d'un outil plus sophistiqué tel que Jira o Redmine.

10. Publier des sources

N’oubliez pas de publier votre code source sur votre référentiel de dépendances (par exemple, Maven Central ou Jcenter). Cette bonne pratique aidera l’EDI de votre utilisateur à charger automatiquement les sources. Ceci est très utile pour améliorer la compréhension des éléments internes de votre bibliothèque et également pour en encourager une utilisation appropriée.

L'ajout de ces lignes à votre build.gradle téléchargera automatiquement vos sources dans le cadre de la tâche de dégradé uploadArchives.

tâche ('androidSourcesJar', tapez: Jar) {
   classificateur = 'sources'
   à partir de android.sourceSets.main.java.sourceFiles, android.sourceSets.debug.java.sourceFiles
}

artefacts {
   archives project.tasks.androidSourcesJar
}

Avez-vous aimé cette histoire?
Veuillez recommander (en cliquant sur le bouton Clap) ou partager cette histoire afin que d'autres personnes puissent la lire! Vous pouvez également faire un don (en cliquant sur le bouton Donate suivant) et m'aider à continuer à écrire. Merci!

Je vous invite à jouer à Geo Seeker, mon tout nouveau jeu Android. https://geoseekergame.com