Author: turnstep
Date: Sun Jan 13 19:44:55 2008
New Revision: 10542
Modified:
DBD-Pg/trunk/README.dev
Log:
Update file list, lots of cleanup and changes.
Modified: DBD-Pg/trunk/README.dev
==============================================================================
--- DBD-Pg/trunk/README.dev (original)
+++ DBD-Pg/trunk/README.dev Sun Jan 13 19:44:55 2008
@@ -7,9 +7,6 @@
Note: most of this document assumes you are using a Unix-like system.
-Warning: this document still references cvs, but DBD::Pg is now using
-subversion. Documentation updates will be coming soon.
-
Sections:
* Overview
@@ -69,6 +66,7 @@
TODO - Rough list of upcoming tasks.
+SIGNATURE - Checksum verification via PGP, generated by Module::Signature.
* Build files:
@@ -118,20 +116,23 @@
quote.h - Helper file for quote.c
types.c - Lists all known data types for PostgreSQL.
- Run as a perl script to check for new types.
+ Run as a perl script to check for new types and rewrites the following:
+ types.h types.c Pg.xs Pg.pm t/01constants.t 99_pod.t
types.h - Helper file for types.c
* Test files:
+t/dbdpg_test_setup.pl - Common connection, schema creation, and schema
destruction subs.
+
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/01connect.t - Basic connection tests, outputs detailed connection
information.
t/01constants.t - Quick test of pg_types.
-t/01setup.t - Create the database items needed by the other tests.
-
t/02attribs.t - Tests all attributes.
t/03dbmethod.t - Tests all database handle methods.
@@ -140,21 +141,31 @@
t/04misc.t - Currently only tests the "data_sources" method.
-t/05arrays.t - Currently skipped until arrays are enabled.
-
t/06bytea.t - Tests bytea manipulation.
t/07copy.t - Tests COPY-related methods.
+t/09arrays.t - Tests array manipulation.
+
t/12placeholders.t - Tests placeholders.
t/20savepoints.t - Test savepoints. Requires a server version 8.0 or up.
+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.
+ 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.
-t/99cleanup.t - Removes anything we have created for the tests (e.g. tables)
+t/99_yaml.t - Uses Test::YAML::Meta to verify the META.yml file.
+
+99_yaml.t
* Helper files
@@ -235,7 +246,7 @@
mode for editing this file, please let us know and update this paragraph!
Please follow the other syntax standards in place as much as possible. A few
guidelines
-for xs files can be found in the xs perldocs.
+for XS files can be found in the XS perldocs.
===================
@@ -261,21 +272,17 @@
version, so that PG 7.4.2 is listening on port 5742. Then set up two aliases
for each
version, like so:
-alias dbd727='export DBI_DSN="dbi:Pg:dbname=greg;port=5727"'
-alias dbd727m='export POSTGRES_LIB=/home/greg/pg727/lib
POSTGRES_INCLUDE=/home/greg/pg727/include POSTGRES_DATA=/home/greg/pg727'
+alias dbd747='export DBI_DSN="dbi:Pg:dbname=greg;port=5747"'
+alias dbd747m='export POSTGRES_LIB=/home/greg/pg747/lib
POSTGRES_INCLUDE=/home/greg/pg747/include POSTGRES_DATA=/home/greg/pg747'
This allows for quick testing of each combination:
-> dbd727m
-> dbd727
+> dbd747m
+> dbd747
> perl Makefile.PL
> make test (check output for any errors)
> dbd739
> make test
-> dbd747
-> make test
-> dbd747
-> make test
> dbd802
> make test
> dbd739m
@@ -283,15 +290,13 @@
> make test
> dbd727
> make test
-> dbd747
-> make test
> dbd802
> make test
etc...
-It's also a good idea to test the current cvs version of Postgres in your
tests: this can detect
-changes nice and early.
+It's also a good idea to test the current HEAD version of Postgres in your
tests:
+this can detect changes nice and early.
In addition to different versions of Postgres, it's a good idea to test a few
versions of
DBI: this has caught problems in the past. You'll basically need to install
the different
@@ -454,12 +459,13 @@
* If you do create a new test, keep the name short, start it with a number,
and use an
existing test as a template.
-* Tests should be as "standalone" as possible. The only exception is that most
of them
-will need 01setup.t to be run first, to create the testing table. However,
once this
-has been run, and before 99cleanup.t has been run, each test file should run
flawlessly
-multiple times. Tests should remove any objects they create at the end of the
script,
-and should be able to silently recreate objects as needed (see 07copy.t for an
example).
-Objects should be created as "temporary" whenever possible.
+* 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.
+
+* 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
+current test table and other objects, use connect_database({nosetup => 1}).
* Use the standard format for tests, and always provide an appropriate output
text.
Abbreviations are encouraged, but be consistent throughout the file.
@@ -535,7 +541,7 @@
new version, whether beta or regular. It is assumed you are very familiar with
the
other sections referenced herein (indicated with **)
-* Test on variety of versions (see ** Heavy Testing)
+* Test on variety of versions (see ** Heavy Testing), including the optional
tests.
* Make sure everything is up to date in subversion
@@ -561,9 +567,6 @@
* Update the Changes file
The best way to do this (other than doing it as you go along) is to check the
subversion logs.
-For example, to grab all changes made since revision 1.43 and save it to a
file:
-
-cvs log -rRel-1_43: * > all_logs.tmp
* Update the documentation
@@ -592,25 +595,7 @@
* Now that everything works, set a symbolic name for this version.
Remember to use underscores (see the ** Version Numbers section)
-For example, to tag all of the current file as the first beta of 1.43, use:
-
-cvs rtag Rel-1_42_1 dbdpg
-
-If you ever need to remove a symbolic tag, you can use:
-
-cvs admin -nRel-1_42_1 filename
-
-To add a symbolic tag to a particular version of a file use:
-
-cvs admin -nRel-1_42_1:1.19 filename
-
-To add a symbolic tag to the latest version of a file use:
-
-cvs admin -nRel-1_42_1: filename
-
-To reposition a symbolic tag to the latest version of a file use:
-
-cvs admin -NRel-1_42_1: filename
+TODO: Expand this section with subversion examples.
* Make checksums
@@ -684,11 +669,6 @@
Also known as, the section to put things that don't fit anywhere else.
Anything
that may make life easier for other developers can go here.
-* To change a cvs comment, use the "cvs admin" command, a dash m, the version
number,
-a colon, and the new text, then the file name. Example:
-
-cvs admin -m1.118:"Memory leak patch by [EMAIL PROTECTED]" dbdimp.c
-
* Temporary tables
We do not use temporary tables in most of our test because they are
@@ -766,9 +746,9 @@
The latest DBI:
http://search.cpan.org/~timb/DBI/
-The source code of other DBDs can be a useful tool as well. In other words,
the "competition" :)
+The source code of other DBDs can be a useful tool as well.
-* PostgreSQL
+* Postgres
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
@@ -788,7 +768,7 @@
* Perl
-Besides a good general understanding of Perl, it helps to learn a little bit
about xs:
+Besides a good general understanding of Perl, it helps to learn a little bit
about XS:
perldoc perlapi
perldoc perlclib
@@ -803,27 +783,24 @@
The all important testing suite:
-perldoc Test;
-perldoc Test::Harness;
-perldoc Test::Simple;
-perldoc Test::More;
-perldoc Test::Pod;
-perldoc Test::Pod::Coverage;
-
+perldoc Test
+perldoc Test::Harness
+perldoc Test::Simple
+perldoc Test::More
+perldoc Test::Pod
+perldoc Test::Pod::Coverage
+perldoc Test::YAML::Meta
-Othjer important modules:
-perldoc Devel::Cover;
-perldoc Module::Signature;
-
-
-This is a guide for DBD authors. It's fairly old and incomplete however, but
listed here for
-completeness:
+Other important modules:
+
+perldoc Devel::Cover
+perldoc Module::Signature
+perldoc Perl::Critic
+perldoc DBI::Profile
-perldoc DBI::DBD
+Also see DBI::DBD. It's fairly old and incomplete however, but still useful.
-A handy module to know about:
-perldoc DBI::Profile
