This file is for those interested in developing Bucardo.

It is hoped that it will be a good introduction as well as a continual 
reference. Suggestions are always welcome.

Sections:

* File List
* Editing
* Test Files
* Version Numbers
* New Files
* Making a New Release
* Tips and Tricks

===============
== File List ==
===============

Here is what each file in the distribution does:


* Text files:

Changes - lists changes made to each version. Please be consistent and use 
  tabs, not spaces, to indent. Try to list who found the bug, and who 
  fixed it (if not the same person). Put the person who made the actual 
  changes in brackets. This file contains a version number.

README.dev - you are reading it.

README - the main file that explains the module, where to get it, and guides 
  people in installing it. This file contain a version number.

TODO - Rough list of ideas on improving Bucardo.

SIGNATURE - Checksum verification via PGP, generated by Module::Signature.

INSTALL - Basic install instructions

UPGRADE - Basic upgrade instructions


* Build files:

Makefile.PL - Standard Perl file that creates the makefile via "perl Makefile.PL"
  Note that this file also creates the html files. Contains a version number.

Makefile - Generated automatically by Makefile.PL

META.yml - YAML description file. Updated by hand and contains version 
  number in two places.


* Distribution files:

MANIFEST - lists which files should be included in the release tarball. 
  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 dist", "make distcheck" and "make skipcheck" commands.

* Program files:

Bucardo.pm - The main program. This is the core of Bucardo - everything else supports 
  this file. Contains a version number in two places.

bucardo - The main command-line interface to Bucardo. Contains a version number.

