Fermer

février 10, 2020

Valider correctement les modifications apportées à votre base de code –


La différence entre un bon et un mauvais commit peut être énorme. Ce n'est pas amusant d'avoir à demander à votre collègue – ou à votre passé – en quoi consistait un changement particulier, ou quel est l'état actuel des choses.

Cet article vise à fournir un guide complet des meilleures pratiques de validation de logiciels. [

Si vous stockez déjà vos projets sur GitHub, vous pouvez supposer que les fichiers sont sûrs et que chaque fois que vous aurez besoin de mettre à jour le code, vous tirerez les modifications, et cela suffit. Tout cela pourrait être vrai. Mais voyons quels problèmes potentiels vous pouvez éviter en allant plus loin et quels avantages supplémentaires vous attendent si vous le faites.

No Man Is a Island, Soit en équipe ou individuellement

Le raisonnement ci-dessus vient généralement d'un développeur utilisé de travailler seul. Mais au moment où ils ont besoin de partager du code avec quelqu'un d'autre, nous pouvons nous attendre à ce que les choses se compliquent et nécessitent beaucoup d'explications. Comme, beaucoup .

N'oubliez pas que notre travail ne se limite pas à écrire du code. Nous devons également gérer les choses, ce qui nécessite un certain degré d'organisation et de méthodologie. Et tout en travaillant en équipe expose plus facilement les problèmes causés par une mauvaise organisation, nous pouvons également bénéficier d'une meilleure approche lorsque nous travaillons par nous-mêmes.

Atomic vs Bloated Commits

Nous avons tous eu besoin de revenir sur un petit changement et avons trouvé nous le recherchons dans un commit massif qui modifie des dizaines de fichiers et ajoute plusieurs fonctionnalités. Dans quelle mesure la restauration serait-elle plus facile si elle se trouvait dans un commit qui ne traitait que ce problème spécifique?

The Messy, Bloated Way

 git add *
git commit -m "nouveaux composants"

Dans cet exemple, nous pouvons parier qu'un grand nombre de fichiers sont affectés. De plus, le message "nouveaux composants" ne nous dit pas grand-chose, comme quels composants, quelles fonctionnalités pour ces composants et si la fonctionnalité est nouvelle ou refactorisée.

Ces informations seront-elles importantes lorsque nous aurons besoin de changer ou de récupérer quelque chose. Nous allons essayer de trouver une aiguille dans une botte de foin, et nous pourrions finir par regarder la base de code à la place et passer un temps précieux à déboguer pendant que nous y sommes.

The Atomic Way

 git add ui / login .html static / js / front-end.js
git commit -m "valider les champs de saisie pour la connexion"

Nous allons maintenant quelque part, alors que nous commençons à avoir une idée plus claire de ce qui se passe avec ce un seul commit.

L'astuce est que nous pouvons valider semi-automatiquement les modifications dans le cadre de notre flux de travail . Autrement dit, faire un bloc de travail qui fait quelque chose de très spécifique (implémenter une fonctionnalité particulière, corriger un bogue, optimiser un algorithme), tester (et écrire un test unitaire, si nécessaire), ajouter une description tout en nos souvenirs sont frais et engageants tout de suite. Rincer et répéter.

La structure d'un bon engagement

Ces règles ne sont pas gravées dans la pierre, mais peuvent vous aider à estimer à quoi pourrait ressembler un bon engagement:

  • sans ambiguïté : pas de seconde devinette sur ce que ces changements font.
  • perspicace : décrivant clairement ce que fait le code, fournissant même des liens ou des informations supplémentaires si nécessaire, et marquant les bogues ou les problèmes qui sont résolus.
  • atomic : adressant un une seule chose à l'époque (pensez à un "bloc de travail", qui pourrait être de 20 minutes à 2 heures, voire 2 minutes s'il s'agissait d'un correctif rapide).

Regardons un modèle et décomposons-le: [19659024]:


Type, composants ou sous-système

Il s'agit d'un ensemble de fonctionnalités d'un projet logiciel qui peuvent être regroupées. Par exemple, ce que AngularJS appelle des types ou ce que SrummVM appelle des sous-systèmes .

Exemples

Dans mes projets, j'utilise souvent le terme «composant», avec quelques exemples:

  • i18n, l18n
  • authentification
  • autre, tiers
  • AQ, teste
  • outils
  • UI, GUI

Le sujet (obligatoire)

