From: Max Kanat-Alexander <mkanat@bugzilla.org>
Date: Thu, 4 Mar 2010 19:40:55 +0000 (-0500)
Subject: Bug 545299, XML-RPC WebService should take and return dates and times in UTC. POD
X-Git-Tag: bugzilla-3.6rc1~14
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=22f10ba4bdf76bb752a321899631ea38df0ce73f;p=thirdparty%2Fbugzilla.git

Bug 545299, XML-RPC WebService should take and return dates and times in UTC. POD
---

22f10ba4bdf76bb752a321899631ea38df0ce73f
diff --cc Bugzilla/WebService/Bugzilla.pm
index 6e74900b9a,a66871dc67..c7bbf7c046
--- a/Bugzilla/WebService/Bugzilla.pm
+++ b/Bugzilla/WebService/Bugzilla.pm
@@@ -172,9 -168,9 +168,7 @@@ Use L</time> instead
  
  =item B<Description>
  
--Returns the timezone of the server Bugzilla is running on. This is
--important because all dates/times that the webservice interface
--returns will be in this timezone.
++Returns the timezone that Bugzilla expects dates and times in.
  
  =item B<Params> (none)
  
@@@ -183,12 -179,12 +177,21 @@@
  A hash with a single item, C<timezone>, that is the timezone offset as a
  string in (+/-)XXXX (RFC 2822) format.
  
++=item B<History>
++
++=over
++
++=item As of Bugzilla B<3.6>, the timezone returned is always C<+0000>
++(the UTC timezone).
++
++=back
++
  =back
  
  
  =item C<time>
  
--B<UNSTABLE>
++B<EXPERIMENTAL>
  
  =over
  
@@@ -207,8 -203,8 +210,8 @@@ A struct with the following items
  
  =item C<db_time>
  
--C<dateTime> The current time in Bugzilla's B<local time zone>, according 
--to the Bugzilla I<database server>.
++C<dateTime> The current time in UTC, according to the Bugzilla 
++I<database server>.
  
  Note that Bugzilla assumes that the database and the webserver are running
  in the same time zone. However, if the web server and the database server
@@@ -217,8 -213,8 +220,8 @@@ rely on for doing searches and other in
  
  =item C<web_time>
  
--C<dateTime> This is the current time in Bugzilla's B<local time zone>, 
--according to Bugzilla's I<web server>.
++C<dateTime> This is the current time in UTC, according to Bugzilla's 
++I<web server>.
  
  This might be different by a second from C<db_time> since this comes from
  a different source. If it's any more different than a second, then there is
@@@ -227,26 -223,26 +230,23 @@@ rely on the C<db_time>, not the C<web_t
  
  =item C<web_time_utc>
  
--The same as C<web_time>, but in the B<UTC> time zone instead of the local
--time zone.
++Identical to C<web_time>. (Exists only for backwards-compatibility with
++versions of Bugzilla before 3.6.)
  
  =item C<tz_name>
  
--C<string> The long name of the time zone that the Bugzilla web server is 
--in. Will usually look something like: C<America/Los Angeles>
++C<string> The literal string C<UTC>. (Exists only for backwards-compatibility
++with versions of Bugzilla before 3.6.) 
  
  =item C<tz_short_name>
  
--C<string> The "short name" of the time zone that the Bugzilla web server
--is in. This should only be used for display, and not relied on for your
--programs, because different time zones can have the same short name.
--(For example, there are two C<EST>s.)
--
--This will look something like: C<PST>.
++C<string> The literal string C<UTC>. (Exists only for backwards-compatibility
++with versions of Bugzilla before 3.6.)
  
  =item C<tz_offset>
  
--C<string> The timezone offset as a string in (+/-)XXXX (RFC 2822) format.
++C<string> The literal string C<+0000>. (Exists only for backwards-compatibility
++with versions of Bugzilla before 3.6.)
  
  =back
  
@@@ -256,6 -252,6 +256,10 @@@
  
  =item Added in Bugzilla B<3.4>.
  
++=item As of Bugzilla B<3.6>, this method returns all data as though the server
++were in the UTC timezone, instead of returning information in the server's
++local timezone.
++
  =back
  
  =back
diff --cc Bugzilla/WebService/Server/XMLRPC.pm
index f06c81fc77,04e38c4a00..a492266c63
--- a/Bugzilla/WebService/Server/XMLRPC.pm
+++ b/Bugzilla/WebService/Server/XMLRPC.pm
@@@ -288,7 -290,7 +290,9 @@@ API via: C<http://bugzilla.yourdomain.c
  =head1 PARAMETERS
  
  C<dateTime> fields are the standard C<dateTime.iso8601> XML-RPC field. They
--should be in C<YYYY-MM-DDTHH:MM:SS> format (where C<T> is a literal T).
++should be in C<YYYY-MM-DDTHH:MM:SS> format (where C<T> is a literal T). As
++of Bugzilla B<3.6>, Bugzilla always expects C<dateTime> fields to be in the
++UTC timezone, and all returned C<dateTime> values are in the UTC timezone.
  
  All other fields are standard XML-RPC types.
  
@@@ -306,6 -308,6 +310,14 @@@ Normally, XML-RPC does not allow empty 
  C<dateTime.iso8601> fields. Bugzilla does--it treats empty values as
  C<undef> (called C<NULL> or C<None> in some programming languages).
  
++Bugzilla accepts a timezone specifier at the end of C<dateTime.iso8601>
++fields that are specified as method arguments. The format of the timezone
++specifier is specified in the ISO-8601 standard. If no timezone specifier
++is included, the passed-in time is assumed to be in the UTC timezone.
++Bugzilla will never output a timezone specifier on returned data, because
++doing so would violate the XML-RPC specification. All returned times are in
++the UTC timezone.
++
  Bugzilla also accepts an element called C<< <nil> >>, as specified by the
  XML-RPC extension here: L<http://ontosys.com/xml-rpc/extensions.php>, which
  is always considered to be C<undef>, no matter what it contains.