time: document that RFC1123 is wrong for times in UTC

Fixes #13781.

Change-Id: Icfac8f2bfc3a4106f646409cfdc053df1e0cd76a
Reviewed-on: https://go-review.googlesource.com/18314
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/src/time/format.go b/src/time/format.go
index 552887609bb8bb12ec75866b86d7b83919358972..fc2136a3f62aa76c05d92ff6b1ddf32b8719ad55 100644 (file)
--- a/src/time/format.go
+++ b/src/time/format.go
@@ -44,6 +44,13 @@ import "errors"
 //
 // The executable example for time.Format demonstrates the working
 // of the layout string in detail and is a good reference.
+//
+// Note that the RFC822, RFC850, and RFC1123 formats should be applied
+// only to local times. Applying them to UTC times will use "UTC" as the
+// time zone abbreviation, while strictly speaking those RFCs require the
+// use of "GMT" in that case.
+// In general RFC1123Z should be used instead of RFC1123 for servers
+// that insist on that format, and RFC3339 should be preferred for new protocols.
 const (
        ANSIC       = "Mon Jan _2 15:04:05 2006"
        UnixDate    = "Mon Jan _2 15:04:05 MST 2006"