+@c ------------------------------------------------------------ + +@node Reviewing Patches +@section Reviewing Patches + +Once the commitment message posted (@pxref{Checking in a Revision}), it +must be reviewed: @emph{every single patch should be reviewed}. + +The purpose of the review is of course to look for errors, typos, +unclear documentation or ChangeLog, incorrect coding style, or even +better implementation suggestion and so forth. + +If there is nothing to report about the patch, just reply ``Ok'', +quoting only the ChangeLog. Usually the thread ends there. + +If there are issues to report, quote only relevant portions of the +patch. If you have several big issues to report, you might want to make +separate replies to split the thread. The author of the patch must +answer to these comments, and if subsequent commits address some of +these issues, the reply should refer to them (e.g., by giving the +revision number). + +Anybody is welcome to comment a patch, nevertheless, this responsibility +typically falls upon the shoulders of the project maintainer, or the +code-review peer of the author of the patch. ---------------------------------------------------------------------- Index: ChangeLog from Akim Demaille <akim@epita.fr> * Makefile.am (.texi.txt, MAKEINFOTEXT, AM_MAKEINFOTEXTFLAGS): New. * maintain.texi (Maintaining ChangeLog): Now section of... (Maintaining Projects): this new chapter. (Checking in a Revision, Reviewing Patches): New. Index: Makefile.am --- Makefile.am Wed, 21 Apr 2004 11:37:53 +0200 akim (lrde-maintain/5_Makefile.a 1.1 644) +++ Makefile.am Thu, 29 Apr 2004 14:35:59 +0200 akim (lrde-maintain/5_Makefile.a 1.1 644) @@ -26,10 +26,43 @@ --fill-column=76 \ --no-split +# Work around makeinfo's lack of I18n support. +MAKEINFO = LC_ALL=C @MAKEINFO@ + + +## ----------------- ## +## Texinfo -> Text. ## +## ----------------- ## + TXTS = maintain.txt CLEANFILES = *.txt +MAKEINFOTEXT = $(MAKEINFO) --plaintext +AM_MAKEINFOTEXTFLAGS = $(AM_MAKEINFOFLAGS) + +# Shamelessly stolen from Automake's .texi.info +.texi.txt: + restore=: && \ + backup="$(am__leading_dot)am$$$$" && \ + if test -f $@; then \ + mv $@ $$backup; \ + restore=mv; \ + fi; \ + if $(MAKEINFOTEXT) $(AM_MAKEINFOTEXTFLAGS) $(MAKEINFOTEXTFLAGS) -I $(srcdir) \ + -o $@ $<; \ + then \ + rc=0; \ + cd $(srcdir); \ + else \ + rc=$$?; \ + cd $(srcdir) && \ + $$restore $$backup `echo "./$@" | sed 's|[^/]*$$||'`; \ + fi; \ + rm -f $$backup; \ + exit $$rc + + ## ---------------- ## ## Building diffs. ## @@ -42,7 +75,7 @@ -I '(line' diff diffs: diffs.patch -diffs.patch: assignments.txt tiger.txt +diffs.patch: maintain.txt -diff -u -w $(IGNORES) --from=$(DESTDIR)$(wwwdir) $(TXTS) >$@ cat $@ Index: maintain.texi --- maintain.texi Wed, 21 Apr 2004 12:20:31 +0200 akim (lrde-maintain/6_maintain.t 1.2 644) +++ maintain.texi Thu, 29 Apr 2004 14:20:10 +0200 akim (lrde-maintain/6_maintain.t 1.2 644) @@ -4,7 +4,7 @@ @settitle Maintaining LRDE Projects @c This date is auto-magically updated when you save this file: -@set lastupdate April 21, 2004 +@set lastupdate April 29, 2004 @set gccversion 3.2 @c $Format: "@set version $ProjectVersion$"$ @@ -61,13 +61,19 @@ @contents @menu -* Introduction:: -* Maintaining ChangeLog:: -* Appendices:: +* Introduction:: About this document +* Maintaining Projects:: Coding styles, guidelines etc. +* Appendices:: Copying this document, Indices @detailmenu --- The Detailed Node Listing --- +Maintaining Projects + +* Maintaining ChangeLog:: Recording the history of changes +* Checking in a Revision:: Recording a revision of a project +* Reviewing Patches:: Controlling the quality of patches + Maintaining @file{ChangeLog} * What and How:: What are ChangeLogs @@ -88,11 +94,21 @@ @node Introduction @chapter Introduction - @c ====================================================================== +@node Maintaining Projects +@chapter Maintaining Projects + +@menu +* Maintaining ChangeLog:: Recording the history of changes +* Checking in a Revision:: Recording a revision of a project +* Reviewing Patches:: Controlling the quality of patches +@end menu + +@c ------------------------------------------------------------ + @node Maintaining ChangeLog -@chapter Maintaining @file{ChangeLog} +@section Maintaining @file{ChangeLog} This page contains a summary of the most important things to know about the Change Log entries. The main source of information remains the @@ -107,7 +123,7 @@ @end menu @node What and How -@section What and How +@subsection What and How Document @emph{any} change you have made. This will make bug hunting easier, and this will help other people to follow the development. @@ -124,7 +140,7 @@ @end example @node ChangeLog Do -@section ChangeLog Do +@subsection ChangeLog Do @itemize @minus @item @@ -155,7 +171,7 @@ @node ChangeLog Don't -@section ChangeLog Don't +@subsection ChangeLog Don't @itemize @minus @item @@ -185,7 +201,7 @@ @end itemize @node Emacs and ChangeLog -@section Emacs and ChangeLog +@subsection Emacs and ChangeLog @itemize @minus @item @@ -203,6 +219,40 @@ @key{RET}}. @end itemize +@c ------------------------------------------------------------ + +@node Checking in a Revision +@section Checking in a Revision + +@c ------------------------------------------------------------ + +@node Reviewing Patches +@section Reviewing Patches + +Once the commitment message posted (@pxref{Checking in a Revision}), it +must be reviewed: @emph{every single patch should be reviewed}. + +The purpose of the review is of course to look for errors, typos, +unclear documentation or ChangeLog, incorrect coding style, or even +better implementation suggestion and so forth. + +If there is nothing to report about the patch, just reply ``Ok'', +quoting only the ChangeLog. Usually the thread ends there. + +If there are issues to report, quote only relevant portions of the +patch. If you have several big issues to report, you might want to make +separate replies to split the thread. The author of the patch must +answer to these comments, and if subsequent commits address some of +these issues, the reply should refer to them (e.g., by giving the +revision number). + +Anybody is welcome to comment a patch, nevertheless, this responsibility +typically falls upon the shoulders of the project maintainer, or the +code-review peer of the author of the patch. + + + + @c ========================================================== Appendices @node Appendices