From: hal9 <hal9@users.sourceforge.net> Date: Wed, 4 Sep 2002 01:55:44 +0000 (+0000) Subject: Migrating developer manual, and related sgml files from 3.0. Add additional X-Git-Tag: v_3_1_archive_branchpoint~201 X-Git-Url: http://www.privoxy.org/gitweb/%22https:/developer-manual/faq/@default-cgi@/diff?a=commitdiff_plain;h=1384db7d3e57bd489472bbc189ecb0749d6811e9;p=privoxy.git Migrating developer manual, and related sgml files from 3.0. Add additional commentary on cvs, versioning, stable branches, and how to handle stable branches in cvs. --- diff --git a/doc/source/contacting.sgml b/doc/source/contacting.sgml index ff60f4b1..98bc8a9c 100644 --- a/doc/source/contacting.sgml +++ b/doc/source/contacting.sgml @@ -3,7 +3,7 @@ Purpose : Entity included in other project documents. - $Id: contacting.sgml,v 1.16 2002/06/03 00:28:16 hal9 Exp $ + $Id: contacting.sgml,v 1.15.2.2 2002/07/26 15:21:33 oes Exp $ Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org> See LICENSE. @@ -19,7 +19,6 @@ README user-manual webserver/index.sgml - privoxy-index.html announce.sgml --> @@ -106,7 +105,9 @@ New, improved <filename>default.action</filename> files will occasionally be made available based on your feedback. These will be announced on the <ulink url="http://lists.sourceforge.net/lists/listinfo/ijbswa-announce">ijbswa-announce</ulink> - list and available from our <ulink url="http://sf.net/projects/ijbswa/">project page</ulink>. + list and available from our the <ulink + url="http://sourceforge.net/project/showfiles.php?group_id=11118">files section</ulink> of + our <ulink url="http://sf.net/projects/ijbswa/">project page</ulink>. </para> </sect2> diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 8b36ac43..b8d762aa 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -23,7 +23,7 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $ + $Id: developer-manual.sgml,v 2.1 2002/07/29 22:08:40 jongfoster Exp $ Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org> See LICENSE. @@ -48,7 +48,7 @@ </pubdate> - <pubdate>$Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $</pubdate> + <pubdate>$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $</pubdate> <!-- @@ -67,7 +67,7 @@ Hal. --> -<abstract> + <abstract> <![%dummy;[ <para> @@ -93,6 +93,8 @@ Hal. <!-- end boilerplate --> <para> + Please note that this document is constantly evolving. This copy represents + the state at the release of version &p-version;. You can find the latest version of the this manual at <ulink url="http://www.privoxy.org/developer-manual/">http://www.privoxy.org/developer-manual/</ulink>. Please see <link linkend="contact">the Contact section</link> @@ -136,6 +138,12 @@ Hal. url="mailto:developers@privoxy.org">the list</ulink> and wait until a project manager has added you. </para> + <para> + You will also need to have a cvs package installed, which will + entail having ssh installed as well (which seems to be a requirement of + SourceForge), in order to access the cvs repository. Having the GNU build + tools is also going to be important (particularly, autoconf and gmake). + </para> <para> For the time being (read, this section is under construction), please refer to the extensive comments in the source code. @@ -165,12 +173,45 @@ Hal. </para> </sect2> - <sect2 id="cvscommit"><title>CVS Commit Guideline</title> + <sect2 id="cvsbranches"> + <title>Branches</title> + <para> + Within the CVS repository, there are modules and branches. As + mentioned, the sources are in the <literal>current</literal> + <quote>module</quote>. Other modules are present for platform specific + issues. There is a webview of the CVS hierarchy at <ulink + url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/</ulink>, + which might help with visualizing how these pieces fit together. + </para> + <para> + Branches are used to fork a sub-development path from the main trunk. + Within the <literal>current</literal> module where the sources are, there + is always at least one <quote>branch</quote> from the main trunk + devoted to a stable release series. The main trunk is where active + development takes place for the next stable series (e.g. 3.2.x). + So just prior to each stable series (e.g. 3.0.x), a branch is created + just for stable series releases (e.g. 3.0.0 -> 3.0.1 -> 3.0.2, etc). + Once the initial stable release of any stable branch has taken place, + this branch is <emphasis>only used for bugfixes</emphasis>, which have + had prior testing before being committed to CVS. (See <link + linkend="versionnumbers">Version Numbers</link> below for details on + versioning.) + </para> + </sect2> + + <sect2 id="cvscommit"><title>CVS Commit Guidelines</title> <para> The source tree is the heart of every software project. Every effort must be made to ensure that it is readable, compilable and consistent at all - times. We therefore ask anyone with CVS access to strictly adhere to the - following guidelines: + times. There are differing guidelines for the stable branch and the + main development trunk, and we ask anyone with CVS access to strictly + adhere to the following guidelines: + </para> + + <para> + Basic Guidelines, for all branches: + </para> + <para> <itemizedlist> <listitem><para> Never (read: <emphasis>never, ever</emphasis>) be tempted to commit @@ -195,16 +236,68 @@ Hal. </para></listitem> <listitem><para> Before changing things on CVS, make sure that your changes are in line - with the team's general consensus on what should be done (see below). + with the team's general consensus on what should be done. </para></listitem> + <listitem> + <para> + Note that near a major public release, we get more cautious. + There is always the possibility to submit a patch to the <ulink + url="http://sourceforge.net/tracker/?atid=311118&group_id=11118&func=browse">patch + tracker</ulink> instead. + </para> + </listitem> </itemizedlist> </para> + + <para> + Stable branches are handled with more care, especially after the + initial *.*.0 release, and we are just in bugfix mode. In addition to + the above, the below applies only to the stable branch (currently the + v_3_0_branchpoint branch): + </para> + + <para> + <itemizedlist> + <listitem><para> + Do <emphasis>not commit anything</emphasis> into the stable branch, + unless immediately before a new release! There needs to be testing + done before it hits CVS, and to ensure that all changes are + appropriate just to fix whatever the problem is. + </para></listitem> + <listitem> + <para> + Submit any proposed changes as patches first to the patch tracker on + Sourceforge: <ulink url="http://sourceforge.net/tracker/?group_id=11118&atid=311118">http://sourceforge.net/tracker/?group_id=11118&atid=311118</ulink>. + Then ask for peer review. + </para> + </listitem> + <listitem> + <para> + Do not commit <emphasis>anything</emphasis> unless your patches + been well tested first, by other members of the project, + and has prior approval of the project leaders or consensus of the + devel list. + </para> + </listitem> + <listitem> + <para> + Do not even think about anything except bugfixes. No new features! + </para> + </listitem> + + </itemizedlist> + </para> </sect2> +<!-- + This sounds vague, dated, and out of step with current development style. + Removing 09/03/02, HB. + <sect2 id="cvswhenask"><title>Discussing Changes First</title> <para> - We don't have a too formal policy on this, just use common sense. Hints: If it is.. - <orderedlist numeration="arabic"> + We don't have a formal policy for the development branch, just use + common sense. Hints: If it is.. + <orderedlist numeration="arabic"> <listitem><para> ..a bug-fix / clean-up / cosmetic thing: shoot </para></listitem> @@ -231,6 +324,7 @@ Hal. tracker</ulink> instead. </para> </sect2> + --> </sect1> <!-- ~~~~~ New section ~~~~~ --> @@ -254,8 +348,7 @@ Hal. 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). + contact someone involved in the documentation (at present Hal). </para> <para> <filename>config</filename> requires some special handling. The reason it @@ -268,7 +361,6 @@ Hal. 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>, @@ -301,7 +393,8 @@ Hal. <listitem><para> First, build the docs by running <computeroutput>make dok</computeroutput> (or alternately <computeroutput>make - redhat-dok</computeroutput>). + redhat-dok</computeroutput>). For PDF docs, do <computeroutput>make + dok-pdf</computeroutput>. </para></listitem> <listitem><para> Run <computeroutput>make webserver</computeroutput> which copies all @@ -499,7 +592,7 @@ Hal. <listitem> <para> Our documents are available in differing formats. Right now, they - are just plain text, and HTML, but PDF, and others is always a + are just plain text, TML, and PDF, but others are always a future possibility. Be careful with URLs (<ulink>), and avoid this mistake: </para> @@ -1740,7 +1833,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.50 2002/06/05 00:31:55 hal9 Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $"; /********************************************************************* * * File : $S<!-- Break CVS Substitution -->ource$ @@ -1800,7 +1893,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.50 2002/06/05 00:31:55 hal9 Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $" /********************************************************************* * * File : $S<!-- Break CVS Substitution -->ource$ @@ -1978,7 +2071,7 @@ at sourceforge. Three simple steps: <para> First you need to determine which version number the release will have. <application>Privoxy</application> version numbers consist of three numbers, - separated by dots, like in X.Y.Z, where: + separated by dots, like in X.Y.Z (e.g. 3.0.0), where: <itemizedlist> <listitem> <para> @@ -2020,6 +2113,22 @@ at sourceforge. Three simple steps: </listitem> </itemizedlist> </para> + <para> + In summary, the main CVS trunk is the development branch where new + features are being worked on for the next stable series. This should + almost always be where the most activity takes place. There is always at + least one stable branch from the trunk, e.g now it is 3.0, which is only + used to release stable versions. Once the initial .0 release of the + stable branch has been done, then as a rule, only bugfixes that have had + prior testing should be committed to the stable branch. At that point, it + is mostly <quote>hands off</quote>. Once there are enough bugfixes to + justify a new release, the version of this branch is again incremented + Example: 3.0.0 -> 3.0.1 -> 3.0.2, etc are all stable releases from within + the stable branch. 3.1.x is currently the main trunk, and where work on + 3.2.x is taking place. If any questions, please post to the devel list + <emphasis>before</emphasis> committing to a stable branch! + + </para> </sect2> @@ -2042,7 +2151,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> @@ -2063,12 +2173,37 @@ 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 packagers. The + formal docs should be uploaded to the webserver. See the + Section "Updating the webserver" in this manual for details. + </para> + </listitem> + <listitem> + <para> + The <citetitle>User Manual</citetitle> is also used for context + sensitive help for the CGI editor. This is version sensitive, so that + the user will get appropriate help for his/her release. So with + each release a fresh version should be uploaded to the webserver + (this is in addition to the main <citetitle>User Manual</citetitle> + link from the main page since we need to keep manuals for various + versions available). The CGI pages will link to something like + <literal>http://privoxy.org/$(VERSION)/user-manual/</literal>. This + will need to be updated for each new release. There is no Makefile + target for this at this time!!! It needs to be done manually. </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> @@ -2112,7 +2247,8 @@ at sourceforge. Three simple steps: <para> For <emphasis>all</emphasis> types of packages, including the source tarball, <emphasis>you must make sure that you build from clean sources by exporting - the right version from CVS into an empty directory:</emphasis>. + the right version from CVS into an empty directory</emphasis> (just press return when + asked for a password): </para> <para> @@ -2235,6 +2371,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> @@ -2715,7 +2860,9 @@ at sourceforge. Three simple steps: mailing list</ulink>, Subject: "Version X.Y.Z available for download". Be sure to include the <ulink url="http://sourceforge.net/project/showfiles.php?group_id=11118">download - location</ulink>, the release notes and the change log. + location</ulink>, the release notes and the Changelog. Also, post an + updated News item on the project page Sourceforge, and update the Home + page and docs linked from the Home page (see below). </para> </sect2> @@ -2724,31 +2871,33 @@ at sourceforge. Three simple steps: <!-- ~~~~~ New section ~~~~~ --> <sect1 id="webserver-update"><title>Update the Webserver</title> <para> - When updating the webserver, please follow these steps to make - sure that no broken links, inconsistent contents or permission - problems will occur: + The webserver should be updated at least with each stable release. When + updating, please follow these steps to make sure that no broken links, + inconsistent contents or permission problems will occur (as it has many + times in the past!): </para> <para> - If you have changed anything in the documentation source SGML files, - do: + If you have changed anything in the stable-branch documentation source + SGML files, do: </para> <para> <programlisting> - make dok # (or make redhat-dok if make dok doesn't work for you) + make dok dok-pdf # (or 'make redhat-dok dok-pdf' if 'make dok' doesn't work for you) </programlisting> </para> <para> That will generate <filename>doc/webserver/user-manual</filename>, <filename>doc/webserver/developer-manual</filename>, - <filename>doc/webserver/faq</filename> and + <filename>doc/webserver/faq</filename>, + <filename>doc/pdf/*.pdf</filename> and <filename>doc/webserver/index.html</filename> automatically. </para> <para> - If you changed the manual page source, generate + If you changed the manual page sources, generate <filename>doc/webserver/man-page/privoxy-man-page.html</filename> by running <quote><command>make man</command></quote>. (This is - a separate target due to dependencies on some obscure perl scripts. - See comments in <filename>GNUmakefile</filename>.) + a separate target due to dependencies on some obscure perl scripts + [now in CVS, but not well tested]. See comments in <filename>GNUmakefile</filename>.) </para> <para> If you want to add new files to the webserver, create them locally in @@ -2756,7 +2905,8 @@ at sourceforge. Three simple steps: create new directories under <filename>doc/webserver</filename>). </para> <para> - Next, commit any changes from the above steps to CVS. All set? Then do + Next, commit any changes from the above steps to CVS. All set? + If these are docs in the stable branch, then do: </para> <para> <programlisting> @@ -2770,7 +2920,9 @@ at sourceforge. Three simple steps: </para> <para> Please do <emphasis>NOT</emphasis> use any other means of transferring - files to the webserver to avoid permission problems. + files to the webserver to avoid permission problems. Also, please do not + upload docs from development branches or versions. The publicly posted + docs should be in sync with the last official release. </para> </sect1> @@ -2835,21 +2987,26 @@ at sourceforge. Three simple steps: Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ - Revision 1.50 2002/06/05 00:31:55 hal9 - Mass commit for new entities, most significantly so docs can read version - and code status info from tmp files, so perl is no longer used. Also, docs can - differentiate on alpha -> beta -> stable now. + Revision 1.46.2.8 2002/08/17 00:16:10 hal9 + Add note on updating webserver for User-manual/CGI editor, which is version + dependent (and different from main UM link). + + Revision 1.46.2.7 2002/08/14 17:29:25 hal9 + Add small notes on post-release steps, and uploading docs to webserver. + + Revision 1.46.2.6 2002/08/10 11:40:25 oes + Added disclaimer about probably being out-of-date and two small hints - Revision 1.49 2002/06/03 00:28:16 hal9 - Sync with various changes from 3.0 branch. Add two new files for config stuff. + Revision 1.46.2.5 2002/08/09 01:15:12 hal9 + Added some notes on pre-release steps (test builds first, update ChangeLog). - Revision 1.51 2002/05/29 00:30:59 mal0rd + Revision 1.46.2.4 2002/05/29 00:30:59 mal0rd Fixed a little formatting. Clarified debian section. - Revision 1.50 2002/05/28 04:32:45 hal9 + Revision 1.46.2.3 2002/05/28 04:32:45 hal9 Change hints on bundling index.html to privoxy-index.html - Revision 1.49 2002/05/26 17:04:24 hal9 + Revision 1.46.2.2 2002/05/26 17:04:24 hal9 -Spellcheck, very minor edits, and sync across branches Revision 1.48 2002/05/26 12:48:31 roro diff --git a/doc/source/history.sgml b/doc/source/history.sgml index cfc3a813..2621f36c 100644 --- a/doc/source/history.sgml +++ b/doc/source/history.sgml @@ -3,7 +3,7 @@ Purpose : Entity included in other project documents. - $Id: history.sgml,v 1.7.2.2 2002/07/30 20:04:31 hal9 Exp $ + $Id: history.sgml,v 2.2 2002/07/30 21:54:50 hal9 Exp $ Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org> See LICENSE. @@ -67,7 +67,7 @@ <para> The result of this is <application>Privoxy</application>, whose first - stable release, 3.0, is due late summer or early fall 2002. + stable release, 3.0, was released August, 2002. <!-- Cautious!!!!!!!!! ;) --> </para> diff --git a/doc/source/seealso.sgml b/doc/source/seealso.sgml index e9e28d06..9c906302 100644 --- a/doc/source/seealso.sgml +++ b/doc/source/seealso.sgml @@ -3,7 +3,7 @@ Purpose : Entity included in other project documents. - $Id: seealso.sgml,v 1.9 2002/05/17 14:16:26 oes Exp $ + $Id: seealso.sgml,v 1.9.2.1 2002/08/23 02:59:34 hal9 Exp $ Copyright (C) 2001, 2002 Privoxy Developers <developers@privoxy.org> See LICENSE. @@ -66,6 +66,12 @@ <ulink url="javascript:w=Math.floor(screen.width/2);h=Math.floor(screen.height*0.9);void(window.open('http://www.privoxy.org/actions','Feedback','screenx='+w+',width='+w+',height='+h+',scrollbars=yes,toolbar=no,location=no,directories=no,status=no,menubar=no,copyhistory=no').focus());">http://www.privoxy.org/actions/</ulink>, to submit <quote>misses</quote> to the developers. </member> </simplelist> + <simplelist> + <member> + <ulink url="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/contrib/">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/contrib/</ulink>, cool + and fun ideas from <application>Privoxy</application> users. + </member> + </simplelist> <simplelist> <member> <ulink url="http://www.junkbusters.com/ht/en/cookies.html">http://www.junkbusters.com/ht/en/cookies.html</ulink>,