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/50-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 " * 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" https://www.postgresql.org/account/news/new/ The content should be roughly the same as the announcement. * Update the Postgres 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