Author: turnstep Date: Mon Feb 4 20:43:03 2008 New Revision: 10691 Modified: DBD-Pg/trunk/README.dev DBD-Pg/trunk/TODO
Log: Updates. Modified: DBD-Pg/trunk/README.dev ============================================================================== --- DBD-Pg/trunk/README.dev (original) +++ DBD-Pg/trunk/README.dev Mon Feb 4 20:43:03 2008 @@ -47,6 +47,7 @@ Here is what each file in the distribution does: + * Text files: Changes - lists changes made to each version. Please be consistent and use @@ -59,8 +60,8 @@ README - the main file that explains the module, where to get it, and guides people in installing it. A large portion of it is simply a list of common - gotchas and guides for various platforms. This is one of four files that lists - the version number. + gotchas and guides for various platforms. This file has a version number + in it (or two, if this is a beta/release candidate) README.win32 - the directions on how to install DBD::Pg on a Win32 box. @@ -68,14 +69,16 @@ SIGNATURE - Checksum verification via PGP, generated by Module::Signature. + * Build files: Makefile.PL - The main file that starts everything off. Used by ExtUtils::MakeMaker - to create the "Makefile" + to create the "Makefile". This file contains a version number. Makefile - Generated automatically by Makefile.PL -META.yml - YAML description file. +META.yml - YAML description file. Updated by hand and contains a version number. + * Distribution files: @@ -83,7 +86,7 @@ Used by the "make dist*" set of commands. MANIFEST.SKIP - files that are known to be safe to exclude from the release - tarball. Used by the "make distcheck" command + tarball. Used by the "make dist", "make distcheck" and "make skipcheck" commands. win32.mak - a helper file for the win32 build. @@ -96,8 +99,8 @@ dbdimp.h - Helper file for dbdimp.c. -Pg.pm - The main perl file, which contains all the DBD::Pg packages and code - for the methods. Often times code here calls code from Pg.xs and dbdimp.c. +Pg.pm - The main Perl file, which contains DBD::Pg packages and code for the + methods. Often times code here calls code from Pg.xs and dbdimp.c. This file contains a version number in two places (once in the code, once in the POD). The main documentation for the module lives here, as POD information. @@ -107,9 +110,9 @@ Pg.c - Not part of the distribution, but created from Pg.xs as part of the build process. Never edit this directly. -Pg.h - Helper file for Pg.xs (or Pg.c) +Pg.h - Helper file for Pg.xs (and thus Pg.c) -quote.c - Various methods to help quote and dequote variables. Much of this is +quote.c - Various methods to help quote and dequote variables. Some of this is now done on the backend, but it is still needed to support older versions of PostgreSQL. @@ -127,9 +130,10 @@ t/00basic.t - Very basic test to see if DBI and DBD::Pg load properly. -t/00-signature.t - Use Module::Signature to verify SIGNATURE file. Requires TEST_SIGNATURE +t/00-signature.t - Uses Module::Signature to verify SIGNATURE file. All tests are skipped + if the environment variable TEST_SIGNATURE is not set. -t/01connect.t - Basic connection tests, outputs detailed connection information. +t/01connect.t - Basic connection tests, outputs pretty, detailed connection information. t/01constants.t - Quick test of pg_types. @@ -139,7 +143,7 @@ t/03smethod.t - Tests all statement handle methods. -t/04misc.t - Currently only tests the "data_sources" method. +t/04misc.t - Tests data_sources, $DBDPG_DEFAULT, and txn status changes. t/06bytea.t - Tests bytea manipulation. @@ -153,20 +157,17 @@ t/99cleanup.t - Removes anything we have created for the tests (e.g. tables) -99_perlcritic.t - Uses Perl::Critic to check Pg.pm and all of the test files. +t/99_perlcritic.t - Uses Perl::Critic to check Pg.pm and all of the test files. Requires that TEST_CRITIC is set. It is recommended that you get all the Perl::Critic policies via Bundle::Perl::Critic::IncludingOptionalDependencies. .perlcriticrc - Used by the above: we assume tests are run from the main dir. t/99_pod.t - Verifies the POD of Pg.pm. Requires Test::POD version 0.95, and - Test::Pod::Coverage 1.04. Neither are mandatory for normal testing, but - developers are highly encouraged to install them. + Test::Pod::Coverage 1.04. t/99_yaml.t - Uses Test::YAML::Meta to verify the META.yml file. -99_yaml.t - * Helper files @@ -302,9 +303,8 @@ DBI: this has caught problems in the past. You'll basically need to install the different versions of DBI into different directories, then adjust PERL5LIB with aliases: -alias dbi138='export PERL5LIB=/home/greg/perl/dbi138/lib/perl5/site_perl/5.8.7/i686-linux' -alias dbi139='export PERL5LIB=/home/greg/perl/dbi139/lib/perl5/site_perl/5.8.7/i686-linux' - +alias dbi156='export PERL5LIB=/home/greg/perl/dbi156/lib/perl5/site_perl/5.10.0/i686-linux' +alias dbi157='export PERL5LIB=/home/greg/perl/dbi157/lib/perl5/site_perl/5.10.0/i686-linux' * Using splint @@ -314,49 +314,23 @@ http://www.splint.org/ It is typically run against a single C file, in our case, dbdimp.c and the generated Pg.c file. -It will not work out of the box, as our dependencies tend to be scattered about. Here is a minimal -file that should work: +This is a very finicky tool. There is a "splint" target in the Makefile. There are three +challenges to using splint: -splint \ -+unixlib \ -+single-include \ --I$DBIDIR \ --I$POSTGRES_INCLUDE \ --I$PERLDIR \ --I/source/bin/DBI-1.48 \ --I/source/pg801/include \ --I/usr/lib/perl5/5.8.5/i686-linux-ld/CORE \ -Pg.c - -You will need to define the environment variables and put the correct path to the DBI, -Postgres, and Perl directories (the Perl one should end in "CORE"). Splint can be -tempermental, so you may need to add more than that, and tweak a few things. It may -take a few runs to get it to go without errors. Once you do get it running, it is very -thorough and extremely verbose. Many of the items will be from DBI, so hunt carefully. -You can start filtering out items you do not need to check. Here are a few common ones: - --nullpass \ --predboolint \ -+charint \ -+charintliteral \ --nullderef \ --branchstate \ --mustfreeonly \ --mustfreefresh \ --boolops \ --type \ --observertrans \ --globstate \ --nullstate \ --compdef \ --onlytrans \ --realcompare \ --nullret \ --bufferoverflowhigh \ +1) Getting it to work in the first place. As the Makefile.PL section says, you need at least +version 3.1.2. You also need to include all the relevant files, which Makefile.PL should do +for you. -Note that most, if not all, of the above, *should* be checked on the first pass, and then -gradually added to make the output easier to read. +2) Limiting the amount of results. splint is extremely verbose, so one must usually limit +what sort of things are returned. Again, the Makefile.PL has a partial list. +3) Figuring out the real problems. Again, splint's verbosity takes some getting used to, as +does interpreting its output, and deciding what is really a problem and what is not. + +* Using valgrind + +We've not gotten valgind to work against DBD::Pg, but would love to. Please email the list +if you manage to do so! * Using Devel::Cover @@ -427,7 +401,7 @@ "bt" command at the gdb prompt. This will run a backtrace and give you an idea of what is causing the problem. -* For really low-level debugging, you can use pg_server_trace() function. +* For really low-level debugging from the Postgres side, you can use pg_server_trace() function. * The perl debugger can also be helpful (perl -d ping.test.tmp). @@ -462,6 +436,7 @@ * Tests should be as "standalone" as possible. Most will call dbdpg_test_setup.pl to automatically setup the test table used. It's a good idea to delete any objects your test itself creates. Objects should be created as "temporary" whenever possible. +Things should be always have a name starting with "dbd_pg_test". * Don't call DBI->connect inside of your tests, but use connect_database() from the dbdpg_test_setup.pl file instead. If you don't want it to blow away and recreate the @@ -474,10 +449,7 @@ tag with an appropriate message if a test does not work on a particular version of something (see 20savepoints.t for an example). -* When developing a new test, or just sorting out an issue with an existing one, -set the environment variable DBDPG_QUICKTEST to true, and the testing will bail -out at the start of 00basic.t. This allows you to run tests starting with 000 without -going through all the tests. +* To run a single test, use: prove --blib . -v t/testname.t ===================== @@ -491,13 +463,13 @@ indicate a change in functionality, new features, etc. The revision number is used for small tweaks and bug fixes, and must be completely compatible with the version before it. -Beta versions are the vesion with an undercore at the end of it. The tells CPAN not to consider -this a "real" release. For example, if the upcoming release is 1.2.3, the first release -candidate would be 1.2.3_1. A second would be 1.2.3_2 etc. +Beta versions (aka release candidates) are the version with an underscore at the end of it. The +tells CPAN not to consider this a "real" release. For example, if the upcoming release is 2.2.3, +the first release candidate would be 2.2.3_1. A second would be 2.2.3_2 etc. Version numbers are currently set in five files: -README +README (one or two places) Pg.pm (two places!) Changes Makefile.PL @@ -521,6 +493,8 @@ * Updated/created necessary tests for it +* Added it to the "File List" section above. + ================= == New Methods == @@ -547,23 +521,23 @@ * Update the versions (see ** Version Numbers) in README, Pg.pm (2 places!), Makefile.PL, META.yml, and Changes. -* Put the final release date into the Changes file. +* If a final version, put the release date into the Changes file. * If a beta version, please put a large warning at the top of the README file. Here is a sample: =================================================== WARNING!! -THIS IS A TEST VERSION (1.43_2) AND SHOULD BE USED +THIS IS A TEST VERSION (2.4.1_2) AND SHOULD BE USED FOR TESTING PURPOSES ONLY. PLEASE USE A STABLE VERSION (no underscore) BY VISITING: http://search.cpan.org/~dbdpg/ =================================================== -* If not a beta version, remove the warning from the README. +* If not a beta version, remove the above warning from the README. -* Update the Changes file +* Completely update the Changes file The best way to do this (other than doing it as you go along) is to check the subversion logs. @@ -571,9 +545,10 @@ Make sure that anything new has been documented properly, usually as pod inside of Pg.pm A good way to do this is to use the tests in 99_pod.t - they will run automatically as -part of the test suite if the right modules are installed. You can do this to test: +part of the test suite if the right modules are installed. -prove -v t/99_pod.t +* Update the SIGNATURE file with Module::Signature. Make sure this is done *after* +you check everything else in, due to the the $Id$ lines. * Run "perl Makefile.PL" @@ -589,19 +564,12 @@ release tarball. Make sure there is nothing important here. * Run "make disttest". This unpacks the tarball, then runs "make" and "make test" on it. -You may also want to remove the directory it creates later. "make realclean" - -* Now that everything works, set a symbolic name for this version. -Remember to use underscores (see the ** Version Numbers section) - -TODO: Expand this section with subversion examples. +You may also want to remove the directory it creates later by using "make realclean" * Make checksums Generate md5 and sha1 checksums of the tarball. Include this in your emails. -* Update the SIGNATURE file with Module::Signature - * Test it out Download the tarball to a completely different system, unpack and test it. @@ -672,7 +640,7 @@ We do not use temporary tables in most of our test because they are not persistent across tests, they mess up the schema testing, and they -are compatible with the foreign key testing. But do try and use them +are not compatible with the foreign key testing. But do try and use them whenever possible. * "turnstep" in the cvs/svn logs is Greg Sabino Mullane, [EMAIL PROTECTED] @@ -723,7 +691,7 @@ == Resources == =============== -The primary resource is the dbdpg-general mailing list, where the developers live. Other +The primary resource is the mailing list, where the developers live. Other resources depend on the subject: * DBD::Pg @@ -752,10 +720,10 @@ A good source for general questions on libpq and similar things is the pgsql-interfaces list. Another good source for more generic questions (and perhaps better for all questions, as it tends to be more active) is the pgsql-hackers list. Having a copy of the source code is invaluable as well. Using a -tool like glimpse is handy to find those obscure libpq functions quickly. You also may want to keep -the libpq documentation handy. +tool like glimpse or ctags is handy to find those obscure libpq functions quickly. You also may want +to keep the libpq documentation handy. -All PG mailing lists: +All of the Postgres mailing lists: http://www.postgresql.org/community/lists/ A great source for searching the pg documentation and mailing lists is: @@ -764,6 +732,16 @@ which allows you to limit the search by version: very helpful as we support multiple versions of PostgreSQL. +There are many ways to search the Postgres mailing lists: + +http://postgresql.markmail.org/ + +http://www.nabble.com/PostgreSQL-f759.html + +http://archives.postgresql.org/ + +http://groups.google.com/ (add group:pgsql.*) + * Perl @@ -799,7 +777,5 @@ perldoc DBI::Profile -Also see DBI::DBD. It's fairly old and incomplete however, but still useful. - - +Also see DBI::DBD. It's fairly old and incomplete, but still useful. Modified: DBD-Pg/trunk/TODO ============================================================================== --- DBD-Pg/trunk/TODO (original) +++ DBD-Pg/trunk/TODO Mon Feb 4 20:43:03 2008 @@ -2,7 +2,6 @@ - Mention RETURNING clause support in docs. - Play nicely with standard_confirming_strings (CPAN bug #27538) -- Update pg_getline and remove the size requirement - Use WITH HOLD for cursor work - Start testing with a thread-enabled Perl - Support for new error protocol @@ -12,7 +11,6 @@ things like arrays can be serialized by the quote function. This will take care of broken chopblanks and pg_bool_tf (pass the quote/dequote options struct to function quote/dequote functions). -- Implement a clean UTF-8 support. - Allow user callbacks to quote user-defined types? - Rename functions and add defines to avoid problems with static linking of multi DBDs - Move to the Module::Build system
