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
|
NOTE: This information is currently stored as a README
since it does not really have a home in the API reference
documentation and it should be kept close to the actual
test implementation.
Addressbook Contact Data Migration Test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This test subdirectory contains a few components
which make up the Addressbook Data Migration test.
This test is here to ensure that regressions
are not silently introduced where bugs might
occur due to database schema upgrades and
data migrations.
Adding a new version to the migration test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It's recommended to add a new version routinely
as a step in releasing any new stable release
of EDS.
To simply add a new version, follow these
instructions:
o EDS must first be built
o Create new contacts.db using currently built EDS
Use the 'setup-migration' target:
cd evolution-data-server/tests/book-migration
make setup-migration
This will create a new directory with a new contacts.db
file. The created directory will be named:
$(EDS_MAJOR_VERSION).$(EDS_MINOR_VERSION)
For version 3.12 EDS for example this file will be created:
evolution-data-server/tests/book-migration/db/3.12/contacts.db
o Remember to add the new contacts.db:
git add db/3.12/contacts.db
o Remember to add contacts.db to EXTRA_DIST
Edit evolution-data-server/tests/book-migration/db/Makefile.am
and add the new "$(EDS_MAJOR_VERSION).$(EDS_MINOR_VERSION)/contacts.db"
to EXTRA_DIST.
Adding a new condition to pass the tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The test suite which runs for every migrated version of EDS
is defined in test-migration.c, simply add tests to the loop
found in that file and those tests will be run for each
version.
Adding new data to the tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some corner cases it might be impossible to
reproduce a migration bug only by adding a
test case to test-migration.c, if there is
not the right kind of data in the vcards to
reproduce the case.
Please avoid creating bugs which are hard
to track like this... if you need to add
or change the vcards in all of the sandboxes,
it will take you all afternoon.
Instructions to rebuild the sandboxes:
o With a recent version of EDS master, copy
the setup-migration-test.c file and all of
the .vcf files from the vcards/ directory
into some location.
o Modify the .vcf files so they have the
data you need.
o For every major point version from
EDS version 3.0 to $(EDS_MAJOR_VERSION).$(EDS_MINOR_VERSION),
do the following:
o Build and install the given EDS version,
have fun building older versions on newer installations.
o Build the setup-migration-test tool against the newly
installed EDS:
gcc -o setup-migration-test setup-migration-test.c `pkg-config --cflags --libs libebook-1.2`
o Cleanup sandbox where EDS dumps data (this location might vary,
from 3.6 and above you can control it with XDG variables)
o Setup environment:
export XDG_CONFIG_HOME=~/temp_eds
export XDG_DATA_HOME=~/temp_eds
export XDG_CACHE_HOME=~/temp_eds
o Manually run EDS under the new environment:
$(prefix)/libexec/evolution-source-registry &
$(prefix)/libexec/evolution-addressbook-factory -r &
Some versions have differently named daemons, versions
starting from 3.6 have the source registry daemon while
older versions dont have the registry.
o Collect data from ~/temp_eds/evolution/addressbook/...
Pick up the newly created contacts.db and stash it
somewhere so you remember what version it was for
(better just accumulate a directory with 3.0, 3.2, etc
subdirectories where you can collect the data).
For versions 3.0 to 3.6, you need to also collect the
BDB data as well as the sqlite contacts.db.
Instead of holding on to the addressbook.db, use
the db_dump tool to save the addressbook.dump.
Our build scripts will later take care of recreating
an addressbook.db automatically before ever running
the test cases.
Hopefully, you will never have to recreate the history
of addressbooks.
Migration test directory explanation:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ book-migration/
\
+ vcards/
|
+ db/
|\
| + 3.0/ 3.2/ 3.4/ 3.6/ ...
|
+ Makefile.am
|
+ setup-migration-test.c
|
+ test-migration.c
o vcards/
The directory containing the vcards which are expected
to be found in the migrated sandboxes.
o db/
The base directory for sandboxes of previous versions,
for each stable version since 3.0 there is a directory
containing either a contacts.db or a both a contacts.db
and an addressbook.dump file.
The contacts.db is the portable SQLite binary blob created
by inserting the contacts from the vcards/ directory after
having built a given stable version of EDS.
The addressbook.dump files exist for versions 3.6 and
below, those are portable Berkeley DB dump files created
using the db_dump tool from the old addressbook.db files.
o Makefile.am
This makefile includes a 'setup-migration' rule which creates
a new sandbox using the vcards in the vcards/ directory.
This rule is available since the test was added in 3.11
o setup-migration-test.c
A simple stand alone program which creates an addressbook
and inserts some contacts.
This program can be compiled with versions of EDS dating
back to 3.0, so it can potentially be used to repopulate
all of the migration sandboxes from scratch.
While this is a rather painful operation (building each
stable version of EDS), it's possible that we will need
to recreate all of the older sandboxes in the case that
we fix a migration bug but are unable to reproduce the
bug using the data migrated from our set of vcards.
o test-migration.c
The book migration test case. This includes a suite of
basic tests which test EBookClient apis on a freshly
upgraded/migrated addressbook.
As a part of the test fixture for each test, the sandbox
is prepared using the sandboxes in db/.
This test expects that all of the contacts listed in
the vcards/ directory to be present in the freshly
opened and migrated addressbook.
|
