README.android - platform/system/timezone - Git at Google

 This directory contains code, tools and data related to time zone rules data
 and updates.

 Directory structure
 ===================

 apex
   - Code related to the Android time zone update APEX file that can be used
     to update time zone rules on Android devices.

 debug_tools
   - Contains tools useful for debugging time zone issues on Android devices.

 input_data
   - Contains files that provide inputs to the time zone rules update process.
     Some files come from external sources and some are mastered in Android.
     See also download-iana-data.py.

 input_tools
   - Contains tools that generate Android time zone files.

 output_data
   - Contains some derived files from the time zone rules update process and
     used in the Android system image and APEX files. Some files are also held
     by ICU - see also update-tzdata.py

 testing
   - Contains tools and scripts related to testing time zone update code. See
     testing/data/README for details.


 Data file update tools
 ======================

 download-iana-files.py
   - A helper script run before update-tzdata.py.
     It downloads the latest tzdata and/or tzcode files from IANA and puts them
     in the input_data/iana and input_tools/iana directories for use by the
     update-tzdata.py script. See download-iana-files.py --help for more.

 update-tzdata.py
   - Regenerates the external/icu and system/timezone/output_data timezone
     data files.

 See update instructions below for how these tools are used.

 IANA rules data changes
 =======================

 When IANA release new time zone rules, the update process is:

 1) Run "download-iana-files.py --data" to update the input_data/iana file.
 2) Make manual modifications to input_data/android files as needed.
 3) There are sometimes metadata and/or test changes associated with tzdata updates
   that should be applied to Android's copy of ICU and CLDR.
   e.g. see https://unicode-org.atlassian.net/issues/?jql=text%20~%20%222024a%2A%22
 4) Run update-tzdata.py to regenerate the system/timezone/output_data,
   system/timezone/testing/data, external/icu runtime files and testing equivalents.
 5) Build/flash a device image with the changes and run CTS:
     ```
     $ m cts
     $ cts-tradefed
     cts-tf > run cts --include-filter CtsLibcoreTestCases \
                      --include-filter CtsLibcoreOjTestCases \
                      --include-filter CtsIcuTestCases \
                      --include-filter CtsBionicTestCases \
                      --include-filter CtsTextTestCases \
                      --include-filter CtsIcu4cTestCases \
                      --include-filter CtsIcuTestCases
     ```
    (And any others that you think may have been affected)
 6) Run tests from 5) for every affected Android release.
 7) Upload, review, submit the changes from external/icu, external/cldr and system/timezone.

 REMINDER: Any prebuilt APEX files containing time zone data files will also
 need to be regenerated.

 IANA tools changes
 ==================

 Occasionally it might be necessary / desirable to update the version of zic
 used to generate Android's tzdata file. For example, if IANA introduce new
 syntax to the text rules files (e.g. asia, north_america, etc.) or adds useful
 command-line arguments to zic. This should be needed very rarely.

 It is recommended that this is done independently of a data update to help
 isolate unexpected changes to behavior.

 Note that updating the version of zic used to create the tzdata file is
 independent of the copy of zic used by ICU. Also, bionic contains
 a copy of tzcode (e.g. localtime.c) which is different from system/timezone copy used to generate
 TZif files. For consistency and compatibility purposes Android tries to keep them in sync. The
 latter is controversial as IANA tries to be careful to make newer TZif files readable and correctly
 interpreted by older tzcode and vice versa.

 The steps for updating IANA tools are similar to updating IANA data except
 you can use "download-iana-files.py --tools" instead of "--data" and testing
 should be more rigorous.

 REMINDER: As above, having updated the tooling then all binaries that contain
 tzdata should also be regenerated.


 Time Zone Data Set Versioning
 =============================

 Android needs various files to be updated to take a time zone data update.
 These files come from various sources and we needed a concise shorthand
 to indicate compatibility between a set of files and an Android release. This is
 known as the "Time Zone Data Set Version". Currently we expect to increment this
 version with every dessert release, though this may change in future.

 The idea of a single version to describe time zone data updates was first
 introduced in O-MR1 with the concept of a "distro" which could be delivered by
 an APK. The Android time zone "distro" was a zip archive containing the files
 needed to update a device's time zone rules by overlaying files into locations
 in /data.

 The "distro" concept has been replaced by an APEX file containing the same data.
 As the APEX contains the same files we continue to use a shorthand version code.
 See apex/ for details.

 Starting from Android V the tzdata APEX through the inclusion of tz data set version numbers in the
 file paths can be installed to a range of Android releases.

 Time Zone Data Set Versions have a major and minor version number:

 - Major version numbers are mutually incompatible. e.g. v2 is not compatible
   with a v1 or a v3 device.
 - Minor version numbers are backwards compatible. e.g. a v2.2 time zone data set
   will work on a v2.1 device but not a v2.3 device.
 - The minor version is reset to 1 when the major version is incremented.

 Historically, the most obvious/common change that could occur between Android releases was an
 ICU upgrade, which required a major version increment: Android used
 the ICU4C's native file format (.dat file) for both ICU4C and ICU4J time zone code which is
 tied to the ICU major version.

 The main .dat file used by ICU is held in external/icu and will naturally be updated when
 ICU is updated. But the time zone data set version code is not necessarily updated as part of ICU
 upgrade any more as from V tzdata now ships .res files which are compatible with older ICU releases.

 Other examples of changes that affect format versioning:

 Major version increment:
 - A non-backwards compatible change to the tzdata or tzlookup.xml files used
   by bionic / com/android/i18n/timezone code.
 - Removal of an existing file from the time zone data set.

 Minor version increment:
 - Backwards compatible changes:
   - A new file in the time zone data set.
   - Additional required data in an existing file (e.g. a backwards compatible
     change to tzdata / tzlookup.xml).

 Versions mapping
 ----------------

 |Android release|Major version|
 |---------------|-------------|
 |Android V      | 8           |
 |Android U      | 7           |
 |Android T      | 6           |
 |Android SC v2  | 5           |
 |Android S      | 5           |
 |Android R      | 4           |
 |Android Q      | 3           |

 In SC v2 neither ICU nor tzcode-s were updated, hence no major version bump.


 Changing the Time Zone Data Set Version
 ---------------------------------------

 1) Modify following files:
     * external/icu/android_icu4j/libcore_bridge/src/java/com/android/i18n/timezone/TzDataSetVersion.java
       * CURRENT_FORMAT_MAJOR_VERSION and CURRENT_FORMAT_MINOR_VERSION fields.
     * external/icu/android_icu4j/src/main/java/android/icu/platform/AndroidDataFiles.java
       * CURRENT_MAJOR_VERSION field.
     * Version mapping table above.
     * system/timezone/output_data/icu_overlay/Android.bp and system/timezone/output_data/android/Android.bp.
       * Update `relative_install_path` in `prebuilt_root_host` targets.
 2) Run update-tzdata.py to regenerate the system/timezone/output_data,
    system/timezone/testing/data, external/icu runtime files and testing equivalents.
 3) Build/flash a device image with the changes and run tests from "IANA rules data changes" section.
 4) Upload, review, submit the changes from system/timezone, external/icu and external/cldr.

 REMINDER: Any prebuilt apks / apex files (i.e. ones that that contain time zone files)
 will also need to be regenerated after this change.
	This directory contains code, tools and data related to time zone rules data
	and updates.

	Directory structure
	===================

	apex
	- Code related to the Android time zone update APEX file that can be used
	to update time zone rules on Android devices.

	debug_tools
	- Contains tools useful for debugging time zone issues on Android devices.

	input_data
	- Contains files that provide inputs to the time zone rules update process.
	Some files come from external sources and some are mastered in Android.
	See also download-iana-data.py.

	input_tools
	- Contains tools that generate Android time zone files.

	output_data
	- Contains some derived files from the time zone rules update process and
	used in the Android system image and APEX files. Some files are also held
	by ICU - see also update-tzdata.py

	testing
	- Contains tools and scripts related to testing time zone update code. See
	testing/data/README for details.



	Data file update tools
	======================

	download-iana-files.py
	- A helper script run before update-tzdata.py.
	It downloads the latest tzdata and/or tzcode files from IANA and puts them
	in the input_data/iana and input_tools/iana directories for use by the
	update-tzdata.py script. See download-iana-files.py --help for more.

	update-tzdata.py
	- Regenerates the external/icu and system/timezone/output_data timezone
	data files.

	See update instructions below for how these tools are used.

	IANA rules data changes
	=======================

	When IANA release new time zone rules, the update process is:

	1) Run "download-iana-files.py --data" to update the input_data/iana file.
	2) Make manual modifications to input_data/android files as needed.
	3) There are sometimes metadata and/or test changes associated with tzdata updates
	that should be applied to Android's copy of ICU and CLDR.
	e.g. see https://unicode-org.atlassian.net/issues/?jql=text%20~%20%222024a%2A%22
	4) Run update-tzdata.py to regenerate the system/timezone/output_data,
	system/timezone/testing/data, external/icu runtime files and testing equivalents.
	5) Build/flash a device image with the changes and run CTS:
	```
	$ m cts
	$ cts-tradefed
	cts-tf > run cts --include-filter CtsLibcoreTestCases \
	--include-filter CtsLibcoreOjTestCases \
	--include-filter CtsIcuTestCases \
	--include-filter CtsBionicTestCases \
	--include-filter CtsTextTestCases \
	--include-filter CtsIcu4cTestCases \
	--include-filter CtsIcuTestCases
	```
	(And any others that you think may have been affected)
	6) Run tests from 5) for every affected Android release.
	7) Upload, review, submit the changes from external/icu, external/cldr and system/timezone.

	REMINDER: Any prebuilt APEX files containing time zone data files will also
	need to be regenerated.

	IANA tools changes
	==================

	Occasionally it might be necessary / desirable to update the version of zic
	used to generate Android's tzdata file. For example, if IANA introduce new
	syntax to the text rules files (e.g. asia, north_america, etc.) or adds useful
	command-line arguments to zic. This should be needed very rarely.

	It is recommended that this is done independently of a data update to help
	isolate unexpected changes to behavior.

	Note that updating the version of zic used to create the tzdata file is
	independent of the copy of zic used by ICU. Also, bionic contains
	a copy of tzcode (e.g. localtime.c) which is different from system/timezone copy used to generate
	TZif files. For consistency and compatibility purposes Android tries to keep them in sync. The
	latter is controversial as IANA tries to be careful to make newer TZif files readable and correctly
	interpreted by older tzcode and vice versa.

	The steps for updating IANA tools are similar to updating IANA data except
	you can use "download-iana-files.py --tools" instead of "--data" and testing
	should be more rigorous.

	REMINDER: As above, having updated the tooling then all binaries that contain
	tzdata should also be regenerated.


	Time Zone Data Set Versioning
	=============================

	Android needs various files to be updated to take a time zone data update.
	These files come from various sources and we needed a concise shorthand
	to indicate compatibility between a set of files and an Android release. This is
	known as the "Time Zone Data Set Version". Currently we expect to increment this
	version with every dessert release, though this may change in future.

	The idea of a single version to describe time zone data updates was first
	introduced in O-MR1 with the concept of a "distro" which could be delivered by
	an APK. The Android time zone "distro" was a zip archive containing the files
	needed to update a device's time zone rules by overlaying files into locations
	in /data.

	The "distro" concept has been replaced by an APEX file containing the same data.
	As the APEX contains the same files we continue to use a shorthand version code.
	See apex/ for details.

	Starting from Android V the tzdata APEX through the inclusion of tz data set version numbers in the
	file paths can be installed to a range of Android releases.

	Time Zone Data Set Versions have a major and minor version number:

	- Major version numbers are mutually incompatible. e.g. v2 is not compatible
	with a v1 or a v3 device.
	- Minor version numbers are backwards compatible. e.g. a v2.2 time zone data set
	will work on a v2.1 device but not a v2.3 device.
	- The minor version is reset to 1 when the major version is incremented.

	Historically, the most obvious/common change that could occur between Android releases was an
	ICU upgrade, which required a major version increment: Android used
	the ICU4C's native file format (.dat file) for both ICU4C and ICU4J time zone code which is
	tied to the ICU major version.

	The main .dat file used by ICU is held in external/icu and will naturally be updated when
	ICU is updated. But the time zone data set version code is not necessarily updated as part of ICU
	upgrade any more as from V tzdata now ships .res files which are compatible with older ICU releases.

	Other examples of changes that affect format versioning:

	Major version increment:
	- A non-backwards compatible change to the tzdata or tzlookup.xml files used
	by bionic / com/android/i18n/timezone code.
	- Removal of an existing file from the time zone data set.

	Minor version increment:
	- Backwards compatible changes:
	- A new file in the time zone data set.
	- Additional required data in an existing file (e.g. a backwards compatible
	change to tzdata / tzlookup.xml).

	Versions mapping
	----------------

	\|Android release\|Major version\|
	\|---------------\|-------------\|
	\|Android V \| 8 \|
	\|Android U \| 7 \|
	\|Android T \| 6 \|
	\|Android SC v2 \| 5 \|
	\|Android S \| 5 \|
	\|Android R \| 4 \|
	\|Android Q \| 3 \|

	In SC v2 neither ICU nor tzcode-s were updated, hence no major version bump.


	Changing the Time Zone Data Set Version
	---------------------------------------

	1) Modify following files:
	* external/icu/android_icu4j/libcore_bridge/src/java/com/android/i18n/timezone/TzDataSetVersion.java
	* CURRENT_FORMAT_MAJOR_VERSION and CURRENT_FORMAT_MINOR_VERSION fields.
	* external/icu/android_icu4j/src/main/java/android/icu/platform/AndroidDataFiles.java
	* CURRENT_MAJOR_VERSION field.
	* Version mapping table above.
	* system/timezone/output_data/icu_overlay/Android.bp and system/timezone/output_data/android/Android.bp.
	* Update `relative_install_path` in `prebuilt_root_host` targets.
	2) Run update-tzdata.py to regenerate the system/timezone/output_data,
	system/timezone/testing/data, external/icu runtime files and testing equivalents.
	3) Build/flash a device image with the changes and run tests from "IANA rules data changes" section.
	4) Upload, review, submit the changes from system/timezone, external/icu and external/cldr.

	REMINDER: Any prebuilt apks / apex files (i.e. ones that that contain time zone files)
	will also need to be regenerated after this change.