From 5a3c79e3bb578d4c367f1cef92ec3bc62e34a1a0 Mon Sep 17 00:00:00 2001
From: hal9 <hal9@users.sourceforge.net>
Date: Fri, 9 Aug 2002 01:15:12 +0000
Subject: [PATCH] Added some notes on pre-release steps (test builds first,
 update ChangeLog).

---
 doc/source/developer-manual.sgml | 67 +++++++++++++++++++++++++-------
 1 file changed, 53 insertions(+), 14 deletions(-)

diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 1196f24f..d6b0e8f5 100644
--- a/doc/source/developer-manual.sgml
+++ b/doc/source/developer-manual.sgml
@@ -8,7 +8,7 @@
 <!entity contacting SYSTEM "contacting.sgml">
 <!entity copyright SYSTEM "copyright.sgml">
 <!entity license SYSTEM "license.sgml">
-<!entity p-version "2.9.15">
+<!entity p-version "2.9.18">
 <!entity p-status "beta">
 <!entity % p-not-stable "INCLUDE">
 <!entity % p-stable "IGNORE">
@@ -23,7 +23,7 @@
                 This file belongs into
                 ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/
                 
- $Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $
+ $Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $
 
  Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org>
  See LICENSE.
@@ -50,7 +50,7 @@
     </pubdate>
 
 
-    <pubdate>$Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $</pubdate>
+    <pubdate>$Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $</pubdate>
 
 <!--
 
@@ -249,14 +249,29 @@ Hal.
     <ulink url="../faq/index.html"><citetitle>FAQ</citetitle></ulink>, and, of
     course this, the <citetitle>developer-manual</citetitle> in this format.
     The <citetitle>README</citetitle>, <citetitle>AUTHORS</citetitle>
-    <citetitle>privoxy.1</citetitle> (man page) files are also now maintained
-    as Docbook SGML. The finished files are all in the top-level source
-    directory are generated files! Also, <filename>index.html</filename>, the
-    <application>Privoxy</application> home page, is maintained as SGML.
+    <citetitle>privoxy.1</citetitle> (man page), and
+    <citetitle>config</citetitle> files are also now maintained as Docbook
+    SGML. These files, when built, in the top-level source directory are
+    generated files! Also, the <application>Privoxy</application> <filename>index.html</filename> (and a 
+    variation on this file, <filename>privoxy-index.html</filename>, 
+    meant for inclusion with doc packages), are maintained as SGML as well.
     <emphasis>DO NOT edit these directly</emphasis>. Edit the SGML source, or
     contact someone involved in the documentation (at present Stefan and
     Hal).
     </para> 
+    <para>
+     <filename>config</filename> requires some special handling. The reason it
+     is maintained this way is so that the extensive comments in the file
+     mirror those in <citetitle>user-manual</citetitle>. But the conversion 
+     process requires going from SGML to HTML to text to special formatting 
+     required for the embedded comments. Some of this does not survive so
+     well. Especially some of the examples that are longer than 80 characters.
+     The build process for this file outputs to <filename>config.new</filename>, 
+     which should be reviewed for errors and mis-formatting. Once satisfied
+     that it is correct, then it should be hand copied to
+     <filename>config</filename>.
+
+    </para>
     <para>
      Other, less formal documents (e.g. <filename>LICENSE</filename>,
      <filename>INSTALL</filename>) are maintained as plain text files in the
@@ -1727,7 +1742,7 @@ static void unload_re_filterfile( void *f ) { ... }</programlisting>
 
     <para><emphasis>Example for file comments:</emphasis></para>
 <programlisting>
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $";
 /*********************************************************************
  *
  * File        :  $S<!-- Break CVS Substitution -->ource$
@@ -1787,7 +1802,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
 <programlisting>
 #ifndef _FILENAME_H
 #define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.3 2002/05/28 04:32:45 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.4 2002/05/29 00:30:59 mal0rd Exp $"
 /*********************************************************************
  *
  * File        :  $S<!-- Break CVS Substitution -->ource$
@@ -2029,7 +2044,8 @@ at sourceforge. Three simple steps:
       <listitem>
        <para>
          Increment the version number (point from odd to even in development
-         branches!) in <filename>configure.in</filename>.
+         branches!) in <filename>configure.in</filename>. (RPM spec files 
+         will need to be incremented as well.)
        </para>
       </listitem> 
       <listitem>
@@ -2050,12 +2066,23 @@ at sourceforge. Three simple steps:
       </listitem>
       <listitem>
        <para>
-        If the HTML documentation is not in sync with the SGML sources
-        you need to regenerate and upload it to the webserver. (If in
-        doubt, just do it.) See the Section "Updating the webserver" in
-        this manual for details.
+        All documentation should be rebuild after the version bump.
+        Finished docs should be then be committed to CVS (for those 
+        without the ability to build these). Some docs may require 
+        rather obscure processing tools. <filename>config</filename>,
+        the man page (and the html version of the man page), and the PDF docs
+        fall in this category. REAMDE, the man page, AUTHORS, and config
+        should all also be committed to CVS for other packageers. The 
+        formal docs should be uploaded to the webserver. See the
+        Section "Updating the webserver" in this manual for details.
        </para>
       </listitem> 
+      <listitem>
+       <para>
+        All developers should look at the <filename>ChangeLog</filename> and
+        make sure noteworthy changes are referenced.
+       </para>
+     </listitem> 
       <listitem>
        <para>
         <emphasis>Commit all files that were changed in the above steps!</emphasis>
@@ -2222,6 +2249,15 @@ at sourceforge. Three simple steps:
        maintainers to do this if you can't).
       </para>
     </listitem> 
+    <listitem>
+     <para>
+       Packagers should do a <quote>clean</quote> install of their 
+       package after building it. So any previous installs should be 
+       removed first to ensure the integrity of the newly built package. 
+       Then run the package for a while to make sure there are no 
+       obvious problems, before uploading.
+     </para>
+    </listitem> 
 
       </itemizedlist>
      </para> 
@@ -2822,6 +2858,9 @@ at sourceforge. Three simple steps:
   Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 
   $Log: developer-manual.sgml,v $
+  Revision 1.46.2.4  2002/05/29 00:30:59  mal0rd
+  Fixed a little formatting.  Clarified debian section.
+
   Revision 1.46.2.3  2002/05/28 04:32:45  hal9
   Change hints on bundling index.html to privoxy-index.html
 
-- 
2.49.0