Le sujet est simple, ligne simple qui décrit ce que fait la validation, afin que tout le monde puisse avoir une idée solide au premier coup d'œil.

En ce qui concerne la mise en forme du sujet, je suis souvent le suivant:

  1. utilisez l'impératif («changement») au lieu de «modifié»)
  2. ne met pas en majuscule la première lettre
  3. pas de point (.) à la fin
  4. ajoutez «(…)» si un corps facultatif est disponible

Exemples

Ces serait quelques sujets valides:

  • i18n: prise en charge du chinois simplifié (zh-hans)
  • auth: refactor Google Sign-In
  • ot her: add jQuery 3.4.1
  • QA: passer le test de déploiement AWS (…)

Comme vous pouvez le voir, il n'y a aucune supposition impliquée quant à ce que font ces commits, et lors du dernier commit QA, nous pouvons également voir qu'il y a plus d'informations disponibles (peut-être des liens vers la documentation pertinente ou des explications supplémentaires sur le correctif).

Le corps (facultatif)

Parfois, nous devrons fournir plus de détails que ne le permet une ligne d'objet pour fournir un contexte, tel comme lors de la correction d'un bogue persistant, ou lors du piratage d'un algorithme.

Dans ces cas, vous pouvez simplement entrer une double ligne de rupture (pour que le sujet fonctionne comme un titre) et entrer autant d'informations que nécessaire.

Exemple

Pour notre commit QA précédent, nous pourrions faire quelque chose comme ceci:

 QA: passer le test de déploiement AWS (...)

J'ai ajouté une variable d'environnement `DJANGO_SETTINGS_LIVE` à
[AWS Elastic Beanstalk] (https://aws.amazon.com/elasticbeanstalk/)
Fichier `django.config`, afin que les commandes de gestion de la synchronisation
dans `db-migrate` sont _seulement_ exécutés en production.

Comme vous pouvez le voir, le corps peut être plus difficile à suivre, et ça va, car il est destiné à ceux qui recherchent activement plus de détails. N'importe qui peut se faire une idée de ce que fait la validation simplement en lisant le sujet, et le corps servira de contexte supplémentaire, nous épargnant des échanges et des courriels sur Slack!

– «Hé, comment êtes-vous arrivé à … »

-« Lisez le commit ?. »

N'oubliez pas de résoudre les problèmes!

Enfin, il y a la question de résoudre les problèmes (jeu de mots!). Tout projet de développement de logiciel décent de moyenne à grande envergure devrait utiliser un outil de suivi des problèmes comme moyen de suivre les tâches, les améliorations et les bogues – que ce soit Atlassian Jira Bugzilla Suivi des problèmes de GitHub ou un autre.

Gestion des problèmes

Si vous ne le saviez pas, avec la plupart des systèmes, vous pouvez gérer les problèmes directement à partir de la validation message

Vous pouvez:

  • fermer / résoudre un problème
  • ré- ouvrir un problème s'il a été fermé avant
  • maintenir un problème, si une fonctionnalité devait être reportée pour une date ultérieure

Il suffit d'utiliser ces mots clés avec le numéro d'identification du problème.

Exemples

  • outils: consolider les données DB avec le travail cron; résoudre # 46
  • UI: ajouter une routine pour sérialiser l'entrée utilisateur; bogue trouvé, ouvrez # 32
  • auth: commentez la connexion Facebook; hold # 12

De plus, vous pouvez toujours référencer un problème comme moyen de fournir un contexte, même si vous ne voulez pas modifier son état – par exemple, "voir # 12".

Toutes ces références seront être visible par quiconque ouvre ce problème sur le tracker, ce qui permet de suivre facilement la progression d'une tâche ou d'un bug donné.

Envelopper

Vous ne réussirez pas toujours correctement (moi, pour ma part, don 't!). Les choses vont mal tourner et de temps en temps, vous ne suivrez pas les règles que vous avez définies pour vous-même ou votre équipe – et cela fait partie du processus. Mais j'espère que vous savez que vous pouvez être très organisé avec seulement quelques mises à niveau de votre flux de travail, vous épargnant ainsi que du temps à votre équipe sur le long terme.

J'ai également établi par expérience que peu importe si un projet implique dix développeurs ou si c'est entièrement géré par vous. Autrement dit, valider les modifications de votre base de code de la bonne façon est une partie cruciale d'une bonne gestion de projet .

Lectures complémentaires




Source link