"Benoit Perrot" <benoit(a)lrde.epita.fr> writes:
>> De même, n'utilisez qu'une seule espace après « * » ; ceci
>>
>> * foo.hh: Blah blah.
>> * bar.cc: Other blah blah.
>>
>> est à proscrire.
>
> Je ne comprends pas. Qu'est-ce que l'on cherche a ecrire ici ?
> Comment faut-il ecrire ?
La même chose, mais avec une seule espace derrière l'étoile :
* foo.hh: Blah blah.
* bar.cc: Other blah blah.
>> 2. Ce n'est pas la peine de documenter les entrées que svn-wrapper
>> génère par pur zèle :
>
> Alors, une option `--no-pedantic' serait bienvenue ;)
Oui, mais je pense que personne n'a vraiment envie d'aller patcher
svn-wrapper.
>> 4. Les fichiers doivent toujours être prefixés d'une étoile
>
> (Heee mais euh ! C'est de la faute a emacs qui fait n'imp' avec Meta-Q
> en mode Change Log :) )
Oui, c'est vrai... Mais c'est mieux que rien.
>> 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.
>>
>
> (Discussion ouverte)
>
> Je pense parfois que ce n'est pas tout a fait ca non plus. Le destinataire
> de l'imperatif, c'est le fichier/la fonction modifie, non ?
>
> Si oui, alors, on ne devrait pas ecrire :
>
> * foo.cc: Create.
>
> ("foo.cc, Cree !")
> Mais plutot :
>
> * foo.cc: Provide foo-feature.
>
> ("foo.cc, Donne-moi la fonctionalite foo !")
>
> Dans la meme idee, on ne doit pas ecrire :
>
> * foo.cc: Fix bug.
>
> ("foo.cc, Corrige-moi ce bug !")
> Mais plutot :
>
> * foo.cc: Have the good behavior.
>
> ("foo.cc, Comporte-toi bien !")
>
> Euh... C'est vendredi aprem, la semaine a ete longue ...
Je ne sais pas. Le sujet, ce peut être le patch aussi.
Quelques critiques...
>>> "VO" == Vincent Ordy <ordy(a)lrde.epita.fr> writes:
[...]
VO> +# Check 80 columns.
VO> +if grep -q '^.\{80,\}' "$file"; then
VO> + warning 'Please avoid long lines in your ChangeLog entry (80 columns max):'
VO> + grep >&2 '^.\{80,\}' "$file"
VO> + error=true
VO> +fi
1) Une tabulation devrait compter pour 8 colonnes dans un ChangeLog
=> il faudrait utiliser "expand" avant grep.
2) Vaucanson contient des noms de fichiers de plus de 80 caractères.
Découper un nom de fichier pour le faire tenir sur 80 colonnes
ne me paraît pas souhaitable car ça empêche d'utiliser grep ensuite.
En fait c'est un cas où il me semble raisonnable de ne pas imposer
les 80 colonnes. Peut-être peux-tu ignorer les lignes qui
n'ont pas d'espace (de la forme "^\t[^ ]*$") avant de compter les
colonnes.
VO> +++ b/trunk/git-hooks/post-commit
[...]
VO> +## Add the log to the ChangeLog
VO> +mv "$changelog" "$changelog".old
VO> +git > "$changelog" \
VO> + log -n1 --date=short \
VO> + --pretty="format:%ad %an <%ae>%n%n %s%n%n%b%n"
VO> +cat >> "$changelog" "$changelog".old
VO> +rm "$changelog".old
VO> +
VO> +## Amend the last commit to add the ChangeLog
VO> +git add "$changelog"
VO> +tree_ref=$(git write-tree)
VO> +commit_ref=$(git log -n1 --pretty="format:%s%n%n%b%n" | \
VO> + git commit-tree $tree_ref -p 'HEAD^')
VO> +git update-ref HEAD $commit_ref
VO> +git gc --auto
Perso il est hors de question que j'utilise un truc pareil.
L'intérêt de git est justement que je peux faire plein de
commits intermédiaires : certains qui disparaîtront par la
suite, d'autres qui seront fusionnés et pour lesquels j'écrirai
le ChangeLog plus tard, ou bien des commits que je réordonnerai
avant de les rendre publiques. Je ne veux pas que mon ChangeLog
soit pollué systématiquement avec ma cuisine.
Par hasard est-ce que ce "truc" ne rajouterait pas une
entrée de ChangeLog si j'essaye de modifier une typo
dans le dernier message de commit avec "commit --amend" ?
Non, non, franchement pour éviter le travail de dupliquer
les messages des commits et du ChangeLog je vois d'autres
solutions :
- écrire le ChangeLog confortablement (p.ex. à l'aide
de "C-x 4 a" sous emacs) et avoir un script qui appelle
"git commit" en lui passant le texte de la dernière entrée.
Ça nous permet d'appeler "git commit" normalement pour
les commits moins formels.
- ne plus écrire de ChangeLog, mais les générer
automatiquement juste avant de faire une release (c'est
l'approche de GNU Coreutils et de Xorg); ça simplifie
les merges.
- ne plus écrire de ChangeLog et ne même plus les générer
(c'est l'approche de Linux).
Pour nous développeurs, les ChangeLogs ne nous servent plus à
grand chose à partir du moment où l'on a une copie du dépôt git
en local. Mais comme on ne distribue pas le dépôt git en même
temps que les sources dans une release, c'est un peu dur de
respecter les GPL sans trimbaler de ChangeLog (au moins pour les
parties du projets dont nous ne sommes pas propriétaires) :
« a) You must cause the modified files to carry prominent
notices stating that you changed the files and the date of
any change. »
--
Alexandre Duret-Lutz
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.
Serait-il possible de créer un dépôt Git vide pour `argp' ? Je voudrais
le peupler par la suite.
Ça me permettra de tester la conversion de svn:external vers des
sous-modules de Git.