forked from bucardo/bucardo
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.dev
293 lines (182 loc) · 9.87 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
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.
* 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_ctl - The main command-line interface to Bucardo. Contains a version number.
* 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.
* Test files:
BucardoTesting.pm - Shared routines for setup and teardown.
bucard.test.helper - Helper script for bucardo_ctl calling.
bucardo.test.data - Connection information for the tests.
t/00setup.t - Shared code for the Bucardo tests.
t/01bc.t - The main test program.
t/03-goat.t - Test goat access methods.
t/04-pushdelta.t - Test pushdelta syncs.
t/99-perlcritic.t - Uses Perl::Critic to check Bucardo.pm, bucardo_ctl, 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-yaml.t - Uses Test::YAML::Meta to verify the META.yml file.
=============
== 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.
Beta versions (aka release candidates) are the version with an underscore at the end of it. The
tells CPAN not to consider this a "real" release. For example, if the upcoming release is 1.9.3,
the first release candidate would be 1.9.3_1. A second would be 1.9.3_2 etc.
Version numbers are currently set in seven files:
README
Bucardo.pm (two places)
bucardo_ctl
bucardo.schema (two places)
Changes
Makefile.PL
META.yml (two 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 (indicated with **)
* Test on variety of versions (see ** Heavy Testing), including the optional tests.
* Make sure everything is up to date and committed in git.
* Update the versions (see ** Version Numbers) in all relevant files.
* 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.
* Run "perl Makefile.PL"
* 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 (e.g. libpq-fe.h.tmp)
* 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"
* Run "make manifypods". This will create the html docs for Bucardo.pm and bucardo_ctl.
* Update the SIGNATURE file with Module::Signature. This should be done as the
very last step.
* Create a tag for the new version with "git tag".
* Make checksums
Generate md5 and sha1 checksums of the tarball. Include this in your emails.
* Create a new tarball, containing all three modules: Bucardo, DBIx::Safe, and Test::Dynamic.
* Announce to the bucardo-announce list.
* Announce to the pgsql-general 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.
* 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.
=====================
== 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.