From 1384db7d3e57bd489472bbc189ecb0749d6811e9 Mon Sep 17 00:00:00 2001 From: hal9 Date: Wed, 4 Sep 2002 01:55:44 +0000 Subject: [PATCH] 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. --- doc/source/contacting.sgml | 7 +- doc/source/developer-manual.sgml | 247 +++++++++++++++++++++++++------ doc/source/history.sgml | 4 +- doc/source/seealso.sgml | 8 +- 4 files changed, 215 insertions(+), 51 deletions(-) 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 See LICENSE. @@ -19,7 +19,6 @@ README user-manual webserver/index.sgml - privoxy-index.html announce.sgml --> @@ -106,7 +105,9 @@ New, improved default.action files will occasionally be made available based on your feedback. These will be announced on the ijbswa-announce - list and available from our project page. + list and available from our the files section of + our project page. 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 See LICENSE. @@ -48,7 +48,7 @@ - $Id: developer-manual.sgml,v 1.50 2002/06/05 00:31:55 hal9 Exp $ + $Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $ - + @@ -93,6 +93,8 @@ Hal. + 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 http://www.privoxy.org/developer-manual/. Please see the Contact section @@ -136,6 +138,12 @@ Hal. url="mailto:developers@privoxy.org">the list and wait until a project manager has added you. + + 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). + 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. - CVS Commit Guideline + + Branches + + Within the CVS repository, there are modules and branches. As + mentioned, the sources are in the current + module. Other modules are present for platform specific + issues. There is a webview of the CVS hierarchy at http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/, + which might help with visualizing how these pieces fit together. + + + Branches are used to fork a sub-development path from the main trunk. + Within the current module where the sources are, there + is always at least one branch 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 only used for bugfixes, which have + had prior testing before being committed to CVS. (See Version Numbers below for details on + versioning.) + + + + CVS Commit Guidelines 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: + + + + Basic Guidelines, for all branches: + + Never (read: never, ever) be tempted to commit @@ -195,16 +236,68 @@ Hal. 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. + + + Note that near a major public release, we get more cautious. + There is always the possibility to submit a patch to the patch + tracker instead. + + + + + 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): + + + + + + Do not commit anything 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. + + + + Submit any proposed changes as patches first to the patch tracker on + Sourceforge: http://sourceforge.net/tracker/?group_id=11118&atid=311118. + Then ask for peer review. + + + + + Do not commit anything 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. + + + + + Do not even think about anything except bugfixes. No new features! + + + + + + @@ -254,8 +348,7 @@ Hal. variation on this file, privoxy-index.html, meant for inclusion with doc packages), are maintained as SGML as well. DO NOT edit these directly. 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). config 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 config. - Other, less formal documents (e.g. LICENSE, @@ -301,7 +393,8 @@ Hal. First, build the docs by running make dok (or alternately make - redhat-dok). + redhat-dok). For PDF docs, do make + dok-pdf. Run make webserver which copies all @@ -499,7 +592,7 @@ Hal. 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: @@ -1740,7 +1833,7 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -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 : $Source$ @@ -1800,7 +1893,7 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #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 : $Source$ @@ -1978,7 +2071,7 @@ at sourceforge. Three simple steps: First you need to determine which version number the release will have. Privoxy 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: @@ -2020,6 +2113,22 @@ at sourceforge. Three simple steps: + + 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 hands off. 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 + before committing to a stable branch! + + @@ -2042,7 +2151,8 @@ at sourceforge. Three simple steps: Increment the version number (point from odd to even in development - branches!) in configure.in. + branches!) in configure.in. (RPM spec files + will need to be incremented as well.) @@ -2063,12 +2173,37 @@ at sourceforge. Three simple steps: - 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. config, + 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. + + + + + The User Manual 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 User Manual + link from the main page since we need to keep manuals for various + versions available). The CGI pages will link to something like + http://privoxy.org/$(VERSION)/user-manual/. 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. + + + All developers should look at the ChangeLog and + make sure noteworthy changes are referenced. + + Commit all files that were changed in the above steps! @@ -2112,7 +2247,8 @@ at sourceforge. Three simple steps: For all types of packages, including the source tarball, you must make sure that you build from clean sources by exporting - the right version from CVS into an empty directory:. + the right version from CVS into an empty directory (just press return when + asked for a password): @@ -2235,6 +2371,15 @@ at sourceforge. Three simple steps: maintainers to do this if you can't). + + + Packagers should do a clean 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. + + @@ -2715,7 +2860,9 @@ at sourceforge. Three simple steps: mailing list, Subject: "Version X.Y.Z available for download". Be sure to include the download - location, the release notes and the change log. + location, 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). @@ -2724,31 +2871,33 @@ at sourceforge. Three simple steps: Update the Webserver - 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!): - 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: - 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) That will generate doc/webserver/user-manual, doc/webserver/developer-manual, - doc/webserver/faq and + doc/webserver/faq, + doc/pdf/*.pdf and doc/webserver/index.html automatically. - If you changed the manual page source, generate + If you changed the manual page sources, generate doc/webserver/man-page/privoxy-man-page.html by running make man. (This is - a separate target due to dependencies on some obscure perl scripts. - See comments in GNUmakefile.) + a separate target due to dependencies on some obscure perl scripts + [now in CVS, but not well tested]. See comments in GNUmakefile.) 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 doc/webserver). - 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: @@ -2770,7 +2920,9 @@ at sourceforge. Three simple steps: Please do NOT 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. @@ -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 See LICENSE. @@ -67,7 +67,7 @@ The result of this is Privoxy, whose first - stable release, 3.0, is due late summer or early fall 2002. + stable release, 3.0, was released August, 2002. 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 See LICENSE. @@ -66,6 +66,12 @@ http://www.privoxy.org/actions/, to submit misses to the developers. + + + http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/ijbswa/contrib/, cool + and fun ideas from Privoxy users. + + http://www.junkbusters.com/ht/en/cookies.html, -- 2.39.2