POPFile Developer's Guide

Trace:

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
developersguide [2007/01/24 09:32] – mannidevelopersguide [2008/07/11 14:43] (current) – external edit 127.0.0.1
Line 1: Line 1:
 ====== POPFile Developer's Guide ======  ====== POPFile Developer's Guide ====== 
  
-=== 1. How do I become a POPFile developer? ===+==== 1. How do I become a POPFile developer? ====
  
 If you are interested in developing code for POPFile then you came to the If you are interested in developing code for POPFile then you came to the
Line 7: Line 7:
 understand it. understand it.
  
-Then go to the [Bleeding Edge - Source Code] [[http://sourceforge.net/forum/forum.php?forum_id=230652| forum]] on the POPFile page on SourceForge and post a message saying that you are interested in writing +Then go to the [[/discussion/3|Bleeding Edge - Source Code forum]] on the POPFile page and post a message saying that you are interested in writing some code and making a suggestion.  You'll get honest feedback on the idea. This is very important because you don't want to waste your time coding something that someone else is working on.  It's also a good idea to find out whether I think your idea is good otherwise you might end up coding something that gets rejected, but most likely you'll get  encouragement and suggestions from other POPFile developers and a "show me" response from me.
-some code and making a suggestion.  You'll get honest feedback on the idea. +
-This is very important because you don't want to waste your time coding +
-something that someone else is working on.  It's also a good idea to find +
-out whether I think your idea is good otherwise you might end up coding +
-something that gets rejected, but most likely you'll get encouragement and +
-suggestions from other POPFile developers and a "show me" response from me.+
  
-It is important to realize that one thing I really care about in the code +It is important to realize that one thing I really care about in the code base is the quality of the code itself.  That means taking the time to understand the POPFile coding style and how to write POPFile tests is very important.  Changes to POPFile that are untested or don't meet the coding style will be rejected.
-base is the quality of the code itself.  That means taking the time to +
-understand the POPFile coding style and how to write POPFile tests is very +
-important.  Changes to POPFile that are untested or don't meet the coding +
-style will be rejected.+
  
 You will also need to sign a POPFile License Agreement, see below. You will also need to sign a POPFile License Agreement, see below.
  
 +==== 2. How do I post a patch? ====
  
-=== 2. How do I post a patch? ===+First read this entire document, then create a patch using [[devel:tools1| diff3]] (or a similar program) and [[/newticket|create a new ticket]] and attach the patch. Make sure that your patch meets the coding standard and has associated unit tests (unless it's really, really, really simple).
  
-First read this entire document, then create a patch using [[:tools | diff3]] (or a +Before you post your patch it's a good idea if you run the POPFile test suite against your version of the code to make sure you didn't break anything else.  Posting a patch that meets the coding standard, has its own tests and passes the full POPFile test suite is the best way to get on my good side, get your code in SVN and one day maybe get SVN access for yourself.
-similar program) and post it to the [[http://sourceforge.net/tracker/?group_id=63137&atid=502958| Patches database]] on SourceForge. Make sure that your patch meets the coding standard and has associated unit tests (unless it's really, really, really simple).+
  
-Before you post your patch it's a good idea if you run the POPFile test +==== 3. How do I get SVN commit access? ====
-suite against your version of the code to make sure you didn't break +
-anything else.  Posting a patch that meets the coding standard, has its own +
-tests and passes the full POPFile test suite is the best way to get on my +
-good side, get your code in CVS and one day maybe get CVS access for +
-yourself.+
  
 +Contact the project Core Team member (Brian, Joseph, Manni and Naoki).  You'll get SVN access if you consistently deliver great patches and come join in with the other developers in the [Bleeding Edge - Source Code] forum, follow the coding guidelines, write good tests and, even better, take direction from me on changes that I want to change in POPFile.
  
-=== 3. How do I get CVS commit access? === +==== 4. Does POPFile have a coding style? ====
- +
-Contact the project owner, John Graham-Cumming, [email protected].  You'll get CVS access if you consistently deliver great patches and come join in with the other developers in the +
-[Bleeding Edge - Source Code] forum, follow the coding guidelines, write good tests and, even better, take direction from me on changes that I want to change in POPFile. +
- +
- +
-=== 4. Does POPFile have a coding style? ===+
  
 Yes, and here it is (note that not all of the POPFile source code matches this coding style... yet... if you see something that needs cleaning up then clean it up!). Yes, and here it is (note that not all of the POPFile source code matches this coding style... yet... if you see something that needs cleaning up then clean it up!).
Line 49: Line 29:
 POPFile has a coding style so that all the code looks consistent and to make it easy for others to read and understand.  POPFile's coding standard may not be the one you prefer.  Too bad!  Individual style is one thing; but getting a single consistent style over multiple developers is vital to keeping the code clean. POPFile has a coding style so that all the code looks consistent and to make it easy for others to read and understand.  POPFile's coding standard may not be the one you prefer.  Too bad!  Individual style is one thing; but getting a single consistent style over multiple developers is vital to keeping the code clean.
  
---- Don't obfuscate your Perl.  Perl is a great language for writing cross +  * Don't obfuscate your Perl. Perl is a great language for writing cross platform code, but it is easy to be obscure and there's no excuse.  So 
-platform code, but it is easy to be obscure and there's no excuse.  So +minimize your use of implicit variables and imagine that a new Perl programmer is trying to decipher what you have written. 
-minimize your use of implicit variables and imagine that a new Perl +  * No TAB characters in files, and use 4 space indentation.  No carriage return characters in files. 
-programmer is trying to decipher what you have written. +  * { goes at the beginning of a new line after a sub declaration but at the end of the line in all other cases. <code perl>
- +
---- No TAB characters in files, and use 4 space indentation.  No carriage +
-return characters in files. +
- +
---- { goes at the beginning of a new line after a sub declaration but at the +
-end of the line in all other cases. +
- +
-<code>+
 sub foo sub foo
 { {
Line 69: Line 41:
 </code> </code>
  
---- Leave blank lines above and below blocks of comments, even when the +  * Leave blank lines above and below blocks of comments, even when the comments are small. <code perl>
-comments are small.+
  
-<code> +# Check whether the elephant feeding module is loaded and load it 
-  - Check whether the elephant feeding module is loaded and load it +# if necessary
-  - if necessary+
  
 if ( $efm->loaded() ) { if ( $efm->loaded() ) {
 </code> </code>
  
----  Every module or file must have a file header that states the name of +  *  Every module or file must have a file header that states the name of the code and the purpose of the code in the file and the standard copyright notice as follows: <code perl> 
-the code and the purpose of the code in the file and the standard copyright +#--------------------------------------------------------------------------- 
-notice as follows: +# 
- +# Module.pm --- A module that handles the loading of banana wumpus drivers 
-<code> +#               and links them into the octopus subsystem using dinolinking 
-  ---------------------------------------------------------------------------- +# 
-  - +# Copyright (c) 2001-2003 John Graham-Cumming 
-  - Module.pm --- A module that handles the loading of banana wumpus drivers +# 
-  -               and links them into the octopus subsystem using dinolinking +#---------------------------------------------------------------------------
-  - +
-  - Copyright (c) 2001-2003 John Graham-Cumming +
-  - +
-  ----------------------------------------------------------------------------+
 </code> </code>
  
---- Every subroutine must have a header of the following form: +  * Every subroutine must have a header of the following form: <code perl> 
- +#--------------------------------------------------------------------------- 
-<code> +# 
-  ---------------------------------------------------------------------------- +# update_word 
-  - +# 
-  - update_word +# Updates the word frequency for a word 
-  - +# 
-  - Updates the word frequency for a word +# $word         The word that is being updated 
-  - +# $encoded      1 if the line was found in encoded text (base64) 
-  - $word         The word that is being updated +# $before       The character that appeared before the word in the original 
-  - $encoded      1 if the line was found in encoded text (base64) +#               line 
-  - $before       The character that appeared before the word in the original +# $after        The character that appeared after the word in the original 
-  -               line +#               line 
-  - $after        The character that appeared after the word in the original +# $prefix       A string to prefix any words with in the corpus, used for 
-  -               line +#               the special identification of values found in for example 
-  - $prefix       A string to prefix any words with in the corpus, used for +#               the subject line 
-  -               the special identification of values found in for example +# 
-  -               the subject line +#---------------------------------------------------------------------------
-  - +
-  ----------------------------------------------------------------------------+
 </code> </code>
  
---- Explain any code where the  operation is not obvious with a comment. +  * Explain any code where the  operation is not obvious with a comment. The bar for not obvious should be very low, but never write something like: <code perl> 
-The bar for not obvious should be very low, but never write something like: +# Increment i
- +
-<code> +
-  - Increment i+
  
 $i += 1; $i += 1;
-</code> +</code>but a good comment would be:<code perl> 
- +# This is the A PIECE OF PLATFORM SPECIFIC CODE and all it does is force 
-but a good comment would be: +# Windows users to have v5.8.0 because that's the version with good fork() 
- +# support everyone else can use whatever they want.  This is probably only 
-<code> +# temporary because at some point I am going to force 5.8.0 for everyone 
-  - This is the A PIECE OF PLATFORM SPECIFIC CODE and all it does is force +# because of the better Unicode support
-  - Windows users to have v5.8.0 because that's the version with good fork() +
-  - support everyone else can use whatever they want.  This is probably only +
-  - temporary because at some point I am going to force 5.8.0 for everyone +
-  - because of the better Unicode support+
  
 my $on_windows = 0; my $on_windows = 0;
  
 if ( $^O eq 'MSWin32' ) { if ( $^O eq 'MSWin32' ) {
-<code>   require v5.8.0; +    require v5.8.0; 
-   $on_windows = 1;</code>+    $on_windows = 1;
 } }
 </code> </code>
  
---- Use parens instead of relying on precendence rules.  Write +  * Use parens instead of relying on precendence rules.  Write <code perl>
- +
-<code>+
 if ( ( $foo == $bar ) && ( $number > 0 ) ) { if ( ( $foo == $bar ) && ( $number > 0 ) ) {
-</code> +</code> instead of <code perl>
- +
-instead of +
- +
-<code>+
 if ( $foo == $bar && $number > 0 ) { if ( $foo == $bar && $number > 0 ) {
 </code> </code>
  
---- Don't use elsif.  This is because of some lameness in the POPFile code coverage tool.+  * Don't use elsif.  This is because of some lameness in the POPFile code coverage tool.
  
---- Use lowercase with underscore between words for subroutine and variable +  * Use lowercase with underscore between words for subroutine and variable names, e.g. <code>start_your_engines();</code>
-names, e.g. <code>start_your_engines();</code>+
  
 +==== 5. How is POPFile tested? ====
  
-=== 5. How is POPFile tested? ===+POPFile has an automatic test suite that is run using the tests.pl script. You can type make test in the engine directory to run the tests or simply run tests.pl yourself.
  
-POPFile has an automatic test suite that is run using the tests.pl script. +tests.pl searches the tests/ subdirectory for files ending with .tst and loads them as Perl scripts.  Each .tst module uses two helper functions in test_assert( $test ) and test_assert_equal( $test, $expected ).  test_assert is used to assert that a particular test (an arbitrary piece of Perl that the test_assert subroutine will eval) is true, test_assert_equal is a glorified string and number comparison subroutine that is used to assert that the result of some test (test_assert_equal does no eval the $test parameter) is equal to some expected value.
-You can type make test in the engine directory to run the tests or simply +
-run tests.pl yourself.+
  
-tests.pl searches the tests/ subdirectory for files ending with .tst and +tests.pl will run all the .tst files printing a . for each test that passes and an appropriate error for those that fail, and then print out a summary at the end of the total number of tests and the number that failed.
-loads them as Perl scripts.  Each .tst module uses two helper functions in +
-test_assert( $test ) and test_assert_equal( $test, $expected ).  test_assert +
-is used to assert that a particular test (an arbitrary piece of Perl that +
-the test_assert subroutine will eval) is true, test_assert_equal is a +
-glorified string and number comparison subroutine that is used to assert +
-that the result of some test (test_assert_equal does no eval the $test +
-parameter) is equal to some expected value.+
  
-tests.pl will run all the .tst files printing a . for each test that passes +Each Perl module in POPFile should have a corresponding test file in the tests/ subdirectory.  For example, for %%MailParse.pm%% we have %%TestMailParse.tst%%.
-and an appropriate error for those that fail, and then print out a summary +
-at the end of the total number of tests and the number that failed.+
  
-Each Perl module in POPFile should have a corresponding test file in the +Before checking in new code or submitting a patch run the test suite to protect against regressions.
-tests/ subdirectory.  For example, for MailParse.pm we have +
-TestMailParse.tst.+
  
-Before checking in new code or submitting a patch run the test suite to +==== 6. Why do I have to sign copyright over to John Graham-Cumming? ====
-protect against regressions.+
  
 +POPFile is released under the General Public License used for free software but in order to ensure that the actual code is free of any claims by people who's interests are different from the GPL and to enable me to litigate cleanly if someone were to break the GPL and to create derivative versions of POPFile from code that is contributed without legal problems contributors are required to sign the [[devel:LicenseAgreement |POPFile License Agreement]].
  
-=== 6. Why do I have to sign copyright over to John Graham-Cumming? ===+A simple summary of this license is "you tell me that the code you wrote doesn't belong to someone else, you give me the right to do what I like with it in the context of POPFile, and I protect you from getting sued if your code in POPFile 'injures' someone".
  
-POPFile is released under the General Public License used for free software +Some background reading on the subject of copyright and copyleft and the POPFile License Agreement can be found here:
-but in order to ensure that the actual code is free of any claims by people +
-who's interests are different from the GPL and to enable me to litigate  +
-cleanly if someone were to break the GPL and to create derivative versions +
-of POPFile from code that is contributed without legal problems contributors +
-are required to sign the [[:LicenseAgreement | POPFile License Agreement]].+
  
-A simple summary of this license is "you tell me that the code you wrote  +  - My original thread on POPFile and code copyright: http://sourceforge.net/forum/forum.php?thread_id=800798&forum_id=230652 
-doesn't belong to someone else, you give me the right to do what I like with +  - The Free Software Foundation's FAQ on the GPL: http://www.fsf.org/licenses/gpl-faq.html<code>
-it in the context of POPFile, and I protect you from getting sued if your +
-code in POPFile 'injures' someone". +
- +
-Some background reading on the subject of copyright and copyleft and the  +
-POPFile License Agreement can be found here: +
- +
-1. My original thread on POPFile and code copyright +
-<code>  https://sourceforge.net/forum/forum.php?thread_id=800798&forum_id=230652 +
-  </code> +
-2. The Free Software Foundation's FAQ on the GPL +
-<code>  http://www.fsf.org/licenses/gpl-faq.html+
      
   A very important section reads:   A very important section reads:
Line 225: Line 147:
        
    I URGE YOU TO READ THE ENTIRE FAQ.</code>    I URGE YOU TO READ THE ENTIRE FAQ.</code>
- +  - The Free Software Foundation's note on copyright assignment: http://www.fsf.org/licenses/why-assign.html<code>
-3. The Free Software Foundation's note on copyright assignment +
-<code>  http://www.fsf.org/licenses/why-assign.html+
        
   "By Professor Eben Moglen, Columbia University Law School    "By Professor Eben Moglen, Columbia University Law School 
Line 247: Line 167:
    the programmer's employer. That way we can be sure that all the code in FSF     the programmer's employer. That way we can be sure that all the code in FSF 
    projects is free code, whose freedom we can most effectively protect, and     projects is free code, whose freedom we can most effectively protect, and 
-   therefore on which other developers can completely rely." </code>+   therefore on which other developers can completely rely."  
 +</code>
  
 
developersguide.1169631172.txt.gz · Last modified: 2008/02/08 19:49 (external edit)
Old revisions

Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License