Démarrage d'un nouveau projet à partir de zéro

J’ai découvert il y a un certain temps déjà la spécification des Conventional Commits. C’est une convention simple sur la façon d’écrire des messages de commit. C’est simple, mais c’est puissant. Cela nous permet de générer des journaux de modifications, des versions des numéros, etc. automatiquement.

Avec une convention définie, il est plus facile pour chacun dans l’équipe de comprendre ce qu’est un commit à propos. Cela facilite également la génération de notes de version.

Un message de commit typique ressemblerait à ceci :

Le type peut être l’un des suivants :

Dans le pied de page, j’ajouterais une référence au ticket JIRA (ou tout autre système de tickets) auquel le commit est lié.

En allant un peu plus loin, je pense que le type devrait également être le préfixe pour le nom de la branche. Suivi du numéro de ticket, et enfin quelques mots sur la fonctionnalité ou le problème. De cette façon, nous pouvons facilement voir de quoi il s’agit dans la branche.

J’adopterais le versionnement sémantique pour gérer les versions projet. C’est une convention simple qui nous permet de savoir quel type de changements se trouvent dans une version rien qu’en regardant le numéro de version.

Traduction de la définition depuis celle du site web semver :

En ce qui concerne la version, ce ne sont que des chiffres, nous ne devrions pas hésiter à les incrémenter, ils ne coûtent rien. Et nous ne devrions pas essayer de garder toutes les parties d’un projet synchronisées avec le numéro de version. Il est acceptable d’avoir une version 1.0.0 d’une bibliothèque et une version 2.0.0 de l’application qui l’utilise.

Mais, lorsque nous déployons, nous devons garder une trace des versions des différentes parties du projet. Cela nous permet de voir facilement ce qui est déployé où.

Nous devons intégrer l’internationalisation (i18n) dès le début du projet. Nous ne pouvons pas simplement écrire les chaines de caractères pour les boutons, menus, descriptions, etc. Nous utiliserons une bibliothèque appropriée pour les frameworks retenus (frontend et backend).

C’est beaucoup plus facile à mettre en place dès le départ que de tenter de réintégrer le tout une fois le projet démarré.

Aussi, si nous enregistrons de l’information dans le backend, comme des configurations, nous devrions retourner toutes les langues comme réponses aux interrogations, et laisser le frontend décider de ce qu’il affiche. C’est particulièrement vrai quand on crée des apis.

La plupart des projets vont devoir gérer des dates à un moment ou un autre. Nous adopterons le format de date ISO8601 pour toutes les communications dès le début.

De plus, les dates, c’est difficile. Il suffit de demander à Google ou de jeter un oeil à Falsehoods programmers believe about time. Nous utiliserons donc des bibliothèques reconnues pour manipuler les données temporelles.

Ça va nous sauver du temps à long terme.

La sécurité doit être une priorité dès le début. Nous devons l’avoir à l’esprit dès le début du projet. Nous devrions prendre le temps de réfléchir aux permissions et aux groupes, de déterminer quels points d’accès doivent être sécurisés, quels demandent des authorisations particulières et quels doivent être public.

Nous devrions aussi utiliser les fonctionnalités de sécurité des frameworks retenus, pas seulement pour l’accès, mais aussi pour éviter l’injection SQL, la reprise de session, etc. OWASP Top Ten est un bon point de départ.