scripts/* - Various scripts

* Documentation files:

Bucardo.pm.html - generated by "make html" from the POD in Bucardo.pm

bucardo.html - generated by "make html" from the POD in bucardo

* Supporting files:

bucardo.schema - The schema for Bucardo. Contains a version number in two places.

.perlcriticrc - Customized Perl::Critic rules for the t/99perlcritic.t file.

.gitignore - Things we don't want git to look at

* Test files:

t/BucardoTesting.pm - Shared routines for setup and teardown.

t/00setup.t - Shared code for the Bucardo tests.

t/01basic.t - Test of very basic things.

t/02-simple.t - Very simply replication tests

t/03-goat.t - Test goat access methods.

t/04-pushdelta.t - Test pushdelta syncs.

t/02-monkey_with_db_table.t - Test db manipulation via bucardo

t/02-monkey_with_goat_table.t - Test goat manipulation via bucardo

t/02-monkey_with_herd.t - Test herd manipulation via bucardo

t/02-monkey_with_sync_table.t - Test sync manipulation via bucardo

t/05-fullcopy.t - Test fullcopy

t/06-multicolpk.t - Test multi-column primary keys

t/06-multicolpushdelta.t - Test multi-column primary keys for pushdelta syncs

t/07-multicolswap.t - Test multi-column primary keys for swap syncs

t/08-wildkick.t - Test kicking more than one sync at a time

t/09-uniqueconstraint.t - Test of customcode with pushdelta

t/10-makedelta.t - Test of makedelta functionality

t/12-addtable.t - Test adding new tables

t/13-ddl.t - Test pushing DDL (not complete yet)

t/14-truncate.t - Test of truncation replication (requires Postgres 8.4 or greater)

t/15-star.t - Test of star replication scheme

t/98-cleanup.t - Shuts down test databases. Called by "make distclean"

t/99-perlcritic.t - Uses Perl::Critic to check Bucardo.pm, bucardo, and all the 
  test files (including itself). Requires that TEST_CRITIC is set. It is recommended 
  that you get all the Perl::Critic policies via Bundle::Perl::Critic::IncludingOptionalDependencies.

t/99-pod.t - Verifies the POD of Pg.pm. Requires Test::POD version 0.95, and 
  Test::Pod::Coverage 1.04.

t/99-signature.t - Uses Module::Signature to verify SIGNATURE file. All tests are skipped 
  if the environment variable TEST_SIGNATURE is not set.

t/99-spellcheck.t - Spell checks all files and comments

t/99-yaml.t - Uses Test::YAML::Meta to verify the META.yml file.

* Developer test files are in the dev/ directory

=============
== Editing ==
=============

All the perl files should have a cperl pragma at the top of the file, for easy use in emacs. 
Please use tabs and not spaces everywhere, and keep the indenting to the cperl standard.
When in doubt, use the guidelines from the Perl Best Practices book, with the following 
exceptions:

* Use tabs, not spaces. When using spaces, make them 4 characters wide.

================
== Test Files ==
================

The test files are an important part of the module. Much work has gone into making 
the tests as complete, thorough, and clean as possible. Please try to follow these 
guidelines when developing:

* 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.

* 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.

* Don't create a new test file unless necessary - use the existing ones whenever possible. 

* If you do create a new test, keep the name short, start it with a number and a dash, 
and use an existing test as a template.

* Tests should be as "standalone" as possible. Most will call bucardo.test.pl to 
automate setting up and tearing down supporting test infrastructure.

* 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.

* Make sure to test on different versions of PostgreSQL, DBI, and Perl. Use the SKIP 
tag with an appropriate message if a test does not work on a particular version of 
something.

* To run a single test, use: prove --blib . -v t/testname.t


=====================
== Version Numbers ==
=====================

Version numbers follow the Postgres convention: major, minor, and revision. 
The major number should very, very rarely change, and is saved for the truly major changes 
(e.g. those that may cause backwards compatibility problems). The minor revision is used to 
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.

Version numbers are currently set in nine files:

README
Bucardo.pm (two places)
Bucardo.pm.html
bucardo
bucardo.html
bucardo.schema (three places)
Changes
Makefile.PL
META.yml (three places)


===============
== New Files ==
===============

If you are adding a new file to the distribution (and this should be a rare event), 
please check that you have done the following items:

* Added it to via 'git add filename' and 'git commit'

* Added it to the MANIFEST file

* Added it to Makefile.PL if needed, to make sure all build dependencies are met

* Updated/created necessary tests for it

* Added it to the "File List" section above.


==========================
== Making a New Release ==
==========================

This is a comprehensive checklist of all the steps required to release a 
new version, whether beta or regular. It is assumed you are very familiar with the 
other sections referenced herein.

* Test on variety of versions of Postgres

* Make sure everything is up to date and committed in git.

* Update the versions in all relevant files. Use t/00_release.t to verify this.

* 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.9.1_2) AND SHOULD BE USED 
FOR TESTING PURPOSES ONLY. PLEASE USE A STABLE 
VERSION (no underscore) BY VISITING:

http://bucardo.org
===================================================

* If not a beta version, remove the above warning as needed from the README.

* Completely update the Changes file

The best way to do this (other than doing it as you go along) is to check the git logs.

* Update the documentation

Make sure that anything new has been documented properly, usually as pod inside of Bucardo.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.

* Make sure the wiki is updated as well.

* Run "perl Makefile.PL"

* Run "make html". This will create the html docs for Bucardo.pm and bucardo. Make sure you 
git commit them if anything has changed.

* Run "make dist". Double check that the tarball created has the correct version name.

* Run "make distcheck". This will show you a list of all files that are in the current directory 
but not inside the MANIFEST file (or the MANIFEST.SKIP file). If there are any new files here 
that should be part of the distribution, add them to the MANIFEST file, commit your changes, 
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.

* 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.

* 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"

* Update the SIGNATURE file with Module::Signature. This should be done as the 
very last step. Running "make signature" will do the signing for you.

* Create a tag for the new version with "git tag".
  Example: git tag -u 14964ac8 -m "Version 4.0.1" 4.0.1

* Create a new tarball with "make dist". Sign it: "gpg -ba <name>"

* Put the tarball and detached sig file in the downloads directory on bucardo.org

* Update the wiki pages for the new version: Bucardo/Downloads, Bucardo/Changes

* Update the bucardo/latest_version.txt file on the website.

* Change the topic on #bucardo on irc.freenode.net

* Announce to the bucardo-announce list.

* Post to pgsql-announce if this is a major or important version.

* Post to the "PostgreSQL news"

On the main page, there is a link named "Submit News" which points to:

http://www.postgresql.org/about/submitnews

The content should be roughly the same as the announcement.

* Update the Postres wiki as needed

https://wiki.postgresql.org/wiki/Bucardo (may be other pages too)

* PostgreSQL weekly news summary

The maintainers of the weekly news are usually pretty good about catching the update 
and adding it in. If not, bug them.

http://www.postgresql.org/community/weeklynews/

* Tell Greg to post on PlanetPostgresql.

* On the bucardo.org server:

Put the new tarball and tarball.asc file in place
Update the download page
Update any pages that refer to the latest version
Update the latest_release.txt file

* Add the new version to Bugzilla

* Mention on our Facebook page

=====================
== Tips and Tricks ==
=====================

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 test different versions of Bucardo, set two environment variables 
before running the tests:

PGBINDIR: Should be a directory holding Postgres binaries for the version you want, 
especially initdb and pg_config.

LD_LIBRARY_PATH: Should point to the "lib" directory of the Postgres version you 
want. May not be needed if the currently installed version is close enough 
to the one you want to test.

Example:

make clean
export PGBINDIR=/home/greg/code/pg/8.0.26/bin/
export LD_LIBRARY_PATH=/home/greg/code/pg/8.0.26/lib/
prove --blib . t/20-postgres.t