Agile-compatible standard format for commit messages

When commiting changesets, I now write my messages using a special format that seems to me “Agile-compatible”. Each line of the message looks like the following: COD Description, where Description is a technical or (as in XOR) client-oriented description of the changeset (the user story summary, for example) and COD is one of:

  • NEW: a new feature or a new element of source code,
  • IMP: an improvement of one of the features of the projet or of the architecture/source code,
  • FIX: a fix of a bug,
  • REM: a removal of a feature or an element of the project (library, useless files…) -this is rarely used.

The Agile compatibility comes from the fact that if every commit must have a message and every message must follow the format, the commiter/developer can only do changes that can be labeled as a new feature, a fix, a feature removal or a (real) improvement. As an example, rewriting a function can only be a part of a changeset if it improves the project in some way: better performances, better readibility.

Some real world examples:

  • the creation of a project is a NEW Base libraries and build scripts,
  • the first feature is a NEW Authentication of a visitor of the website,
  • a fix of a feature is a FIX No error message when submitting an empty username in the authentication form,
  • a change of a feature related to a need is a IMP Moved the username and password fields on one line,
  • writing the documentation of a function is a IMP Documented the password encryption function,
  • etc.

Finally, using a label per change allows the commiter to have a better view on how to separate the commit in different changesets. Instead of commiting:

FIX PHP error when using a quote in the password field of the authentication form
IMP Getting the user info from the database only once when authentication

The developer can separate the changeset in two different commits (using partial commits or the shelve function of its SCM).

Gérer les redirections et erreurs des formulaires HTML

La création de formulaires HTML amène invariablement à une question d’architecture : comment gérer les  redirections et les messages d’erreur ou de succès qui peuvent avoir lieu lors de la validation de la saisie de l’utilisateur ?

La réponse que j’ai adoptée se base sur quelques règles de conception web simples, applicables à l’ensemble d’un site et qui permettent d’offrir à l’utilisateur un certain confort de navigation :

  • l’utilisateur doit être en mesure de se servir pleinement les fonctions de base de son navigateur (précédent, suivant, rafraîchir, mise dans les favoris…) ;
  • pour une URL donnée, le contenu doit rester identique ou très similaire ;
  • à l’inverse, un contenu identique ne doit pas se trouver sur plusieurs URL différentes.

Soit un formulaire en page /monformulaire.php et contenant plusieurs champs qui peuvent entraîner des erreurs de saisie par l’utilisateur (exemple : email incorrect, nombre trop grand, date invalide, etc.). En cas d’erreur de la saisie on souhaite afficher un message d’avertissement à l’utilisateur et réafficher le formulaire (avec éventuellement le champ erroné clairement indiqué, par exemple sur fond rouge pour faire dans l’originalité).

Suivant les principes énoncés plus haut, le formulaire devra toujours avoir comme URL /monformulaire.php : après soumission du formulaire l’utilisateur doit donc se trouver au final sur la page /monformulaire.php. L’idée est ici de donner comme URL de soumission du formulaire la même URL que l’affichage du formulaire : <form action="/monformulaire.php" ...

Les avantages de cette technique sont les suivants :

  • les erreurs éventuelles lors de la soumission n’ont pas besoin d’être transmises à d’autres pages comme c’est le cas en cas de redirections ;
  • l’utilisateur peut pleinement utiliser les fonctions précédent/suivant de son navigateur pour par exemple retrouver les valeurs des champs de formulaire ;
  • en cas de réactualisation de la page, le navigateur propose de reposter les champs du formulaire et l’utilisateur se retrouve donc sur la même page (et on reste donc dans le respect de la première règle énoncée, ouf !) ;
  • en cas de chargement direct de la page (par exemple si la page a été enregistrée dans les favoris) c’est bien le formulaire qui est chargé avec des valeurs vides, comme pouvait s’y attendre l’utilisateur ;
  • d’un point de vue plus technique, tout le code de gestion et d’affichage du formulaire se situe sur une même page.

Par conséquent, c’est seulement en cas de succès que l’utilisateur est redirigé, ce qui apparaît finalement plus logique du point de vue de la navigation : page précédente renvoie sur le formulaire valide, rafraîchir la page ne propose pas de reposter le formulaire…

Cercle ou carré ?

Cercle ou carré ?

La conception me fait penser à ces jeux pour enfants qui consistent à faire entrer des formes en bois dans les trous qui correspondent. Trouver une bonne solution architecturale est un peu comme trouver la bonne forme : d’abord on essaye le triangle qui dépasse fortement, puis l’étoile, beaucoup trop compliquée, et on arrive enfin à mettre la main sur le cercle et tout rentre parfaitement. En conception, quand on tombe sur la bonne solution tout devient clair et logique, tout s’assemble parfaitement. La mauvaise solution, le carré, c’est celle qui rentre seulement en forçant, en limant les coins et en laissant plein d’espaces vides, et qui reste bloquée dans le trou.

Alors, cette solution, cercle ou carré ?

au fin al