J’ai récemment été introduit au concept de Diataxis (https://dev.to/onepoint/documentation-chaotique-diataxis-a-la-rescousse—​3e9o).

C’est une façon de catégoriser et d’organiser la documentation d’un projet.

On peut le voir comme une matrice avec deux axes : le contenu et la forme.

Je n’ai pas encore utilisé cette méthode, mais je pense que c’est une bonne idée pour organiser la documentation.

Il existe de nombreuses façons et formats pour documenter notre futur projet. Très souvent, nous verrons markdown comme format. Malheureusement, markdown est plus limité, et il existe une variété de saveurs en compétition pour markdown. Par exemple, il est difficile de numéroter les titres dans markdown, il faut le faire à la main, et s’assurer de faire suivre la numérotation quand on déplace des sections.

AsciiDoc est un format plus puissant qui peut être utilisé pour rédiger de la documentation. Il permet de faire plus de choses que markdown. Il est relativement facile à lire dans sa forme brute.

Donc, nous devrions utiliser Asciidoc comme format. Il peut être utilisé pour générer de la documentation dans de nombreux formats, comme html, pdf, etc. La documentation peut être pour différentes sorties, comme un livre, un article, etc.

Si nous devons un jour le convertir à nouveau en markdown, nous pouvons utiliser la commande suivante :

Antora est défini comme le générateur de site de documentation mono ou multi dépôt pour les rédacteurs techniques qui aiment rédiger en Asciidoc.

Antora permet de rédiger de la documentation en asciidoc dans plusieurs dépôts de codes (penser frontend, multiples modules backend) et de créer un dépôt pour centraliser toute la documentation de vos dépôts et de publier un site statique pour votre organisation.

C’est une façon très intéressante de faire en sorte d’avoir un point de départ pour toute la documentation du projet tout en la maintenant à jour.

Dès le début d’un projet, nous prenons des décisions d’architectures. Cet article en suggère plusieurs. Avec le temps qui passe, les personnes peuvent changer de projet et la mémoire de ces décisions et des raisons qui les ont appuyées peuvent se perdre.

Les ADR sont une façon d’enregistrer ces décisions et de les garder au même endroit.

Quelques projets existent pour faciliter la création d’ADR, mais la plupart utilisent du markdown comme format. Je suis encore à la recherche d’un bon projet qui supporte le asciidoc. Pour l’instant, adr-j semble un bon candidat qui supporte à la fois le markdown et le asciidoc.

Se prétendant être le framework le plus rapide pour construire un site statique, Hugo est un framework qui prend un ensemble de documents rédigés en markdown ou asciidoc et les convertis en site statique avec la possibilité d’appliquer des thèmes et d’autres fonctionnalités intéressantes comme les mots clés.

J’ai commencé à l’utiliser pour générer mon blog personnel. Pour l’instant, je suis satisfait.

J’utilise IntelliJ IDEA de JetBrains depuis décembre 2012 et je l’apprécie beaucoup.

Mais en fait, chaque personne devrait utiliser n’importe quel IDE qu’elle aime, à une condition : Ils devraient le maîtriser. Ils devraient savoir comment l’utiliser à son plein potentiel.

Si nous avons une personne junior dans notre équipe, assurons-nous qu’elle prenne le temps d’apprendre son IDE.

Dans de nombreux projets, nous aurons besoin de certains services auxiliaires. J’utiliserais docker-compose pour définir ces services auxiliaires et les rassembler. Et envelopper les actions (démarrage, arrêt, réinitalisation de la base de données, etc.) dans un script shell qui offre une aide et des valeurs par défaut raisonnables.

De cette façon, nous pouvons démarrer les services auxiliaires avec une seule commande. Nous pouvons également arrêter les services avec une seule commande. Nous pouvons aussi redémarrer les services auxiliaires avec une seule commande.

Dans nos projets, le script d’aide comprend des profils. Ainsi, un développeur front-end commencerait par l’aide des services comme la base de données et le backend, tandis qu’un développeur backend commencerait par la base de données et le front-end. Et un QA commencerait tout.

Nous pouvons également ajouter tout autre service d’assistance qui peut être dockerisé.

Et bien sûr, tous les projets, modules ou microservices qui font partie du projet.

La simple réalité est qu’il faut choisir un format pour le code, n’importe lequel et de s’y tenir. Mais, d’après mon expérience, j’ajouterais d’autres critères pour le sélectionner :

Dès qu’il y a (ou pourrait y avoir) plus d’une personne travaillant sur un projet, nous aurons besoin d’un moyen pour gérer notre travail, notez les tâches à accomplir, leur état d’avancement, etc. Nous devrions utiliser le système de tickets qui est déjà en place dans l’organisation où le projet a commencé. S’il n’y en a pas, de nombreuses options sont disponibles.

Lorsque nous construisons une API, nous devrons renvoyer des messages d’erreur. Il est préférable de prédéfinir le format des messages d’erreur et être cohérents dans toutes les APIs que nous exposons, même si elles sont exposées seulement en interne.

J’utiliserais le Problem Details for HTTP APIs (RFC 9457) pour renvoyer des messages d’erreur. C’est une simple convention qui peut être utilisée pour renvoyer des messages d’erreur. Elle peut être utilisée pour renvoyer des messages d’erreur dans de nombreux formats, comme json, xml, etc. Elle peut être utilisée pour renvoyer des messages d’erreur dans de nombreux langages, comme java, javascript, etc.

Une caractéristique à noter est que nous pouvons faire en sorte que l’erreur dans les journaux ait un UUID unique qui est également renvoyé au client. De cette façon, nous pouvons tracer l’erreur dans les journaux et dans le client.

Voici un article plus long par A java geek qui explique https://blog.frankel.ch/problem-details-http-apis/

Il existe une implémentation prête pour Quarkus : https://github.com/quarkiverse/quarkus-resteasy-problem

La communication est essentielle dans un projet. Que ce soit pour une question rapide, pour partager un extrait de code, pour demander de l’aide, etc. Nous avons besoin d’un système de chat.

Ici encore, j’utiliserais le système de chat qui est déjà en place dans l’organisation où le projet est lancé. S’il n’y en a pas, de nombreuses options comme MS Teams, Slack, etc. sont disponibles.

S’assurer que nous créons des canaux dédiés pour différents aspects (code, révision, déploiements/devops, communication ludique) du projet. De cette façon, nous pouvons garder la conversation ciblée sur le bon sujet.

J’identifierais dans la base de code des exemples de bon code. De cette façon, lorsqu’un nouveau développeur rejoint l’équipe, il peut voir ce qui est considéré comme un bon code. Cela peut être une classe simple, une méthode, un modèle, etc.

Adopter dès le début la pratique de rédiger des tests pour chaque fonctionnalité développée. Premièrement des tests unitaires pour tester le code et les cas limites, et ensuite, des tests d’intégration pour tester les interactions entre les différentes parties du système là où c’est nécessaires.

Éviter de tester les bibliothèques de code utilisées.

Les tests doivent être exécutés automatiquement à chaque fois que le code est modifié et avant qu’il ne soit fusionné.

L’analyse statique du code est une bonne pratique pour attraper des bugs avant qu’ils n’arrivent.

Votre IDE est la première ligne de défense, gardons un oeil sur les avertissements qu’il prodigue.

Idéalement, nous devrions relier notre IDE à un outil plus robuste, comme Sonarqube afin qu’il vérifie le code avec la même configuration que ce que le pipeline fera. Ça doit être fait pendant que l’on code, ou, minimalement avant de commettre le code.

Une autre façon d’augmenter la qualité du code, c’est de le réviser. Ça permet d’attraper les bugs, mais aussi de partager la connaissance sur le code, les pratiques et le projet. Ça permet aussi d’avoir une base de code cohérente et facilement lisible pour l’ensemble de l’équipe et des futurs développeurs.

Même si l’équipe est petite, c’est une bonne pratique que de faire de la revue de code. Il devrait y avoir une étape dans le pipeline qui bloque le merge si le code n’a pas été révisé.

Nous devrions avoir un pipeline de construction qui roule les tests, l’analyse statique et s’assure que le code a été révisé. Il pourra attraper les erreurs qui n’arrivent pas sur notre propre poste et aider à faire un build plus robuste.

J’utiliserais Quarkus comme framework pour construire le backend du projet. C’est un framework Java moderne qui est assez mature. On dirait qu’il a été construit dès le départ avec le développeur en tête. Et il peut créer des artefacts qui sont natifs, rapides et adaptés aux conteneurs.

Il existe un excellent tutoriel pour nous donner un aperçu du framework et des fonctionnalités associées. https://quarkus.io/quarkus-workshops/super-heroes/

Très souvent, lors de la construction d’un backend robuste, nous aurons besoin de différents modèles (DTO, pojo, entités) pour différentes parties de l’application.

À mesure que l’information passe d’une partie de l’application à une autre (de la base de données au service, du service au contrôleur, du contrôleur au client), nous devrons mapper les informations d’un modèle à un autre.

J’utiliserais Mapstruct. C’est un produit puissant qui peut être utilisé pour mapper des objets d’un type à un autre. Le mapping se fait à la compilation, donc c’est rapide.

C’est assez utile quand nous devons mapper d’un DTO à une entité et vice versa. Il peut faire correspondre les propriétés par nom, ou nous pouvons définir le mapping nous-mêmes. Nous pouvons également facilement définir des transformations personnalisées au besoin.

L’une des plaintes que les gens ont sur Java est de devoir écrire beaucoup de code répétitif.

J’utiliserais Lombok pour alléger cela. C’est un produit puissant qui peut être utilisé pour générer le code répétitif pour nous. Il peut être utilisé pour générer le code de base pour nous de plusieurs manières, comme les accesseurs, les mutateurs, les constructeurs, y compris certains modèles comme les constructeurs, equals et hashcode, etc.

Pour certaines constructions, utiliser les Records de java pourrait être une bonne alternative.

À un certain moment, nous aurons probablement besoin d’une base de données relationnelle pour stocker nos données (voir Postgresql plus tard à ce sujet). Et ensuite, nous aurons besoin d’un moyen de gérer le schéma de cette base de données. J’utiliserais Liquibase pour cela.

C’est un produit mature qui peut être utilisé pour gérer le schéma de la base de données. Il peut être utilisé pour créer le schéma, mettre à jour le schéma, etc. Il peut également être utilisé pour créer des données dans la base de données.

Il prend également en charge le concept de contextes. Ainsi, nous pouvons stocker dans le même système différents ensembles de modifications pour différents environnements (comme des données pour les QAs), besoins ou fonctionnalités. C’est une fonctionnalité puissante.

Il y a même un certain support pour certaines bases de données non relationnelles/sql, comme MongoDB, Noe4j, Databricks Data Lakehouses, etc.

Surveiller notre application est souvent une tâche qui est repoussée à plus tard, après que les fonctionnalités soient mises en oeuvre. Mais il est important de commencer à y penser tôt.

J’utiliserais OpenTelemetry pour surveiller l’application. C’est un projet framework implémenté par plusieurs bibliothèques de code. Il peut être utilisé pour surveiller l’application en production, mais aussi en développement. Il peut être utilisé pour surveiller l’application dans un conteneur, mais aussi dans un environnement natif.

Et nous pouvons également ajouter nos propres métriques. Disons que nous voulons surveiller le nombre de fois qu’une fonctionnalité spécifique est utilisée. Nous pouvons ajouter une métrique pour cela. Ou si nous voulons nous assurer qu’un job cron est complété correctement au taux attendu, nous pouvons ajouter une métrique pour cela.

Un exemple de la documentation quarkus :

Que diriez-vous si je vous disais "vous pouvez tout mettre dans des commutateurs de fonctionnalité" ?

Dès que le coeur de notre application existe, nous devrions envisager d’encapsuler chaque fonctionnalité supplémentaire dans un commutateur de fonctionnalité.

Il y a deux raisons principales à cela :

Nous pouvons également utiliser des commutateurs de fonctionnalité pour désactiver une fonctionnalité si elle ne fonctionne pas comme prévu.

Si notre projet nécessite une base de données relationnelle, j’utiliserais Postgresql. C’est un produit mature qui peut être utilisé pour stocker les données du projet. C’est un produit puissant qui a de nombreuses fonctionnalités comme les transactions, les contraintes, les déclencheurs, etc. Il a de nombreuses capacités intégrées, comme le stockage d’objets en json format, la recherche en texte intégral, etc. Il a également de nombreuses extensions, comme Postgis, qui peuvent être utilisés pour stocker et interroger des données géospatiales, Timescale, qui peut être utilisé pour stocker et interroger des données de séries temporelles, etc. Il est très stable et a une grande communauté.

À un moment donné, nous devrons gérer les utilisateurs et leur accès à l’application. J’utiliserais Keycloak pour cela. C’est un produit mature qui peut être utilisé pour gérer les utilisateurs, les rôles, les permissions, etc. Nous pouvons également le configurer pour déférer l’authentification à un système externe en utilisant des fournisseurs d’identité. Il existe même un moyen de migrer nos utilisateurs d’un système externe vers Keycloak.

Il est tout à fait possible que notre projet doive interagir avec des services externes. Nous voudrons tester notre code sans avoir à dépendre de l’appel réel à ces services externes. Nous pouvons utiliser la documentation du service pour obtenir le format du payload attendu.

J’utiliserais Wiremock pour remplacer ces services pendant le développement. C’est un produit mature qui peut simuler les services externes. Nous pouvons définir les réponses que nous voulons obtenir des services externes et utiliser Wiremock pour simuler les services externes.

Il prend même en charge la randomisation du résultat ou le retour de timestamps qui sont toujours une période définie dans le passé ou le futur de l’appel.

Nous avons des mots de passe, beaucoup trop probablement. Et nous ne devrions pas les stocker en texte clair. J’utiliserais un gestionnaire de mots de passe pour stocker les mots de passe. Il existe de nombreux gestionnaires de mots de passe disponibles, comme 1Password, LastPass, Bitwarden, etc.

Certains, comme 1Password, sont plus qu’un simple coffre-fort de mots de passe, ils viennent avec des outils qui nous permettent d’utiliser en toute sécurité les mots de passe dans nos applications ou sur la ligne de commande.

Puisque nous parlons finalement d’écrire du code en équipe, nous avons besoin d’un moyen de gérer notre code. Je choisirais Git comme système de contrôle de version. Ensuite, nous aurions besoin d’un endroit pour stocker ce code. Les suspects habituels sont Github, Gitlab, Bitbucket, etc.

Je serais pragmatique et choisirais ce qui est déjà utilisé dans l’organisation où le projet est commencé. Tant que nous pouvons également avoir des pipelines pour vérifier, construire et empaqueter le code, ça me va.

À un moment donné, c’est sûr, nous devrons gérer des secrets dans notre dépôt. Nous utiliserons Sops pour chiffrer ces secrets. De cette façon, nous pouvons les stocker dans le dépôt git sans craindre qu’ils ne soient lu par des personnes qui ne devraient pas y avoir accès.

Assurez-vous que nous mettons cette pratique en place tôt dans le processus, afin qu’aucun secret ne soit jamais stocké en texte clair dans notre dépôt. (Voir l’article que j’ai rédigé à ce sujet)

Certaines organisations utilisent Gitlab, d’autres utilisent Github, Bitbucket ou même AWS CodeCommit. Peu importe ce que votre organisation utilise, assurez-vous que votre organisation dispose d’un système pipeline capable de :

Comme nous utilisons Gitlab, nous utiliserons les pipelines qui peuvent s’exécuter dans gitlab. C’est un outil puissant qui peut être utilisé pour vérifier, construire et empaqueter le code. Il peut également être utilisé pour déployer, surveiller la qualité du code. Il peut être utilisé pour revenir en arrière sur le code si un problème était découvert.

Voici quelques étapes typiques que nous mettons dans nos pipelines :

Traduction libre du site web de danger :

Nous devrions utiliser Danger pour valider et imposer les normes de notre équipe.

Nous voudrons vérifier la qualité de notre code. L’analyse statique de notre code permet de détecter de nombreux problèmes comme des mauvaises habitudes de programmation, des bugs ou des problèmes de sécurité.

J’utiliserais Sonarqube pour cela. C’est un produit mature qui peut vérifier notre code pour des bugs, vulnérabilités, mauvaises pratiques de code, etc. Il peut également vérifier notre code pour la couverture, les duplications, etc.

La plupart des IDE devraient avoir un plugin afin que nous puissions voir les résultats de l’analyse directement dans notre IDE ou avant de valider.

Il est raisonnable de prévoir le déploiement de notre application dans des conteneurs. D’autant plus si notre application n’est pas un gros monolithe, mais un ensemble de modules ou de microservices. Pensez à un frontend en React, un backend en Quarkus, une base de données en Postgresql, etc.

Nous pouvons utiliser Docker pour créer les images de notre application. Nous pouvons également utiliser Docker pour exécuter les conteneurs de notre application. Et, si le besoin se présente, nous pouvons utiliser Kubernetes pour déployer l’ensemble de notre pile d’application.

Donc, tôt dans le projet, assurons-nous que nous avons un pipeline qui peut construire les images de notre application. Nous devons prendre en considération les étapes pour construire les images, et quelles sont les configurations que nous voudrons passer à ces images. Et testons autant le pipeline que les images résultantes.

Idéalement, nous devrions avoir un pipeline qui construit les images et les pousse vers un dépôt de conteneurs. Cela nous permet d’utiliser la même image dans tous nos environnements.

Je pense que faire une image différente pour chaque environnement est une mauvaise idée. Nous devrions être capables de déployer la même image dans tous nos environnements. La seule différence devrait être la configuration.

Nous nous épargnerons beaucoup de stress si nous commençons tôt avec cela au lieu d’attendre de le faire quand nous sommes près du Test d’Acceptation Utilisateur ou pire, de la date de Production.

Nous allons déployer notre application dans une infrastructure, qu’elle soit chez un fournisseur cloud, ou déployée sur l’infra de l’organisation. Et nous aurons très probablement besoin de la même infrastructure dans différents environnements, comme le développement, la qa, la pré-production, l’uat, la production. Le meilleur moyen de s’assurer que chaque environnement est aussi proche que possible du précédent est de le rendre reproductible. J’utiliserais Terraform pour définir l’infrastructure en tant que code. De cette façon, nous pouvons déployer la même infrastructure dans chaque environnement.

Un autre avantage de Terraform est qu’il nous permet de synchroniser des parties de l’infrastructure qui sont définies chez différents fournisseurs cloud. Prenons pour exemple que nous utilisons Github comme dépôt de code, Amazon Pipelines pour nos pipelines de construction et que nous voulons aussi configurer Keycloak et Grafana. Nous pouvons définir tout cela dans Terraform et le déployer en une seule commande.

Ce qui est, je pense, plus simple que d’utiliser la configuration propre à chaque fournisseur et de tenter de créer une orcherstration par dessus.

Terragrunt est un wrapper mince pour Terraform qui fournit des outils supplémentaires pour garder vos configurations DRY, travailler avec plusieurs modules Terraform, et gérer l’état distant.

Gérer une grande infrastructure avec Terraform est un peu douloureux. Nous avons probablement un gros fichier d’état sur le bucket AWS S3, plusieurs modules et plusieurs environnements. Terragrunt peut nous aider à gérer tout cela.

Je considère cela comme un sous-ensemble de la surveillance. Nous voudrons savoir si, quand et d’où nos utilisateurs utilisent notre application.

J’utiliserais Plausible pour cela. C’est un produit simple qui peut être utilisé pour surveiller notre application. Il peut être utilisé pour surveiller notre application en production, mais aussi en développement, dans un conteneur ou dans un environnement natif.