29 Apr
2004
29 Apr
'04
2:38 p.m.
+@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(a)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