Copyright &my-copy; 2001-2021 by Privoxy Developers This is here to keep vim syntax file from breaking :/ If I knew enough to fix it, I would. PLEASE DO NOT REMOVE! HB: hal@foobox.net ]]> The developer manual provides guidance on coding, testing, packaging, documentation and other issues of importance to those involved with Privoxy development. It is mandatory (and helpful!) reading for anyone who wants to join the team. Note that it's currently out of date and may not be entirely correct. As always, patches are welcome. 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 https://www.privoxy.org/developer-manual/. Please have a look at the contact section in the user manual if you are interested in contacting the developers. Privoxy, as an heir to Junkbuster, is a Free Software project. As such, Privoxy development is potentially open to anyone who has the time, knowledge, and desire to contribute in any capacity. Our goals are simply to continue the mission, to improve Privoxy, and to make it available to as wide an audience as possible. One does not have to be a programmer to contribute. Packaging, testing, documenting and porting, are all important jobs as well. The first step is to join the privoxy-devel mailing list. You can submit your ideas or, even better, patches. Patches can also be submitted to the Sourceforge patch tracker. You will also need to have a git package installed, in order to access the git 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. If you become part of the active development team, you will eventually need write access to our holy grail, the Git repository. One of the team members will need to set this up for you. Please read this chapter completely before accessing via Git. The project's Git repository is hosted on the Privoxy webserver. For Privoxy team members with push privileges the Git repository URL is ssh://git@git.privoxy.org:23/git/privoxy.git. Contributors without push privileges can git clone https://www.privoxy.org/git/privoxy.git. The central repository is called privoxy, and the source branch is called master. Subfolders exist within the project for target-dependent build and packaging tools, each including the name of the target operating system in their name (e.g. Windows, OSXPackageBuilder, debian). There is a webview of the Git hierarchy at https://www.privoxy.org/gitweb/?p=privoxy.git;a=tree, which might help with visualizing how these pieces fit together. Whilst the central repository contains only the master branch, developers are of course free to create branches in their local repositories as they develop features, fixes, or update the target-dependent tools. Only once such changes are fully tested ought they be pushed back to the central repository master branch. Before pushing stuff, please rebase it on a current master so we get an uncomplicated commit history. Avoid merges where possible. Here's an example git sesssion that should result in a merge-free history: fk@t520 ~/git/privoxy $git checkout master Switched to branch 'master' Your branch is up to date with 'origin/master'. # Make sure you have the latest changes fk@t520 ~/git/privoxy $git pull Already up to date. # Create a local banch for changes fk@t520 ~/git/privoxy $git checkout -b local-branch Switched to a new branch 'local-branch' # Create some change fk@t520 ~/git/privoxy $gmake dok dok-tidy [...] # Review your change fk@t520 ~/git/privoxy $git diff [...] # Commit your changes if they look goood fk@t520 ~/git/privoxy $git commit -m "developer-manual: Regenerate" doc/webserver/ [local-branch 1abb7316] developer-manual: Regenerate 1 file changed, 2 insertions(+), 2 deletions(-) # Review your commit fk@t520 ~/git/privoxy $git show [...] # Go to the master branch fk@t520 ~/git/privoxy $git checkout master Switched to branch 'master' Your branch is up to date with 'origin/master'. # Make sure you are still in sync fk@t520 ~/git/privoxy $git pull [...] Already up to date. # Apply the commit you made to the local-branch fk@t520 ~/git/privoxy $git cherry-pick local-branch [master 046e85e2] developer-manual: Regenerate Date: Tue Dec 15 05:10:07 2020 +0100 1 file changed, 2 insertions(+), 2 deletions(-) # Make sure the history looks as expected fk@t520 ~/git/privoxy $git log -p # Finally push your change to the Privoxy repository fk@t520 ~/git/privoxy $git push [...] # Go back to the local branch fk@t520 ~/git/privoxy $git checkout local-branch # Rebase on top of master and continue hacking fk@t520 ~/git/privoxy $git rebase master Successfully rebased and updated refs/heads/local-branch. At one time there were two distinct branches: stable and unstable. The more drastic changes were to be in the unstable branch. These branches have now been merged to minimize time and effort of maintaining two branches. 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 expect anyone with Git access to strictly adhere to the following guidelines: Basic Guidelines, for all branches: Please don't commit even a small change without testing it thoroughly first. When we're close to a public release, ask a fellow developer to review your changes. Your commit message should give a concise overview of what you changed (no big details) and why you changed it Just check previous messages for good examples. Don't use the same message on multiple files, unless it equally applies to all those files. If your changes span multiple files, and the code won't recompile unless all changes are committed (e.g. when changing the signature of a function), then commit all files one after another, without long delays in between. If necessary, prepare the commit messages in advance. Before changing things on Git, make sure that your changes are in line 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 or the privoxy-devel mailing list instead. All formal documents are maintained in Docbook SGML and located in the doc/source/* directory. You will need Docbook, the Docbook DTD's and the Docbook modular stylesheets (or comparable alternatives), and either jade or openjade (recommended) installed in order to build docs from source. Currently there is user-manual, FAQ, and, of course this, the developer-manual in this format. The README, AUTHORS, INSTALL, privoxy.8 (man page), and config files are also now maintained as Docbook SGML. These files, when built, in the top-level source directory are generated files! Also, the Privoxy index.html (and a 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. config requires some special handling. The reason it is maintained this way is so that the extensive comments in the file mirror those in user-manual. 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. Other, less formal documents (e.g. LICENSE) are maintained as plain text files in the top-level source directory. Packagers are encouraged to include this documentation. For those without the ability to build the docs locally, text versions of each are kept in Git. HTML versions are also being kept in Git under doc/webserver/*. Formal documents are built with the Makefile targets of make dok. The build process uses the document SGML sources in doc/source/*/* to update all text files in doc/text/ and to update all HTML documents in doc/webserver/. Documentation writers should please make sure documents build successfully before committing to Git, if possible. How do you update the webserver (i.e. the pages on privoxy.org)? First, build the docs by running make dok dok-tidy. Run make webserver which copies all files from doc/webserver to the sourceforge webserver via ssh. Finished docs should be occasionally submitted to Git (doc/webserver/*/*.html) so that those without the ability to build them locally, have access to them if needed. This is especially important just prior to a new release! Please do this after the $VERSION and other release specific data in configure.in has been updated (this is done just prior to a new release). If you are not familiar with SGML, it is a markup language similar to HTML. Actually, not a mark up language per se, but a language used to define markup languages. In fact, HTML is an SGML application. Both will use tags to format text and other content. SGML tags can be much more varied, and flexible, but do much of the same kinds of things. The tags, or elements, are definable in SGML. There is no set standards. Since we are using Docbook, our tags are those that are defined by Docbook. Much of how the finish document is rendered is determined by the stylesheets. The stylesheets determine how each tag gets translated to HTML, or other formats. Tags in Docbook SGML need to be always closed. If not, you will likely generate errors. Example: <title>My Title</title>. They are also case-insensitive, but we strongly suggest using all lower case. This keeps compatibility with [Docbook] XML. Our documents use sections for the most part. Sections will be processed into HTML headers (e.g. h1 for sect1). The Docbook stylesheets will use these to also generate the Table of Contents for each doc. Our TOC's are set to a depth of three. Meaning sect1, sect2, and sect3 will have TOC entries, but sect4 will not. Each section requires a <title> element, and at least one <para>. There is a limit of five section levels in Docbook, but generally three should be sufficient for our purposes. Some common elements that you likely will use: <para></para>, paragraph delimiter. Most text needs to be within paragraph elements (there are some exceptions). <emphasis></emphasis>, the stylesheets make this italics. <filename></filename>, files and directories. <command></command>, command examples. <literallayout></literallayout>, like <pre>, more or less. <itemizedlist></itemizedlist>, list with bullets. <listitem></listitem>, member of the above. <screen></screen>, screen output, implies <literallayout>. <ulink url="example.com"></ulink>, like HTML <a> tag. <quote></quote>, for, doh, quoting text. Look at any of the existing docs for examples of all these and more. You might also find Writing Documentation Using DocBook - A Crash Course useful. It will be easier if everyone follows a similar writing style. This just makes it easier to read what someone else has written if it is all done in a similar fashion. Here it is: All tags should be lower case. Tags delimiting a block of text (even small blocks) should be on their own line. Like: <para> Some text goes here. </para> Tags marking individual words, or few words, should be in-line: Just to <emphasis>emphasize</emphasis>, some text goes here. Tags should be nested and step indented for block text like: (except in-line tags) <para> <itemizedlist> <para> <listitem> Some text goes here in our list example. </listitem> </para> </itemizedlist> </para> This makes it easier to find the text amongst the tags ;-) Use white space to separate logical divisions within a document, like between sections. Running everything together consistently makes it harder to read and work on. Do not hesitate to make comments. Comments can either use the <comment> element, or the <!-- --> style comment familiar from HTML. (Note in Docbook v4.x <comment> is replaced by <remark>.) We have an international audience. Refrain from slang, or English idiosyncrasies (too many to list :). Humor also does not translate well sometimes. Try to keep overall line lengths in source files to 80 characters or less for obvious reasons. This is not always possible, with lengthy URLs for instance. Our documents are available in differing formats. Right now, they are just plain text and/or HTML, but others are always a future possibility. Be careful with URLs (<ulink>), and avoid this mistake: My favorite site is <ulink url="http://example.com">here</ulink>. This will render as My favorite site is here, which is not real helpful in a text doc. Better like this: My favorite site is <ulink url="http://example.com">example.com</ulink>. All documents should be spell checked occasionally. aspell can check SGML with the -H option. (ispell I think too.) Privoxy documentation is using a number of customized entities to facilitate documentation maintenance. We are using a set of boilerplate files with generic text, that is used by multiple docs. This way we can write something once, and use it repeatedly without having to re-write the same content over and over again. If editing such a file, keep in mind that it should be generic. That is the purpose; so it can be used in varying contexts without additional modifications. We are also using what Docbook calls internal entities. These are like variables in programming. Well, sort of. For instance, we have the p-version entity that contains the current Privoxy version string. You are strongly encouraged to use these where possible. Some of these obviously require re-setting with each release (done by the Makefile). A sampling of custom entities are listed below. See any of the main docs for examples. Re- boilerplate text entities are defined like: <!entity supported SYSTEM "supported.sgml"> In this example, the contents of the file, supported.sgml is available for inclusion anywhere in the doc. To make this happen, just reference the now defined entity: &supported; (starts with an ampersand and ends with a semi-colon), and the contents will be dumped into the finished doc at that point. Commonly used internal entities: p-version: the Privoxy version string, e.g. &p-version;. 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). p-stable: just the opposite. p-text: this doc is only generated as text. There are others in various places that are defined for a specific purpose. Read the source! This set of standards is designed to make our lives easier. It is developed with the simple goal of helping us keep the "new and improved Privoxy" consistent and reliable. Thus making maintenance easier and increasing chances of success of the project. And that of course comes back to us as individuals. If we can increase our development and product efficiencies then we can solve more of the request for changes/improvements and in general feel good about ourselves. ;-> Explanation: Comment as much as possible without commenting the obvious. For example do not comment "variable_a is equal to variable_b". Instead explain why variable_a should be equal to the variable_b. Just because a person can read code does not mean they will understand why or what is being done. A reader may spend a lot more time figuring out what is going on when a simple comment or explanation would have prevented the extra research. Please help your fellow Privoxy developers out! The comments will also help justify the intent of the code. If the comment describes something different than what the code is doing then maybe a programming error is occurring. Example: /* if page size greater than 1k ... */ if (page_length() > 1024) { ... "block" the page up ... } /* if page size is small, send it in blocks */ if (page_length() > 1024) { ... "block" the page up ... } This demonstrates 2 cases of "what not to do". The first is a "syntax comment". The second is a comment that does not fit what is actually being done. Explanation: Comments can help or they can clutter. They help when they are differentiated from the code they describe. One line comments do not offer effective separation between the comment and the code. Block identifiers do, by surrounding the code with a clear, definable pattern. Example: /********************************************************************* * This will stand out clearly in your code! *********************************************************************/ if (this_variable == that_variable) { do_something_very_important(); } /* unfortunately, this may not */ if (this_variable == that_variable) { do_something_very_important(); } if (this_variable == that_variable) /* this may not either */ { do_something_very_important(); } Exception: If you are trying to add a small logic comment and do not wish to "disrupt" the flow of the code, feel free to use a 1 line comment which is NOT on the same line as the code. Explanation: It goes back to the question of readability. If the comment is on the same line as the code it will be harder to read than the comment that is on its own line. There are three exceptions to this rule, which should be violated freely and often: during the definition of variables, at the end of closing braces, when used to comment parameters. Example: /********************************************************************* * This will stand out clearly in your code, * But the second example won't. *********************************************************************/ if (this_variable == this_variable) { do_something_very_important(); } if (this_variable == this_variable) /*can you see me?*/ { do_something_very_important(); /*not easily*/ } /********************************************************************* * But, the encouraged exceptions: *********************************************************************/ int urls_read = 0; /* # of urls read + rejected */ int urls_rejected = 0; /* # of urls rejected */ if (1 == X) { do_something_very_important(); } short do_something_very_important( short firstparam, /* represents something */ short nextparam /* represents something else */ ) { ...code here... } /* -END- do_something_very_important */ Explanation: Logical steps should be commented to help others follow the intent of the written code and comments will make the code more readable. If you have 25 lines of code without a comment, you should probably go back into it to see where you forgot to put one. Most "for", "while", "do", etc... loops _probably_ need a comment. After all, these are usually major logic containers. Explanation: A reader of the code should be able to look at the comments just prior to the beginning of a function and discern the reason for its existence and the consequences of using it. The reader should not have to read through the code to determine if a given function is safe for a desired use. The proper information thoroughly presented at the introduction of a function not only saves time for subsequent maintenance or debugging, it more importantly aids in code reuse by allowing a user to determine the safety and applicability of any function for the problem at hand. As a result of such benefits, all functions should contain the information presented in the addendum section of this document. Explanation: Each closing brace should be followed on the same line by a comment that describes the origination of the brace if the original brace is off of the screen, or otherwise far away from the closing brace. This will simplify the debugging, maintenance, and readability of the code. As a suggestion , use the following flags to make the comment and its brace more readable: use following a closing brace: } /* -END- if() or while () or etc... */ Example: if (1 == X) { do_something_very_important(); ...some long list of commands... } /* -END- if x is 1 */ or: if (1 == X) { do_something_very_important(); ...some long list of commands... } /* -END- if (1 == X) */ Explanation: Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which are reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in case we ever decide to port Privoxy to C++. Example: int ms_iis5_hack = 0; Instead of: int msiis5hack = 0; int msIis5Hack = 0; Explanation: Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which are reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in case we ever decide to port Privoxy to C++. Example: int load_some_file(struct client_state *csp) Instead of: int loadsomefile(struct client_state *csp) int loadSomeFile(struct client_state *csp) Explanation: Use a descriptive parameter name in the function prototype in header files. Use the same parameter name in the header file that you use in the c file. Example: (.h) extern int load_aclfile(struct client_state *csp); (.c) int load_aclfile(struct client_state *csp) Instead of: (.h) extern int load_aclfile(struct client_state *); or (.h) extern int load_aclfile(); (.c) int load_aclfile(struct client_state *csp) Explanation: Use all capital letters, with underscores between words. Do not start an identifier with an underscore. (ANSI C reserves these for use by the compiler and system headers.) Example: (enumeration) : enum Boolean {FALSE, TRUE}; (#define) : #define DEFAULT_SIZE 100; Note: We have a standard naming scheme for #defines that toggle a feature in the preprocessor: FEATURE_>, where > is a short (preferably 1 or 2 word) description. Example: #define FEATURE_FORCE 1 #ifdef FEATURE_FORCE #define FORCE_PREFIX blah #endif /* def FEATURE_FORCE */ Explanation: Spell common words out entirely (do not remove vowels). Use only widely-known domain acronyms and abbreviations. Capitalize all letters of an acronym. Use underscore (_) to separate adjacent acronyms and abbreviations. Never terminate a name with an underscore. Example: #define USE_IMAGE_LIST 1 Instead of: #define USE_IMG_LST 1 or #define _USE_IMAGE_LIST 1 or #define USE_IMAGE_LIST_ 1 or #define use_image_list 1 or #define UseImageList 1 Explanation: The brace needs to be on a line all by itself, not at the end of the statement. Curly braces should line up with the construct that they're associated with. This practice makes it easier to identify the opening and closing braces for a block. Example: if (this == that) { ... } Instead of: if (this == that) { ... } or if (this == that) { ... } Note: In the special case that the if-statement is inside a loop, and it is trivial, i.e. it tests for a condition that is obvious from the purpose of the block, one-liners as above may optically preserve the loop structure and make it easier to read. Status: developer-discretion. Example exception: while (more lines are read) { /* Please document what is/is not a comment line here */ if (it's a comment) continue; do_something(line); } Explanation: Using braces to make a block will make your code more readable and less prone to error. All control statements should have a block defined. Example: if (this == that) { do_something(); do_something_else(); } Instead of: if (this == that) do_something(); do_something_else(); or if (this == that) do_something(); Note: The first example in "Instead of" will execute in a manner other than that which the developer desired (per indentation). Using code braces would have prevented this "feature". The "explanation" and "exception" from the point above also applies. Example: structure->flag = (condition); Instead of: if (condition) { structure->flag = 1; } else { structure->flag = 0; } Note: The former is readable and concise. The later is wordy and inefficient. Please assume that any developer new to the project has at least a "good" knowledge of C/C++. (Hope I do not offend by that last comment ... 8-) Explanation: Make it readable. The notable exception to using white space freely is listed in the next guideline. Example: int first_value = 0; int some_value = 0; int another_value = 0; int this_variable = 0; Explanation: - structure pointer operator ( "->" ) - member operator ( "." ) - functions and parentheses It is a general coding practice to put pointers, references, and function parentheses next to names. With spaces, the connection between the object and variable/function name is not as clear. Example: a_struct->a_member; a_struct.a_member; function_name(); Instead of: a_struct -> a_member; a_struct . a_member; function_name (); Example: int function1( ... ) { ...code... return(ret_code); } /* -END- function1 */ int function2( ... ) { } /* -END- function2 */ Instead of: int function1( ... ) { ...code... return(ret_code); } int function2( ... ) { } Note: Use 1 blank line before the closing brace and 2 lines afterward. This makes the end of function standout to the most casual viewer. Although function comments help separate functions, this is still a good coding practice. In fact, I follow these rules when using blocks in "for", "while", "do" loops, and long if {} statements too. After all whitespace is free! Status: developer-discretion on the number of blank lines. Enforced is the end of function comments. Explanation: If some use 8 character TABs and some use 3 character TABs, the code can look *very* ragged. So use 3 character indentions only. If you like to use TABs, pass your code through a filter such as "expand -t3" before checking in your code. Example: static const char * const url_code_map[256] = { NULL, ... }; int function1( ... ) { if (1) { return ALWAYS_TRUE; } else { return HOW_DID_YOU_GET_HERE; } return NEVER_GETS_HERE; } Explanation: Do not assume that the variables declared will not be used until after they have been assigned a value somewhere else in the code. Remove the chance of accidentally using an unassigned variable. Example: short a_short = 0; float a_float = 0; struct *ptr = NULL; Note: It is much easier to debug a SIGSEGV if the message says you are trying to access memory address 00000000 and not 129FA012; or array_ptr[20] causes a SIGSEV vs. array_ptr[0]. Status: developer-discretion if and only if the variable is assigned a value "shortly after" declaration. Explanation: Value should be phrased as a question that would logically be answered as a true or false statement Example: should_we_block_this(); contains_an_image(); is_web_page_blank(); Explanation: The default return for a function is an int. To avoid ambiguity, create a return for a function when the return has a purpose, and create a void return type if the function does not need to return anything. Explanation: It is easy to write the following code, and a clear argument can be made that the code is easy to understand: Example: for (size_t cnt = 0; cnt < block_list_length(); cnt++) { .... } Note: Unfortunately, this makes a function call for each and every iteration. This increases the overhead in the program, because the compiler has to look up the function each time, call it, and return a value. Depending on what occurs in the block_list_length() call, it might even be creating and destroying structures with each iteration, even though in each case it is comparing "cnt" to the same value, over and over. Remember too - even a call to block_list_length() is a function call, with the same overhead. Instead of using a function call during the iterations, assign the value to a variable, and evaluate using the variable. Example: size_t len = block_list_length(); for (size_t cnt = 0; cnt < len; cnt++) { .... } Exceptions: if the value of block_list_length() *may* change or could *potentially* change, then you must code the function call in the for/while loop. Explanation: This allows a developer to define a const pointer and call your function. If your function does not have the const keyword, we may not be able to use your function. Consider strcmp, if it were defined as: extern int strcmp(char *s1, char *s2); I could then not use it to compare argv's in main: int main(int argc, const char *argv[]) { strcmp(argv[0], "privoxy"); } Both these pointers are *const*! If the c runtime library maintainers do it, we should too. Explanation: Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes or less). Aka, a function declaration like: int load_aclfile(struct client_state csp) would not work. So, to be consistent, we should declare all prototypes with "pass by value": int load_aclfile(struct client_state *csp) Explanation: Your include statements should contain the file name without a path. The path should be listed in the Makefile, using -I as processor directive to search the indicated paths. An exception to this would be for some proprietary software that utilizes a partial path to distinguish their header files from system or other header files. Example: #include <iostream.h> /* This is not a local include */ #include "config.h" /* This IS a local include */ Exception: /* This is not a local include, but requires a path element. */ #include <sys/fileName.h> Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include "file.h" behavior. Explanation: Prevents compiler and linker errors resulting from redefinition of items. Wrap each header file with the following syntax to prevent multiple inclusions of the file. Of course, replace PROJECT_H with your file name, with "." Changed to "_", and make it uppercase. Example: #ifndef PROJECT_H_INCLUDED #define PROJECT_H_INCLUDED ... #endif /* ndef PROJECT_H_INCLUDED */ Explanation: If our headers are included from C++, they must declare our functions as `extern "C"`. This has no cost in C, but increases the potential re-usability of our code. Example: #ifdef __cplusplus extern "C" { #endif /* def __cplusplus */ ... function definitions here ... #ifdef __cplusplus } #endif /* def __cplusplus */ Explanation: Useful in headers that include pointers to other struct's. Modifications to excess header files may cause needless compiles. Example: /********************************************************************* * We're avoiding an include statement here! *********************************************************************/ struct file_list; extern file_list *xyz; Note: If you declare "file_list xyz;" (without the pointer), then including the proper header file is necessary. If you only want to prototype a pointer, however, the header file is unnecessary. Status: Use with discretion. Explanation Compiler warnings are meant to help you find bugs. You should turn on as many as possible. With GCC, the switch is "-Wall". Try and fix as many warnings as possible. Explanation: What you think is guaranteed is never really guaranteed. The value that you don't think you need to check is the one that someday will be passed. So, to protect yourself from the unknown, always have a default step in a switch statement. Example: switch (hash_string(cmd)) { case hash_actions_file: ... code ... break; case hash_confdir: ... code ... break; default: log_error( ... ); ... anomaly code goes here ... continue; / break; / exit( 1 ); / etc ... } /* end switch (hash_string(cmd)) */ Note: If you already have a default condition, you are obviously exempt from this point. Of note, most of the WIN32 code calls `DefWindowProc' after the switch statement. This API call *should* be included in a default statement. Another Note: This is not so much a readability issue as a robust programming issue. The "anomaly code goes here" may be no more than a print to the STDERR stream (as in load_config). Or it may really be an abort condition. Status: Programmer discretion is advised. Explanation: In general, you will want to have a 'break' statement within each 'case' of a switch statement. This allows for the code to be more readable and understandable, and furthermore can prevent unwanted surprises if someone else later gets creative and moves the code around. The language allows you to plan the fall through from one case statement to another simply by omitting the break statement within the case statement. This feature does have benefits, but should only be used in rare cases. In general, use a break statement for each case statement. If you choose to allow fall through, you should comment both the fact of the fall through and reason why you felt it was necessary. Explanation: The type of size_t varies across platforms. Do not make assumptions about whether it is signed or unsigned, or about how long it is. Do not compare a size_t against another variable of a different type (or even against a constant) without casting one of the values. Explanation: It can be tempting to declare a series of variables all on one line. Don't. Example: long a = 0; long b = 0; long c = 0; Instead of: long a, b, c; Explanation: - there is more room for comments on the individual variables - easier to add new variables without messing up the original ones - when searching on a variable to find its type, there is less clutter to "visually" eliminate Exceptions: when you want to declare a bunch of loop variables or other trivial variables; feel free to declare them on one line. You should, although, provide a good comment on their functions. Status: developer-discretion. Explanation: Create a local struct (on the stack) if the variable will live and die within the context of one function call. Only "malloc" a struct (on the heap) if the variable's life will extend beyond the context of one function call. Example: If a function creates a struct and stores a pointer to it in a list, then it should definitely be allocated via `malloc'. Explanation: If you have to "malloc" an instance, you are responsible for insuring that the instance is `free'd, even if the deallocation event falls within some other programmer's code. You are also responsible for ensuring that deletion is timely (i.e. not too soon, not too late). This is known as "low-coupling" and is a "good thing (tm)". You may need to offer a free/unload/destructor type function to accommodate this. Example: int load_re_filterfile(struct client_state *csp) { ... } static void unload_re_filterfile(void *f) { ... } Exceptions: The developer cannot be expected to provide `free'ing functions for C run-time library functions ... such as `strdup'. Status: developer-discretion. The "main" use of this standard is for allocating and freeing data structures (complex or nested). Explanation: I have ordered all of the "blocker" file code to be in alpha order. It is easier to add/read new blockers when you expect a certain order. Note: It may appear that the alpha order is broken in places by POPUP tests coming before PCRS tests. But since POPUPs can also be referred to as KILLPOPUPs, it is clear that it should come first. Explanation: If you have enough confidence in new code or confidence in your changes, but are not *quite* sure of the repercussions, add this: /* XXX: this code has a logic error on platform XYZ, * attempting to fix */ #ifdef PLATFORM ...changed code here... #endif or: /* XXX: I think the original author really meant this... */ ...changed code here... or: /* XXX: new code that *may* break something else... */ ...new code here... Note: If you make it clear that this may or may not be a "good thing (tm)", it will be easier to identify and include in the project (or conversely exclude from the project). Example for file comments: /********************************************************************* * * File : $Source * * Purpose : (Fill me in with a good description!) * * Copyright : Written by and Copyright (C) 2001-2009 * the Privoxy team. https://www.privoxy.org/ * * 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/licenses/old-licenses/gpl-2.0.html * or write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , * USA * *********************************************************************/ #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-version" page. If this is a brand new creation by you, you are free to change the "Copyright" section to represent the rights you wish to maintain. Note: The formfeed character that is present right after the comment flower box is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of the code (via `forward-page' and `backward-page'). Please include it if you can. Example for file header comments: #ifndef _FILENAME_H #define _FILENAME_H /********************************************************************* * * File : $Source * * Purpose : (Fill me in with a good description!) * * Copyright : Written by and Copyright (C) 2001-2009 * the Privoxy team. https://www.privoxy.org/ * * 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/licenses/old-licenses/gpl-2.0.html * or write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , * USA * *********************************************************************/ #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: /********************************************************************* * * Function : FUNCTION_NAME * * Description : (Fill me in with a good description!) * * parameters : * 1 : param1 = pointer to an important thing * 2 : x = pointer to something else * * Returns : 0 => Ok, everything else is an error. * *********************************************************************/ int FUNCTION_NAME(void *param1, const char *x) { ... return 0; } Note: If we all follow this practice, we should be able to parse our code to create a "self-documenting" web page. To be filled. Explain release numbers. major, minor. developer releases. etc. Remove any existing rpm with rpm -e Remove any file that was left over. This includes (but is not limited to) /var/log/privoxy /etc/privoxy /usr/sbin/privoxy /etc/init.d/privoxy /usr/doc/privoxy* Install the rpm. Any error messages? start,stop,status Privoxy with the specific script (e.g. /etc/rc.d/init/privoxy stop). Reboot your machine. Does autostart work? Start browsing. Does Privoxy work? Logfile written? Remove the rpm. Any error messages? All files removed? If you compiled, packaged or merely installed Privoxy, it is recommended to run Privoxy-Regression-Test to verify that at least the tested parts of Privoxy are working as expected. This is actually pretty easy. For details, please see perldoc privoxy-regression-test.pl. Here is an example of what Privoxy-Regression-Test can do for you: # Run all the tests fk@t520 ~ $privoxy-regression-test.pl 2020-12-14 12:16:32: Asking Privoxy for the number of action files available ... 2020-12-14 12:16:32: Gathering regression tests from 9 action file(s) delivered by Privoxy 3.0.30. 2020-12-14 12:16:32: Executing regression tests ... 2020-12-14 12:16:41: Ooops. Expected removal but: 'Referer: https://p.p/' is still there. 2020-12-14 12:16:41: Failure for test 785. Header 'Referer: https://p.p/' and tag 'hide-referrer{conditional-block}' 2020-12-14 12:16:41: Ooops. Got: 'Referer: https://p.p/' while expecting: 'Referer: http://p.p/' 2020-12-14 12:16:41: Failure for test 791. Header 'Referer: https://p.p/' and tag 'hide-referrer{conditional-forge}' 2020-12-14 12:16:44: Executed 1087 regression tests. Skipped 115. 1085 successes, 2 failures. # Repeat one of the failing tests and get a curl command to quickly reproduce the problem # without causing too much log noise. fk@t520 ~ $privoxy-regression-test.pl --test-number 785 --verbose --debug 4 2020-12-14 12:17:55: Asking Privoxy for the number of action files available ... [...] 2020-12-14 12:17:56: Executing regression tests ... 2020-12-14 12:17:56: Executing: curl --include -H 'Proxy-Connection:' -H 'Connection: close' -s -S --user-agent 'Privoxy-Regression-Test 0.7.2' --max-time '5' --globoff -H 'X-Privoxy-Control: hide-referrer{conditional-block}' -H 'Referer: https://p.p/' http://p.p/show-request 2>&1 2020-12-14 12:17:56: Ooops. Expected removal but: 'Referer: https://p.p/' is still there. 2020-12-14 12:17:56: Failure for test 785 (0/13/5). Header 'Referer: https://p.p/' and tag 'hide-referrer{conditional-block}' 2020-12-14 12:17:56: Executed 1 regression tests. Skipped 1201. 0 successes, 1 failures. Use the if the --privoxy-address option if the http_proxy environment variable isn't configured and you don't want to use the default (http://127.0.0.1:8118/). To make fuzzing more convenient, Privoxy can be configured with --enable-fuzz which will result in the --fuzz option becoming available. Example (tested on ElectroBSD): # Compile Privoxy with instrumentation for afl $ export CC=afl-clang $ export CFLAGS="-fsanitize=address -ggdb" $ export CPPFLAGS=-I/usr/local/include/ $ export LDFLAGS="-fsanitize=address -L/usr/local/lib" $ export AFL_USE_ASAN=1 $ export AFL_HARDEN=1 $ ./configure --with-debug --enable-extended-host-patterns --enable-accept-filter --enable-no-gifs --enable-compression --enable-strptime-sanity-checks --enable-external-filters --enable-fuzz $ ./privoxy --fuzz Privoxy version 3.0.24 (http://www.privoxy.org/) Usage: ./privoxy [--config-test] [--chroot] [--help] [--no-daemon] [--pidfile pidfile] [--pre-chroot-nslookup hostname] [--user user[.group]] [--version] [configfile] ./privoxy --fuzz fuzz-mode ./path/to/fuzzed/input [--stfu] Supported fuzz modes and the expected input: action: Text to parse as action file. client-request: Client request to parse. Currently incomplete client-header: Client header to parse. chunked-transfer-encoding: Chunk-encoded data to dechunk. deflate: deflate-compressed data to decompress. filter: Text to parse as filter file. gif: gif to deanimate. gzip: gzip-compressed data to decompress. pcrs-substitute: A pcrs-substitute to compile. Not a whole pcrs job! Example: Bla $1 bla C $3 blah. server-header: Server header to parse. server-response: Server response to parse. The following fuzz modes read data from stdin if the 'file' is '-' client-request client-header chunked-transfer-encoding deflate gif gzip pcrs-substitute server-header server-response Aborting $ export ASAN_OPTIONS='abort_on_error=1' $ mkdir input output $ echo '$1 bla fasel $2' > input/pcrs $ afl-fuzz -i input -o output -m none ~/git/privoxy/privoxy --fuzz pcrs-substitute - --stfu $ cat >input/pcrs.txt FILTER: bla fasel s@(.{1})[432](\d+)@$1$2$hostname@UgisT $ afl-fuzz -i input/ -o output/ -f bla.filter -m none privoxy --fuzz filter bla.filter --stfu When we release versions of Privoxy, our work leaves our cozy secret lab and has to work in the cold RealWorld[tm]. Once it is released, there is no way to call it back, so it is very important that great care is taken to ensure that everything runs fine, and not to introduce problems in the very last minute. So when releasing a new version, please adhere exactly to the procedure outlined in this chapter. The following programs are required to follow this process: ssh, gmake (GNU's version of make), autoconf, git, a web browser. 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: X, the version major, is rarely ever changed. It is increased by one if turning a development branch into stable substantially changes the functionality, user interface or configuration syntax. Majors 1 and 2 were Junkbuster, and 3 is the first stable Privoxy release. Y, the version minor, represents the branch within the major version. At any point in time, there are two branches being maintained: The stable branch, with an even minor, say, 2N, in which no functionality is being added and only bug-fixes are made, and 2N+1, the development branch, in which the further development of Privoxy takes place. This enables us to turn the code upside down and inside out, while at the same time providing and maintaining a stable version. The minor is reset to zero (and one) when the major is incremented. When a development branch has matured to the point where it can be turned into stable, the old stable branch 2N is given up (i.e. no longer maintained), the former development branch 2N+1 becomes the new stable branch 2N+2, and a new development branch 2N+3 is opened. Z, the point or sub version, represents a release of the software within a branch. It is therefore incremented immediately after each software release. 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 Git 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 Git. 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). The following must be done by one of the developers prior to each new release. Make sure that everybody who has worked on the code in the last couple of days has had a chance to yell no! in case they have pending changes/fixes in their pipelines. Announce the freeze so that nobody will interfere with last minute changes. Update the code status (CODE_STATUS="xxx") in configure.in to one of "alpha", "beta" or "stable". Rebuild configure and GNUMakefile to make sure the updated values are being used. $ autoheader && autoconf # rebuild configure $ ./configure # rebuild GNUmakefile make dok-release to update the sgml documentation source files. If action file processing has changed and is not backward-compatible, make sure the "for-privoxy-version=x.y.z" minimum version number in default.action.master has been updated: {{settings}} ############################################################################# #MASTER# COMMENT: The minimum Privoxy version: for-privoxy-version=3.0.11 Create the change log: $ git tag # to see the tags $ git log [last release tag]..master > /tmp/log # get the commit log since the last release $ utils/makeChangeLog /tmp/log > /tmp/change.log # reformat the commit log Edit /tmp/change.log to remove trivial changes and group the changes under general headings like: - Bug fixes: - Action file improvements: - Filter file improvements: - General improvements: - Documentation improvements: - Build system improvements: - Code cleanups: - Privoxy-Log-Parser: - Privoxy-Regression-Test: Add the contents of /tmp/change.log to the start of ChangeLog and re-create doc/source/changelog.sgml: $ utils/changelog2doc.pl /tmp/change.log >| doc/source/changelog.sgml All developers should look at the ChangeLog and make sure noteworthy changes are referenced. Update the announcement at doc/webserver/announce.txt. All documentation should be rebuilt: $ make man $ make dok $ make dok-man $ make dok-tidy $ make config-file Finished docs should be then be committed to Git (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) fall in this category. README, the man page, AUTHORS, and config should all also be committed to Git for other packagers. The formal docs should be uploaded to the webserver. See the section "Updating the webserver" in this manual for details. Commit all files that were changed in the above steps! 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 https://www.privoxy.org/$(VERSION)/user-manual/. This needs to be updated for each new release and is done with the webserver target. Tag all files in Git with the version number with git tag -s v_X_Y_Z. Don't use vX_Y_Z, ver_X_Y_Z, v_X.Y.Z (won't work) etc. Push the tag to the remote with git push origin v_X_Y_Z. On the webserver, copy the user manual to a new top-level directory called X.Y.Z. This ensures that help links from the CGI pages, which have the version as a prefix, will go into the right version of the manual. If this is a development branch release, also symlink X.Y.(Z-1) to X.Y.Z and X.Y.(Z+1) to . (i.e. dot). Now the individual packages can be built and released. Note that for GPL reasons the first package to be released is always the source tarball. 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 Git into an empty directory (just press return when asked for a password): mkdir dist # delete or choose different name if it already exists cd dist git clone https://www.privoxy.org/git/privoxy.git cd privoxy git checkout v_X_Y_Z Do NOT change a single bit, including, but not limited to version information after export from Git. This is to make sure that all release packages, and with them, all future bug reports, are based on exactly the same code. Every significant release of Privoxy has included at least one package that either had incorrect versions of files, missing files, or incidental leftovers from a previous build process that gave unknown numbers of users headaches to try to figure out what was wrong. PLEASE, make sure you are using pristene sources, and are following the prescribed process! Please find additional instructions for the source tarball and the individual platform dependent binary packages below. And details on the Sourceforge release process below that. Please keep these general guidelines in mind when putting together your package. These apply to all platforms! Privoxy requires write access to: all *.action files, all logfiles, and the trust file. You will need to determine the best way to do this for your platform. Please include up to date documentation. At a bare minimum: LICENSE (top-level directory) README (top-level directory) AUTHORS (top-level directory) man page (top-level directory, Unix-like platforms only) The User Manual (doc/webserver/user-manual/) FAQ (doc/webserver/faq/) Also suggested: Developer Manual (doc/webserver/developer-manual) and ChangeLog (top-level directory). FAQ and the manuals are HTML docs. The documentation has been designed such that the manuals are linked to each other from parallel directories, and should be packaged that way. privoxy-index.html can also be included and can serve as a focal point for docs and other links of interest (and possibly renamed to index.html). This should be one level up from the manuals. There is a link also on this page to an HTMLized version of the man page. To avoid 404 for this, it is in Git as doc/webserver/man-page/privoxy-man-page.html, and should be included along with the manuals. There is also a css stylesheets that can be included for better presentation: p_doc.css. This should be in the same directory with privoxy-index.html, (i.e. one level up from the manual directories). user.action and user.filter are designed for local preferences. Make sure these do not get overwritten! config should not be overwritten either. This has especially important configuration data in it. trust should be left in tact as well. Other configuration files (default.action, regression-tests.action and default.filter) should be installed as the new defaults, but all previously installed configuration files should be preserved as backups. This is just good manners :-) These files are likely to change between releases and contain important new features and bug fixes. Please check platform specific notes in this doc, if you haven't done Privoxy packaging before for other platform specific issues. Conversely, please add any notes that you know are important for your platform (or contact one of the doc 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. First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). Then run from that directory: autoheader && autoconf && ./configure Then do: make tarball-dist Note that the docbook generated files might need some hand editing, so the Windows build makefile does not rebuild the docs. First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). Check that you have the current versions of the NSIS installer, PCRE library, MBED TLS library, Brotli library, and that the MAKENSIS evar in windows/GNUMakefile points to the NSIS installer program. (See the Building from Source / Windows section of the User Manual for details.) Then you can build the package. This is fully automated, and is controlled by windows/GNUmakefile. All you need to do is: cd windows make Now you can manually rename privoxy_setup.exe to privoxy_setup_X.Y.Z.exe, and the build directory to privoxy_X.Y.Z. Create a .zip file of the newly renamed privoxy_X.Y.Z directory, GPG sign the installer and zip file, gpg --armor --detach --sign privoxy_setup_X.Y.Z.exe gpg --armor --detach --sign privoxy_X.Y.Z.zip and upload the files to SourceForge. When releasing the package on SourceForge, use the release notes and Change Log from the source tarball package. Using git-buildpackage we start with a clone of the last Debian version: gbp clone https://salsa.debian.org/debian/privoxy.git cd privoxy or if the repository is already there cd privoxy gbp pull Now import the newly released upstream tarball via debian/watch file: gbp import-orig --uscan Next update all Debian quilt patches to the new version: while quilt push; do quilt refresh; done If some patch is no longer required (because it is already merged upstream), it can be removed using quilt delete XX_patchname.patch git rm debian/patches/XX_patchname.patch If the patch needs modification, you can apply, edit and update it with quilt push -f quilt edit some_file quilt refresh until while quilt push; do quilt refresh; done succeeds. Then you can quilt pop -a Now add a new entry to the debian/changelog representing the new version: dch -v &p-version;-1 and describe what you did before and don't forget to git commit all changes. Now you can build the package on the local machine using gbp buildpackage -us -uc You should check for warnings using lintian -iI ../build-area/privoxy_&p-version;-1_amd64.changes Maybe rebuild the package in different defined cowbuilder environments like sudo cowbuilder --build --basepath /var/cache/pbuilder/base.cow ../build-area/privoxy_&p-version;-1.dsc And try to run autopackage testing suite on the result: autopkgtest /var/cache/pbuilder/result/privoxy_&p-version;-1_amd64.changes -s -- schroot sid Or just push the changes to salsa.debian.org, where a CI pipeline is defined for the package, that builds and tests it. If everything is okay, run cowbuilder with i386 and amd64 environments for current Debian stable release and build privoxy_&p-version;-1_i386.deb and privoxy_&p-version;-1_amd64.deb. Then sign both files: gpg --detach-sign --armor privoxy_&p-version;-1_i386.deb gpg --detach-sign --armor privoxy_&p-version;-1_amd64.deb Create a README file containing the recent block from debian/changelog and upload the two packages, the two signatures and the README to a freshly created folder below https://sourceforge.net/projects/ijbswa/files/Debian/ For building just a git snapshot build the following workflow may be useful. First create a build environment, for this you may have to run the following commands: sudo apt install build-essential devscripts sudo apt-get build-dep privoxy After this enter the checked out privoxy git tree and check that all (new) build dependencies are met: dpkg-checkbuilddeps If something is missing, just add it using sudo apt install foobar Now you may update debian/changelog, especially the version number using dch and finally build the package: debuild -us -uc -b If everything went okay, you may find the resulting Debian package in the parent directory. You may want to clean up the build tree using debian/rules clean And maybe repair some artefacts using one or both of the following commands: git reset --hard git clean -fd First, make sure that you have freshly exported the right version into an empty directory. (See "Building and releasing packages" above). The OSXPackageBuilder module can generate OS X installer packages supporting all Macs running OS X 10.4 and above. Obtain it from Git as follows into a folder parallel to the exported privoxy source: git clone ssh://git@git.privoxy.org:23/git/OSXPackageBuilder.git The module contains complete instructions on its usage in the file OS X Package Builder HOWTO.txt. Once the package(s) have been generated, you can then upload them directly to the Files section of the Sourceforge project in the Macintosh (OS X) folder. Each new version release of Privoxy should have a new subfolder created in which to store its files. Please ensure that the folder contains a readme file that makes it clear which package is for which version of OS X. Update the www/privoxy port and submit a diff upstream. For details see the FreeBSD Porter's Handbook. After the package is ready, it is time to upload it and go through the release steps. The upload is done at SourceForge after logging in. 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 Release. Check the appropriate box(es). Remember at each step to hit the Refresh/Submit buttons! You should now see your file(s) listed in Step 3. Fill out the forms with the appropriate information for your platform, being sure to hit Update for each file. If anyone is monitoring your platform, check the email box at the very bottom to notify them of the new package. This should do it! If you have made errors, or need to make changes, you can go through essentially the same steps, but select Edit Release, instead of Add Release. When all (or: most of the) packages have been uploaded and made available, send an email to the announce mailing list, Subject: "Announcing Privoxy X.Y.Z $CODE_STATUS". Be sure to include the download 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). Other news sites and release oriented sites, such as Freshmeat, should also be notified. Then update the source code for the next version to be released: Increment the version number and change the code status to "UNRELEASED" in configure.in Rebuild configure (autoheader && autoconf) and GNUMakefile (./configure) make dok-release to update the sgml documentation source files. Commit all your changes. 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 stable-branch documentation source SGML files, do: make dok && make dok-tidy That will generate doc/webserver/user-manual, doc/webserver/developer-manual, doc/webserver/faq, doc/webserver/index.html automatically. 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 [now in Git, but not well tested]. See comments in GNUmakefile.) If you want to add new files to the webserver, create them locally in the doc/webserver/* directory (or create new directories under doc/webserver). Next, commit any changes from the above steps to Git. All set? If these are docs in the stable branch, then do: make webserver This will do the upload to the SourceForge webserver (which is manually syncronized with www.privoxy.org) and ensure all files and directories there are group writable. Please do NOT use any other means of transferring 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.