15 May
2009
15 May
'09
3:59 p.m.
Quelques rappels de style.
1. Je vois beaucoup d'entrées qui ressemblent à ça :
* foo.hh: Blah blah.
Other blah blah.
Par soucis d'uniformité, évitez les espaces supplémentaires après la
tabulation. Ça devrait ressembler à ça :
* foo.hh: Blah blah.
Other blah blah.
De même, n'utilisez qu'une seule espace après « * » ; ceci
* foo.hh: Blah blah.
* bar.cc: Other blah blah.
est à proscrire.
2. Ce n'est pas la peine de documenter les entrées que svn-wrapper
génère par pur zèle :
* .: Blah.
La présence de ce « . » n'est probablement due qu'à un changement de
propriété Subversion sur le répertoire à partir duquel vous avez lancé
svn. Or c'est typiquement le genre de choses qu'on ne documente pas
dans un ChangeLog (rappel : ChangeLog décrit les changements vis-à-vis
de la *distribution*, et pas du dépôt).
=> Il faut supprimer de telles lignes lorsque vous faites un commit.
De façon génèrale, svn-rapper n'est qu'un *outil* : les règles (celles
du Guide et des GNU Coding Standards) priment. Faites des entrèes
utiles, pas du remplissage.
3. Ne pas utiliser de caractère joker (wildcard) tels que « * » :
* foo/bar/*: Fix ctors.
Ça rend l'usage de grep difficile. Il faut détailler (je sais, c'est du
travail) :
* foo/bar/baz.cc,
* foo/bar/quux.cc:
* foo/bar/ix.cc:
Fix ctors.
4. Les fichiers doivent toujours être prefixés d'une étoile (vous pouvez
éventuellement les grouper sur une ligne si vous voulez). Ceci n'est
donc pas correct :
* inim/2010/rag/rag.cc, inim/2010/rag/center_weight.hh,
inim/2010/rag/dijkstra.hh, inim/2010/rag/p_vertices_with_accu.hh,
inim/2010/rag/rag.hh, inim/2010/rag/Makefile: New, INIM1 project
to detect lines from a picture with a Region Adjacency Graph.
Il aurait fallu écrire :
* inim/2010/rag/rag.cc, inim/2010/rag/center_weight.hh,
* inim/2010/rag/dijkstra.hh, inim/2010/rag/p_vertices_with_accu.hh,
* inim/2010/rag/rag.hh, inim/2010/rag/Makefile: New, INIM1 project
to detect lines from a picture with a Region Adjacency Graph.
Voire (mais c'est juste une question de goût) :
* inim/2010/rag/rag.cc,
* inim/2010/rag/center_weight.hh,
* inim/2010/rag/dijkstra.hh,
* inim/2010/rag/p_vertices_with_accu.hh,
* inim/2010/rag/rag.hh,
* inim/2010/rag/Makefile:
New, INIM1 project to detect lines from a picture with a Region
Adjacency Graph.
5. Les entrées s'écrivent à l'impératif (et non au prétérit). Une
entrée comme :
* foo.cc: Fixed 'float' bug on edges.
devrait s'écrire :
* foo.cc: Fix 'float' bug on edges.
6. Attention à tenir dans 80 colonnes!
7. Ce n'est pas une mauvaise idée de sauter des lignes dans un ChangeLog
pour marquer les différentes parties d'un patch, mais il ne faut pas en
abuser. S'il y en a trop, c'est probablement que vous êtes en train de
commettre trop de choses en même temps, qui mériteraient des patches
séparés. Si vous êtes utilisateur de Git, l'outil est là pour vous
aider.
Il faut éviter de faire des patches fourre-tout où vous corrigez
plusieurs problèmes d'un seul coup. Ça rend difficile la
lecture/relecture de vos contributions et la recherche d'infos.
Merci d'avance de respecter ces indications !
P.S. : Une bonne partie de ces règles figurent dans le guide, mais pas
toutes. Si une bonne âme trouve le temps de reformater ça et d'ajouter
ce qui manque au Guide du LRDE, je lui en serai reconnaissant.