1This directory contains code, tools and data related to time zone rules data
2and updates.
3
4Directory structure
5===================
6
7apex
8  - Code related to the Android time zone update APEX file that can be used
9    to update time zone rules on Android devices.
10
11debug_tools
12  - Contains tools useful for debugging time zone issues on Android devices.
13
14input_data
15  - Contains files that provide inputs to the time zone rules update process.
16    Some files come from external sources and some are mastered in Android.
17    See also download-iana-data.py.
18
19input_tools
20  - Contains tools that generate Android time zone files.
21
22output_data
23  - Contains some derived files from the time zone rules update process and
24    used in the Android system image and APEX files. Some files are also held
25    by ICU - see also update-tzdata.py
26
27testing
28  - Contains tools and scripts related to testing time zone update code. See
29    testing/data/README for details.
30
31
32
33Data file update tools
34======================
35
36download-iana-files.py
37  - A helper script run before update-tzdata.py.
38    It downloads the latest tzdata and/or tzcode files from IANA and puts them
39    in the input_data/iana and input_tools/iana directories for use by the
40    update-tzdata.py script. See download-iana-files.py --help for more.
41
42update-tzdata.py
43  - Regenerates the external/icu and system/timezone/output_data timezone
44    data files.
45
46See update instructions below for how these tools are used.
47
48IANA rules data changes
49=======================
50
51When IANA release new time zone rules, the update process is:
52
531) Run "download-iana-files.py --data" to update the input_data/iana file.
542) Make manual modifications to input_data/android files as needed.
553) There are sometimes metadata and/or test changes associated with tzdata updates
56  that should be applied to Android's copy of ICU and CLDR.
57  e.g. see https://unicode-org.atlassian.net/issues/?jql=text%20~%20%222024a%2A%22
584) Run update-tzdata.py to regenerate the system/timezone/output_data,
59  system/timezone/testing/data, external/icu runtime files and testing equivalents.
605) Build/flash a device image with the changes and run CTS:
61    ```
62    $ m cts
63    $ cts-tradefed
64    cts-tf > run cts --include-filter CtsLibcoreTestCases \
65                     --include-filter CtsLibcoreOjTestCases \
66                     --include-filter CtsIcuTestCases \
67                     --include-filter CtsBionicTestCases \
68                     --include-filter CtsTextTestCases \
69                     --include-filter CtsIcu4cTestCases \
70                     --include-filter CtsIcuTestCases
71    ```
72   (And any others that you think may have been affected)
736) Run tests from 5) for every affected Android release.
747) Upload, review, submit the changes from external/icu, external/cldr and system/timezone.
75
76REMINDER: Any prebuilt APEX files containing time zone data files will also
77need to be regenerated.
78
79IANA tools changes
80==================
81
82Occasionally it might be necessary / desirable to update the version of zic
83used to generate Android's tzdata file. For example, if IANA introduce new
84syntax to the text rules files (e.g. asia, north_america, etc.) or adds useful
85command-line arguments to zic. This should be needed very rarely.
86
87It is recommended that this is done independently of a data update to help
88isolate unexpected changes to behavior.
89
90Note that updating the version of zic used to create the tzdata file is
91independent of the copy of zic used by ICU. Also, bionic contains
92a copy of tzcode (e.g. localtime.c) which is different from system/timezone copy used to generate
93TZif files. For consistency and compatibility purposes Android tries to keep them in sync. The
94latter is controversial as IANA tries to be careful to make newer TZif files readable and correctly
95interpreted by older tzcode and vice versa.
96
97The steps for updating IANA tools are similar to updating IANA data except
98you can use "download-iana-files.py --tools" instead of "--data" and testing
99should be more rigorous.
100
101REMINDER: As above, having updated the tooling then all binaries that contain
102tzdata should also be regenerated.
103
104
105Time Zone Data Set Versioning
106=============================
107
108Android needs various files to be updated to take a time zone data update.
109These files come from various sources and we needed a concise shorthand
110to indicate compatibility between a set of files and an Android release. This is
111known as the "Time Zone Data Set Version". Currently we expect to increment this
112version with every dessert release, though this may change in future.
113
114The idea of a single version to describe time zone data updates was first
115introduced in O-MR1 with the concept of a "distro" which could be delivered by
116an APK. The Android time zone "distro" was a zip archive containing the files
117needed to update a device's time zone rules by overlaying files into locations
118in /data.
119
120The "distro" concept has been replaced by an APEX file containing the same data.
121As the APEX contains the same files we continue to use a shorthand version code.
122See apex/ for details.
123
124Starting from Android V the tzdata APEX through the inclusion of tz data set version numbers in the
125file paths can be installed to a range of Android releases.
126
127Time Zone Data Set Versions have a major and minor version number:
128
129- Major version numbers are mutually incompatible. e.g. v2 is not compatible
130  with a v1 or a v3 device.
131- Minor version numbers are backwards compatible. e.g. a v2.2 time zone data set
132  will work on a v2.1 device but not a v2.3 device.
133- The minor version is reset to 1 when the major version is incremented.
134
135Historically, the most obvious/common change that could occur between Android releases was an
136ICU upgrade, which required a major version increment: Android used
137the ICU4C's native file format (.dat file) for both ICU4C and ICU4J time zone code which is
138tied to the ICU major version.
139
140The main .dat file used by ICU is held in external/icu and will naturally be updated when
141ICU is updated. But the time zone data set version code is not necessarily updated as part of ICU
142upgrade any more as from V tzdata now ships .res files which are compatible with older ICU releases.
143
144Other examples of changes that affect format versioning:
145
146Major version increment:
147- A non-backwards compatible change to the tzdata or tzlookup.xml files used
148  by bionic / com/android/i18n/timezone code.
149- Removal of an existing file from the time zone data set.
150
151Minor version increment:
152- Backwards compatible changes:
153  - A new file in the time zone data set.
154  - Additional required data in an existing file (e.g. a backwards compatible
155    change to tzdata / tzlookup.xml).
156
157Versions mapping
158----------------
159
160|Android release|Major version|
161|---------------|-------------|
162|Android V      | 8           |
163|Android U      | 7           |
164|Android T      | 6           |
165|Android SC v2  | 5           |
166|Android S      | 5           |
167|Android R      | 4           |
168|Android Q      | 3           |
169
170In SC v2 neither ICU nor tzcode-s were updated, hence no major version bump.
171
172
173Changing the Time Zone Data Set Version
174---------------------------------------
175
1761) Modify following files:
177    * external/icu/android_icu4j/libcore_bridge/src/java/com/android/i18n/timezone/TzDataSetVersion.java
178      * CURRENT_FORMAT_MAJOR_VERSION and CURRENT_FORMAT_MINOR_VERSION fields.
179    * external/icu/android_icu4j/src/main/java/android/icu/platform/AndroidDataFiles.java
180      * CURRENT_MAJOR_VERSION field.
181    * Version mapping table above.
182    * system/timezone/output_data/icu_overlay/Android.bp and system/timezone/output_data/android/Android.bp.
183      * Update `relative_install_path` in `prebuilt_root_host` targets.
1842) Run update-tzdata.py to regenerate the system/timezone/output_data,
185   system/timezone/testing/data, external/icu runtime files and testing equivalents.
1863) Build/flash a device image with the changes and run tests from "IANA rules data changes" section.
1874) Upload, review, submit the changes from system/timezone, external/icu and external/cldr.
188
189REMINDER: Any prebuilt apks / apex files (i.e. ones that that contain time zone files)
190will also need to be regenerated after this change.
191
192