forked from bucardo/bucardo
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.dev
372 lines (229 loc) · 12 KB
/
README.dev
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
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 misused.
* 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 use BucardoTesting.pm 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:
https://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.libera.chat
* 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.
https://postgresweekly.com/
* Tell Greg to post on Planet PostgreSQL: https://planet.postgresql.org/
* 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/13.2/bin/
export LD_LIBRARY_PATH=/home/greg/code/pg/13.2/lib/
prove --blib . t/20-postgres.t