Author: turnstep
Date: Fri Jul 25 09:33:11 2008
New Revision: 11589
Modified:
DBD-Pg/trunk/README
DBD-Pg/trunk/README.dev
DBD-Pg/trunk/t/99_spellcheck.t
Log:
Cleanup of the README files.
Modified: DBD-Pg/trunk/README
==============================================================================
--- DBD-Pg/trunk/README (original)
+++ DBD-Pg/trunk/README Fri Jul 25 09:33:11 2008
@@ -6,8 +6,8 @@
DESCRIPTION:
------------
-This is version 2.8.8 of DBD::Pg. The web site for this interface, and
-the latest version, can be found at:
+This is version 2.8.8 of DBD::Pg, the Perl interface to Postgres using DBI.
+The web site for this interface, and the latest version, can be found at:
http://search.cpan.org/dist/DBD-Pg/
@@ -30,6 +30,7 @@
---------------------------------
Please send any problems and comments to
+
<[EMAIL PROTECTED]>
Please include what OS you are using, and the version of Perl,
@@ -50,7 +51,6 @@
and selecting the "Report a new bug" link. Please check that the bug
has not already been reported first.
-
REQUIREMENTS:
-------------
@@ -59,12 +59,12 @@
build, test, and install PostgreSQL (at least 7.4)
build, test, and install Test::Simple (at least 0.47)
-You must also have the pg_config executable installed (to check, type
-"which pg_config" on unix-like systems). If pg_config is not available,
-then you need to install the development package for PostgreSQL. For example
-on Debian: apt-get install postgresql-dev; on RedHat: yum install
postgresql-devel.
-This development package is needed even if you already have PostgreSQL up
-and running since DBD::Pg uses it for its installation.
+DBD::Pg needs to know where to find the libpq libraries: this is usually done
+by checking the output of the pg_config executable. If pg_config is not
available,
+then you may need to install the development package for PostgreSQL. To do
this
+on Debian and ubuntu, use: apt-get install postgresql-dev; on RedHat and
CentOS,
+use: yum install postgresql-devel. Note that the development libraries are
needed
+even if you already have PostgreSQL up and running.
INSTALLATION:
-------------
@@ -89,13 +89,13 @@
3. make test
4. make install
-Do steps 1 to 3 as a normal user, not as root!
+Do steps 1 to 2 as a normal user, not as root!
If the script cannot find the pg_config information itself, it will
ask you for the path to it. Enter the complete path to the pg_config
file here, including the name of the file itself.
-TESTING:
+yTESTING:
--------
The tests rely on being able to connect to a valid Postgres database.
@@ -128,10 +128,6 @@
When reporting test failures, please use TEST_VERBOSE=1, but do *not*
set DBD_TRACE unless requested, and send only the relevant sections.
-If the first connection fails and DBI_DSN is not set, the tests may
-attempt to connect as the user 'postgres' to the database 'postgres'.
-See the t/dbdpg_test_setup.pl for the exact process.
-
Please consider installing CPAN::Reporter so that your tests are
automatically gathered and reported, which helps the development
of DBD::Pg.
@@ -163,7 +159,7 @@
$dbh->{pg_server_prepare} = 0;
This can also be set for individual queries at the statement handle level: see
-the documentation for more details.
+the documentation section on "Placeholders" for more details.
* PostgreSQL library issues:
Modified: DBD-Pg/trunk/README.dev
==============================================================================
--- DBD-Pg/trunk/README.dev (original)
+++ DBD-Pg/trunk/README.dev Fri Jul 25 09:33:11 2008
@@ -77,9 +77,9 @@
Makefile.PL - The main file that starts everything off. Used by
ExtUtils::MakeMaker
to create the "Makefile". This file contains a version number.
-Makefile - Generated automatically by Makefile.PL
+Makefile - Generated automatically by Makefile.PL. Not part of the
dsitribution.
-META.yml - YAML description file. Updated by hand and contains version number
in three places.
+META.yml - YAML description file. Updated by hand and contains a version
number in three places.
lib/Bundle/DBD/Pg.pm - Simple file used to enable perl -MCPAN -e 'install
Bundle::DBD::Pg'
Contains a version number.
@@ -102,12 +102,12 @@
module (the rest is done by Pg.pm). Almost all of the complexity and power
of
the module is here.
-dbdimp.h - Helper file for dbdimp.c.
+dbdimp.h - Header file for dbdimp.c.
dbivport.h - DBI portability macros. This should be the latest version from
the
DBI subversion repository.
-Pg.pm - The main Perl file, which contains DBD::Pg packages and code for the
+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.
@@ -118,24 +118,25 @@
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 (and thus Pg.c)
+Pg.h - Header file for Pg.xs (and thus Pg.c)
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.
-quote.h - Helper file for quote.c
+quote.h - Header file for quote.c
types.c - Lists all known data types for PostgreSQL.
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
+types.h - Header file for types.c
* Test files:
t/dbdpg_test_setup.pl - Common connection, schema creation, and schema
destruction subs.
+ Goes through a lot of trouble to try and get a database to test with.
t/00basic.t - Very basic test to see if DBI and DBD::Pg load properly.
Requires Test::Warn
for the version warning test.
@@ -153,12 +154,14 @@
t/03smethod.t - Tests all statement handle methods.
-t/04misc.t - Tests data_sources, $DBDPG_DEFAULT, and txn status changes.
+t/04misc.t - Tests tracing, data_sources, $DBDPG_DEFAULT, and txn status
changes.
t/06bytea.t - Tests bytea manipulation.
t/07copy.t - Tests COPY-related methods.
+t/08async.t - Tests asynchronous methods.
+
t/09arrays.t - Tests array manipulation.
t/12placeholders.t - Tests placeholders.
@@ -178,6 +181,8 @@
t/99_yaml.t - Uses Test::YAML::Meta to verify the META.yml file.
+t/99_spellcheck.t - Checks the spelling of everything it can.
+
dbdpg_test_database - May be created by the test suite as a place to store
a new database cluster.
@@ -260,7 +265,8 @@
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. When in doubt, go with the
guidelines from
+Damian Conway's Perl Best Practices book.
===================
@@ -347,7 +353,7 @@
* Using valgrind
-We've not gotten valgind to work against DBD::Pg, but would love to. Please
email the list
+We've not gotten valgrind to work against DBD::Pg, but would love to. Please
email the list
if you manage to do so!
* Using Devel::Cover
@@ -364,6 +370,29 @@
then check out the coverage.html file inside the cover_db directory.
+* Using Devel::DProf
+
+This module is good for finding bottlenecks in the C portion of the code.
Generally, you
+create a small test file that does heavy looping over some methods of
interest, and
+then run it with:
+
+perl -d:DProf testfile.pl
+
+Then view the results with:
+
+dprofpp
+
+* Using Devel::NYTProf
+
+Another nice Perl-level profiler. To use:
+
+perl -d:NTYProf testfile.pl
+
+Then run:
+
+nytprofhtml
+
+and check out the generated HTML files.
===============
@@ -437,10 +466,11 @@
* Whenever you add a new feature, no matter how minor, add a test. Better yet,
add
many tests to make sure that it not only works correctly, but that it breaks
when
it is supposed to (e.g. when it is fed the wrong output). Try to conceive of
every
-possible way your feature will be used and mis-used.
+possible way your feature will be used and mis-used. Consider the effects of
older
+versions of Perl, DBI, and/or Postgres.
-* If someone files a bug report that is not revealed by a test, please add one
in,
-no matter how simple the fix maybe, or how stupid the bug is.
+* If someone files a bug report that is not revealed by a test, please add a
new test
+for it, no matter how simple the fix maybe, or how stupid the bug is.
* Don't create a new test file unless necessary - use the existing ones
whenever possible.
Most things can fit in 03dbmethod.t (database handle methods) or 03smethod.t
(statement
@@ -487,7 +517,7 @@
Version numbers are currently set in six files:
-README (one or two places)
+README (one place, two if a beta version)
Pg.pm (two places)
Changes
Makefile.PL
@@ -538,7 +568,7 @@
* Make sure everything is up to date in subversion
* Update the versions (see ** Version Numbers) in README, Pg.pm (2 places!),
Makefile.PL,
- META.yml, and Changes.
+ lib/Bundle/DBD/Pg.pm, META.yml (3 places!), and Changes.
* If a final version, put the release date into the Changes file.
@@ -554,21 +584,19 @@
http://search.cpan.org/dist/DBD-Pg/
===================================================
-* If not a beta version, remove the above warning from the README.
+* If not a beta version, remove the above warning from the README if it exists.
* 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.
+The best way to do this (other than doing it as you go along) is to check the
subversion logs,
+by running a diff against the last-releaed version.
* Update the documentation
-Make sure that anything new has been documented properly, usually as pod
inside of Pg.pm
+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.
-* Update the SIGNATURE file with Module::Signature. Make sure this is done
*after*
-you check everything else in, due to the the magic (dollarsign)Id lines.
-
* Run "perl Makefile.PL"
* Run "make dist". Double check that the tarball created has the correct
version name.
@@ -579,9 +607,12 @@
and then re-run. Note that files ending in ".tmp" are currently skipped, so
this is a good
extension for any miscellaneous files you have that use often (e.g.
libpq-fe.h.tmp)
-* Run "make skipcheck". This will show you a list of files that will not be
packed into the
+* Run "make skipcheck". This will show you a list of files that will NOT be
packed into the
release tarball. Make sure there is nothing important here.
+* Update the SIGNATURE file with Module::Signature. Make sure this is done
*after*
+you check everything else in, due to the the magic (dollarsign)Id lines.
+
* 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 by using "make
realclean"
@@ -604,6 +635,9 @@
is loaded, wait for it to appear on the main DBD::Pg page and then test that
the file
has the same checksums.
+* Commit the SIGNATURE file. Remember the subversion revision number given,
and add that
+to the Changes files. Then commit the Changes file.
+
* Announce to the "public" lists
[EMAIL PROTECTED]
@@ -739,11 +773,9 @@
* 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
-active) is the pgsql-hackers list. Having a copy of the source code is
invaluable as well. Using a
-tool like glimpse or ctags is handy to find those obscure libpq functions
quickly. You also may want
-to keep the libpq documentation handy.
+A good source for general questions on libpq and similar things is the
pgsql-hackers list. Having a
+copy of the Postgres source code is invaluable as well. Using a 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 of the Postgres mailing lists:
http://www.postgresql.org/community/lists/
@@ -799,5 +831,6 @@
perldoc DBI::Profile
-Also see DBI::DBD. It's fairly old and incomplete, but still useful.
+Also see perldoc DBI::DBD. It's fairly old and incomplete, but still useful.
+
Modified: DBD-Pg/trunk/t/99_spellcheck.t
==============================================================================
--- DBD-Pg/trunk/t/99_spellcheck.t (original)
+++ DBD-Pg/trunk/t/99_spellcheck.t Fri Jul 25 09:33:11 2008
@@ -489,7 +489,6 @@
utf
UTF
Util
-valgind
valgrind
varchar
VARCHAR
