Copyright © 2001, 2002 by Privoxy Developers
-$Id: developer-manual.sgml,v 1.46.2.11 2002/12/11 13:12:15 hal9 Exp $
+$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $
The developer manual provides guidance on coding, testing, packaging,
documentation and other issues of importance to those involved with Privoxy
join the team.
Please note that this document is constantly evolving. This copy represents the
-state at the release of version 3.0.1. You can find the latest version of the
+state at the release of version 3.0.0. You can find the latest version of the
this manual at http://www.privoxy.org/developer-manual/. Please see the Contact
section on how to contact the developers.
2. The CVS Repository
2.1. Access to CVS
- 2.2. Branches
- 2.3. CVS Commit Guidelines
+ 2.2. CVS Commit Guideline
+ 2.3. Discussing Changes First
3. Documentation Guidelines
1.1. Quickstart to Privoxy Development
-The first step is to join the developer's mailing list. You can submit your
-ideas, or even better patches. Patches are best submitted to the Sourceforge
-tracker set up for this purpose, but can be sent to the list for review too.
+You'll need an account on Sourceforge to support our development. Mail your ID
+to 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), you can also
-refer to the extensive comments in the source code. In fact, reading the code
-is recommended in any case.
+For the time being (read, this section is under construction), please refer to
+the extensive comments in the source code.
-------------------------------------------------------------------------------
2. The CVS Repository
-If you become part of the active development team, you will eventually need
-write access to our holy grail, the CVS repository. One of the team members
-will need to set this up for you. Please read this chapter completely before
-accessing via CVS.
+If you intend to help us with programming, documentation or packaging you will
+need write access to our holy grail, the CVS repository. Please read this
+chapter completely before accessing via CVS.
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------
-2.2. 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.)
-
-This will result in at least two active branches, which means there may be
-occasions that require the same (or similar) item to be checked into to two
-different places (assuming its a bugfix and needs fixing in both the stable and
-unstable trees). This also means that in order to have access to both trees,
-both will have to be checked out separately. Use the cvs -r flag to check out a
-branch, e.g: cvs co -r v_3_0_branch current.
-
--------------------------------------------------------------------------------
-
-2.3. CVS Commit Guidelines
+2.2. CVS Commit Guideline
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.
-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
+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:
-Basic Guidelines, for all branches:
-
* Never (read: never, ever) be tempted to commit that small change without
testing it thoroughly first. When we're close to a public release, ask a
fellow developer to review your changes.
necessary, prepare the commit messages in advance.
* Before changing things on CVS, make sure that your changes are in line with
- the team's general consensus on what should be done.
+ the team's general consensus on what should be done (see below).
- * 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.
+ * Don't commit into the stable branch, unless immediately before a new
+ release. (See Version Numbers below for details.) Collect your changes on
+ the patches 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_branch branch):
+-------------------------------------------------------------------------------
+
+2.3. Discussing Changes First
+
+We don't have a too formal policy on this, just use common sense. Hints: If it
+is..
- * Do not commit anything unless your proposed changes have been well tested
- first, preferably by other members of the project, or have prior approval
- of the project leaders or consensus of the devel list.
+ 1. ..a bug-fix / clean-up / cosmetic thing: shoot
- * Where possible, bugfixes and changes should be tested in the main
- development trunk first. There may be occasions where this is not feasible,
- though.
+ 2. ..a new feature that can be turned off: shoot
- * Alternately, proposed changes can be submitted as patches to the patch
- tracker on Sourceforge first: http://sourceforge.net/tracker/?group_id=
- 11118&atid=311118. Then ask for peer review.
+ 3. ..a clear improvement w/o side effects on other parts of the code: shoot
- * Do not even think about anything except bugfixes. No new features!
+ 4. ..a matter of taste: ask the list
+ 5. ..a major redesign of some part of the code: ask the list
+
+Note that near a major public release, we get a bit more cautious - if unsure,
+it doesn't hurt to ask first. There is always the possibility to submit a patch
+to the patches tracker instead.
+
-------------------------------------------------------------------------------
3. Documentation Guidelines
* Commonly used "internal entities":
- p-version: the Privoxy version string, e.g. "3.0.1".
+ p-version: the Privoxy version string, e.g. "3.0.0".
p-status: the project status, either "alpha", "beta", or "stable".
p-not-stable: use to conditionally include text in "not stable" releases
(e.g. "beta").
Example for file comments:
-const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.11 2002/12/11 13:12:15 hal9 Exp $";
-/*********************************************************************
- *
- * File : $Source$
- *
- * Purpose : (Fill me in with a good description!)
- *
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
- * Privoxy team. http://www.privoxy.org/
- *
- * Based on the Internet Junkbuster originally written
- * by and Copyright (C) 1997 Anonymous Coders and
- * Junkbusters Corporation. http://www.junkbusters.com
- *
- * This program is free software; you can redistribute it
- * and/or modify it under the terms of the GNU General
- * Public License as published by the Free Software
- * Foundation; either version 2 of the License, or (at
- * your option) any later version.
- *
- * This program is distributed in the hope that it will
- * be useful, but WITHOUT ANY WARRANTY; without even the
- * implied warranty of MERCHANTABILITY or FITNESS FOR A
- * PARTICULAR PURPOSE. See the GNU General Public
- * License for more details.
- *
- * The GNU General Public License should be included with
- * this file. If not, you can view it at
- * http://www.gnu.org/copyleft/gpl.html
- * or write to the Free Software Foundation, Inc., 59
- * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- *
- * Revisions :
- * $Log$
- *
- *********************************************************************/
-
-
-#include "config.h"
-
- ...necessary include files for us to do our work...
-
-const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $";
+/*********************************************************************
+ *
+ * File : $Source$
+ *
+ * Purpose : (Fill me in with a good description!)
+ *
+ * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * Privoxy team. http://www.privoxy.org/
+ *
+ * Based on the Internet Junkbuster originally written
+ * by and Copyright (C) 1997 Anonymous Coders and
+ * Junkbusters Corporation. http://www.junkbusters.com
+ *
+ * This program is free software; you can redistribute it
+ * and/or modify it under the terms of the GNU General
+ * Public License as published by the Free Software
+ * Foundation; either version 2 of the License, or (at
+ * your option) any later version.
+ *
+ * This program is distributed in the hope that it will
+ * be useful, but WITHOUT ANY WARRANTY; without even the
+ * implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU General Public
+ * License for more details.
+ *
+ * The GNU General Public License should be included with
+ * this file. If not, you can view it at
+ * http://www.gnu.org/copyleft/gpl.html
+ * or write to the Free Software Foundation, Inc., 59
+ * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ * Revisions :
+ * $Log$
+ *
+ *********************************************************************/
+
+
+#include "config.h"
+
+ ...necessary include files for us to do our work...
+
+const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
Note: This declares the rcs variables that should be added to the
"show-proxy-args" page. If this is a brand new creation by you, you are free to
Example for file header comments:
-#ifndef _FILENAME_H
-#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.11 2002/12/11 13:12:15 hal9 Exp $"
-/*********************************************************************
- *
- * File : $Source$
- *
- * Purpose : (Fill me in with a good description!)
- *
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
- * Privoxy team. http://www.privoxy.org/
- *
- * Based on the Internet Junkbuster originally written
- * by and Copyright (C) 1997 Anonymous Coders and
- * Junkbusters Corporation. http://www.junkbusters.com
- *
- * This program is free software; you can redistribute it
- * and/or modify it under the terms of the GNU General
- * Public License as published by the Free Software
- * Foundation; either version 2 of the License, or (at
- * your option) any later version.
- *
- * This program is distributed in the hope that it will
- * be useful, but WITHOUT ANY WARRANTY; without even the
- * implied warranty of MERCHANTABILITY or FITNESS FOR A
- * PARTICULAR PURPOSE. See the GNU General Public
- * License for more details.
- *
- * The GNU General Public License should be included with
- * this file. If not, you can view it at
- * http://www.gnu.org/copyleft/gpl.html
- * or write to the Free Software Foundation, Inc., 59
- * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- *
- * Revisions :
- * $Log$
- *
- *********************************************************************/
-
-
-#include "project.h"
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
- ... function headers here ...
-
-
-/* Revision control strings from this header and associated .c file */
-extern const char FILENAME_rcs[];
-extern const char FILENAME_h_rcs[];
-
-
-#ifdef __cplusplus
-} /* extern "C" */
-#endif
-
-#endif /* ndef _FILENAME_H */
-
-/*
- Local Variables:
- tab-width: 3
- end:
-*/
+#ifndef _FILENAME_H
+#define _FILENAME_H
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.46.2.8 2002/08/17 00:16:10 hal9 Exp $"
+/*********************************************************************
+ *
+ * File : $Source$
+ *
+ * Purpose : (Fill me in with a good description!)
+ *
+ * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * Privoxy team. http://www.privoxy.org/
+ *
+ * Based on the Internet Junkbuster originally written
+ * by and Copyright (C) 1997 Anonymous Coders and
+ * Junkbusters Corporation. http://www.junkbusters.com
+ *
+ * This program is free software; you can redistribute it
+ * and/or modify it under the terms of the GNU General
+ * Public License as published by the Free Software
+ * Foundation; either version 2 of the License, or (at
+ * your option) any later version.
+ *
+ * This program is distributed in the hope that it will
+ * be useful, but WITHOUT ANY WARRANTY; without even the
+ * implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU General Public
+ * License for more details.
+ *
+ * The GNU General Public License should be included with
+ * this file. If not, you can view it at
+ * http://www.gnu.org/copyleft/gpl.html
+ * or write to the Free Software Foundation, Inc., 59
+ * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ * Revisions :
+ * $Log$
+ *
+ *********************************************************************/
+
+
+#include "project.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+ ... function headers here ...
+
+
+/* Revision control strings from this header and associated .c file */
+extern const char FILENAME_rcs[];
+extern const char FILENAME_h_rcs[];
+
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* ndef _FILENAME_H */
+
+/*
+ Local Variables:
+ tab-width: 3
+ end:
+*/
Example for function comments:
6.1. Version numbers
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
-(e.g. 3.0.0), where:
+version numbers consist of three numbers, separated by dots, like in X.Y.Z,
+where:
* X, the version major, is rarely ever changed. It is increased by one if
turning a development branch into stable substantially changes the
distinguished from released versions. The point version is reset to zero
when the minor changes.
- Stable branches work a little differently, since there should be little to
- no development happening in such branches. Remember, only bugfixes, which
- presumably should have had some testing before being committed. Stable
- branches will then have their version reported as 0.0.0, during that period
- between releases when changes are being added. This is to denote that this
- code is not for release. Then as the release nears, the version is bumped
- according: e.g. 3.0.1 -> 0.0.0 -> 3.0.2.
-
-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. 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!
-
-Developers should remember too that if they commit a bugfix to the stable
-branch, this will more than likely require a separate submission to the main
-trunk, since these are separate development trees within CVS. If you are
-working on both, then this would require at least two separate check outs (i.e
-main trunk, and the stable release branch, which is v_3_0_branch at the
-moment).
-
-------------------------------------------------------------------------------
6.2. Before the Release: Freeze
directory. (See "Building and releasing packages" above). Then add a log entry
to debian/changelog, if it is not already there, for example by running:
- debchange -v 3.0.1-stable-1 "New upstream version"
+ debchange -v 3.0.0-stable-1 "New upstream version"
Then, run:
dpkg-buildpackage -rfakeroot -us -uc -b
-This will create ../privoxy_3.0.1-stable-1_i386.deb which can be uploaded. To
+This will create ../privoxy_3.0.0-stable-1_i386.deb which can be uploaded. To
upload the package to Sourceforge, simply issue
make debian-upload
group_id=11118, making sure you are logged in. Find your target platform in the
second column, and click Add Release. You will then need to create a new
release for your package, using the format of $VERSION ($CODE_STATUS), e.g.
-3.0.1 (beta).
+3.0.0 (beta).
Now just follow the prompts. Be sure to add any appropriate Release notes. You
should see your freshly uploaded packages in "Step 2. Add Files To This
projects / privoxy.git / blobdiff