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 code and metadata changes associated with tzdata updates 56 that should be applied to Android's copy of ICU. 57 e.g. see http://bugs.icu-project.org/trac/search?q=2015d 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 cts-tradefed 62 run cts -m CtsLibcoreTestCases 63 run cts -m CtsIcuTestCases 64 (And any others that you think may have been affected) 656) Upload, review, submit the changes from external/icu and system/timezone. 66 67REMINDER: Any prebuilt APEX files containing time zone data files will also 68need to be regenerated. 69 70IANA tools changes 71================== 72 73Occasionally it might be necessary / desirable to update the version of zic 74used to generate Android's tzdata file. For example, if IANA introduce new 75syntax to the text rules files (e.g. asia, north_america, etc.) or adds useful 76command-line arguments to zic. This should be needed very rarely. 77 78It is recommended that this is done independently of a data update to help 79isolate unexpected changes to behavior. 80 81Note that updating the version of zic used to create the tzdata file is 82independent of the copy of zic used by ICU. Also, bionic contains 83a copy of tzcode (e.g. localtime.c) which is based on yet another IANA 84release so compatibility and consistency is a consideration. 85 86The steps for updating IANA tools are similar to updating IANA data except 87you can use "download-iana-files.py --tools" instead of "--data" and testing 88should be more rigorous. 89 90REMINDER: As above, having updated the tooling then all binaries that contain 91tzdata should also be regenerated. e.g. APK and APEX files. 92 93 94Time Zone Data Set Versioning 95============================= 96 97Android needs various files to be updated to take a time zone data update. 98These files come from various sources and we needed a concise shorthand 99to indicate compatibility between a set of files and an Android release. This is 100known as the "Time Zone Data Set Version". Currently we expect to increment this 101version with every dessert release, though this may change in future. 102 103The idea of a single version to describe time zone data updates was first 104introduced in O-MR1 with the concept of a "distro" which could be delivered by 105an APK. The Android time zone "distro" was a zip archive containing the files 106needed to update a device's time zone rules by overlaying files into locations 107in /data. 108 109The "distro" concept has been replaced by an APEX file containing the same data. 110As the APEX contains the same files we continue to use a shorthand version code. 111See apex/ for details. 112 113Time Zone Data Set Versions have a major and minor version number: 114 115- Major version numbers are mutually incompatible. e.g. v2 is not compatible 116 with a v1 or a v3 device. 117- Minor version numbers are backwards compatible. e.g. a v2.2 time zone data set 118 will work on a v2.1 device but not a v2.3 device. 119- The minor version is reset to 1 when the major version is incremented. 120 121The most obvious/common change that can occur between Android releases is an 122ICU upgrade, which currently requires a major version increment: Android uses 123the ICU4C's native file format for both ICU4C and ICU4J time zone code which is 124tied to the ICU major version. The main .dat file used by ICU is held in 125external/icu and will naturally be updated when ICU is updated. Less obviously, 126the time zone data set version code and files must be updated as well. 127 128Other examples of changes that affect format versioning: 129 130Major version increment: 131- A non-backwards compatible change to the tzdata or tzlookup.xml files used 132 by bionic / com/android/i18n/timezone code. 133- Removal of an existing file from the time zone data set. 134 135Minor version increment: 136- Backwards compatible changes: 137 - A new file in the time zone data set. 138 - Additional required data in an existing file (e.g. a backwards compatible 139 change to tzdata / tzlookup.xml). 140 141 142Changing the Time Zone Data Set Version 143--------------------------------------- 144 1451) Modify android_icu4j/libcore_bridge/src/java/com/android/i18n/timezone/TzDataSetVersion.java 146 - CURRENT_FORMAT_MAJOR_VERSION, CURRENT_FORMAT_MINOR_VERSION 1472) Run update-tzdata.py to regenerate the system/timezone/output_data, 148 system/timezone/testing/data, external/icu runtime files and testing equivalents. 1493) Build/flash a device image with the changes and run CTS tests: 150 atest CtsIcuTestCases 1514) Upload, review, submit the changes from system/timezone and external/icu/. 152 153REMINDER: Any prebuilt apks / apex files (i.e. ones that that contain time zone files) 154will also need to be regenerated after this change. 155 156