From: Brad Fitzpatrick <bradfitz@golang.org>
Date: Sun, 5 Jul 2015 17:00:14 +0000 (-0700)
Subject: doc: add section about standard library to the FAQ
X-Git-Tag: go1.5beta2~91
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=8a28242b5f7c20d0e215ea9996fa3c5171ee14fb;p=gostls13.git

doc: add section about standard library to the FAQ

Fixes #10246

Change-Id: Ifa698232a09e1c37f3a9340ffdc1f2650c06fe4c
Reviewed-on: https://go-review.googlesource.com/11900
Reviewed-by: Rob Pike <r@golang.org>
---

diff --git a/doc/go_faq.html b/doc/go_faq.html
index 78a96568bc..f61e24a662 100644
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -1591,6 +1591,51 @@ test cases. The standard Go library is full of illustrative examples, such as in
 <a href="/src/fmt/fmt_test.go">the formatting tests for the <code>fmt</code> package</a>.
 </p>
 
+<h3 id="x_in_std">
+Why isn't <i>X</i> in the standard library?</h3>
+
+<p>
+The standard library's purpose is to support the runtime, connect to
+the operating system, and provide key functionality that many Go
+programs require, such as formatted I/O and networking.
+It also contains elements important for web programming, including
+cryptography and support for standards like HTTP, JSON, and XML.
+</p>
+
+<p>
+There is no clear criterion that defines what is included because for
+a long time, this was the <i>only</i> Go library.
+There are criteria that define what gets added today, however.
+</p>
+
+<p>
+New additions to the standard library are rare and the bar for
+inclusion is high.
+Code included in the standard library bears a large ongoing maintenance cost
+(often borne by those other than the original author),
+is subject to the <a href="/doc/go1compat.html">Go 1 compatibility promise</a>
+(blocking fixes to any flaws in the API),
+and is subject to the Go
+<a href="https://golang.org/s/releasesched">release schedule</a>,
+preventing bug fixes from being available to users quickly.
+</p>
+
+<p>
+Most new code should live outside of the standard library and be accessible
+via the <a href="/cmd/go/"><code>go</code> tool</a>'s
+<code>go get</code> command.
+Such code can have its own maintainers, release cycle,
+and compatibility guarantees.
+Users can find packages and read their documentation at
+<a href="https://godoc.org/">godoc.org</a>.
+</p>
+
+<p>
+Although there are pieces in the standard library that don't really belong,
+such as <code>log/syslog</code>, we continue to maintain everything in the
+library because of the Go 1 compatibility promise.
+But we encourage most new code to live elsewhere.
+</p>
 
 <h2 id="Implementation">Implementation</h2>