content: convert to Markdown-enabled present inputs
Converted blog to Markdown-enabled present (CL 222846)
using present2md (CL 222847).
For golang/go#33955.
Change-Id: Ib39fa1ddd9a46f9c7a62a2ca7b96e117635553e8
Reviewed-on: https://go-review.googlesource.com/c/blog/+/222848
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>
diff --git a/content/10years.article b/content/10years.article
index 4a33db0..f67c343 100644
--- a/content/10years.article
+++ b/content/10years.article
@@ -1,22 +1,23 @@
-Go Turns 10
+# Go Turns 10
8 Nov 2019
+Summary: Happy birthday, Go!
Russ Cox, for the Go team
rsc@golang.org
-* Introduction
+##
Happy birthday, Go!
This weekend we celebrate the 10th anniversary of
-[[https://opensource.googleblog.com/2009/11/hey-ho-lets-go.html][the Go release]],
+[the Go release](https://opensource.googleblog.com/2009/11/hey-ho-lets-go.html),
marking the 10th birthday of Go as an open-source programming language
and ecosystem for building modern networked software.
To mark the occasion,
-[[https://twitter.com/reneefrench][Renee French]],
+[Renee French](https://twitter.com/reneefrench),
the creator of the
-[[https://blog.golang.org/gopher][Go gopher]],
+[Go gopher](https://blog.golang.org/gopher),
painted this delightful scene:
.html 10years/img1.html
@@ -46,14 +47,14 @@
I wondered: where would Go be after a decade?
Today, we can answer that question:
-Go is everywhere, used by at least [[https://research.swtch.com/gophercount][a million developers worldwide]].
+Go is everywhere, used by at least [a million developers worldwide](https://research.swtch.com/gophercount).
Go’s original target was networked system infrastructure,
what we now call cloud software.
Every major cloud provider today uses core cloud infrastructure written in Go,
such as Docker, Etcd, Istio, Kubernetes, Prometheus, and Terraform;
the majority of the
-[[https://www.cncf.io/projects/][Cloud Native Computing Foundation’s projects]]
+[Cloud Native Computing Foundation’s projects](https://www.cncf.io/projects/)
are written in Go.
Countless companies are using Go to move their own work to the cloud as well,
from startups building from scratch
@@ -62,9 +63,9 @@
with uses ranging
from
controlling tiny embedded systems with
-[[https://gobot.io][GoBot]] and [[https://tinygo.org/][TinyGo]]
+[GoBot](https://gobot.io) and [TinyGo](https://tinygo.org/)
to detecting cancer with
-[[https://medium.com/grail-eng/bigslice-a-cluster-computing-system-for-go-7e03acd2419b][massive big data analysis and machine learning at GRAIL]],
+[massive big data analysis and machine learning at GRAIL](https://medium.com/grail-eng/bigslice-a-cluster-computing-system-for-go-7e03acd2419b),
and everything in between.
All this is to say that Go has succeeded beyond our wildest dreams.
@@ -85,8 +86,8 @@
with fantastic tooling,
a production-quality implementation,
a
-[[https://blog.golang.org/ismmkeynote][state-of-the-art garbage collector]],
-and [[https://golang.org/doc/install/source#introduction][ports to 12 operating systems and 10 architectures]].
+[state-of-the-art garbage collector](https://blog.golang.org/ismmkeynote),
+and [ports to 12 operating systems and 10 architectures](https://golang.org/doc/install/source#introduction).
Any programming language needs the support of a thriving ecosystem.
The open source release was the seed for that ecosystem,
@@ -98,10 +99,10 @@
Of course, the ecosystem needs the support of a thriving community.
In 2019 there are dozens of Go conferences all over the world,
along with
-[[https://www.meetup.com/pro/go][over 150 Go meetup groups with over 90,000 members]].
-[[https://golangbridge.org][GoBridge]]
+[over 150 Go meetup groups with over 90,000 members](https://www.meetup.com/pro/go).
+[GoBridge](https://golangbridge.org)
and
-[[https://medium.com/@carolynvs/www-loves-gobridge-ccb26309f667][Women Who Go]]
+[Women Who Go](https://medium.com/@carolynvs/www-loves-gobridge-ccb26309f667)
help bring new voices into the Go community,
through mentoring, training, and conference scholarships.
This year alone, they have taught
@@ -109,7 +110,7 @@
at workshops where community members teach and mentor those new to Go.
There are
-[[https://research.swtch.com/gophercount][over a million Go developers]]
+[over a million Go developers](https://research.swtch.com/gophercount)
worldwide,
and companies all over the globe are looking to hire more.
In fact, people often tell us that learning Go
@@ -121,7 +122,7 @@
and we are thrilled that Go has helped so many others.
As
-[[https://twitter.com/search?q=%23GoTurns10][#GoTurns10]],
+[\#GoTurns10](https://twitter.com/search?q=%23GoTurns10),
I hope everyone will take a moment to celebrate
the Go community and all we have achieved.
On behalf of the entire Go team at Google,
diff --git a/content/4years.article b/content/4years.article
index 4122617..9bfe92c 100644
--- a/content/4years.article
+++ b/content/4years.article
@@ -1,10 +1,11 @@
-Four years of Go
+# Four years of Go
10 Nov 2013
Tags: community, birthday
+Summary: Today marks the fourth anniversary of Go as an open source project.
Andrew Gerrand
-* Introduction
+##
Today marks the fourth anniversary of Go as an open source project.
@@ -19,7 +20,7 @@
.image 4years-graph.png
This chart shows the growth of Google searches for the term
-"[[http://www.google.com/trends/explore?hl=en-US#q=golang&date=10/2009+50m&cmpt=q][golang]]"
+"[golang](http://www.google.com/trends/explore?hl=en-US#q=golang&date=10/2009+50m&cmpt=q)"
over the past four years.
Notice the knee in the curve around March 2012, when Go 1.0 was released.
If these searches are a decent proxy for interest, then it's clear that
@@ -29,104 +30,104 @@
But where is the interest coming from?
The open source community has embraced Go,
-with our community wiki listing [[https://golang.org/wiki/Projects][hundreds of Go projects]]. Some popular ones:
+with our community wiki listing [hundreds of Go projects](https://golang.org/wiki/Projects). Some popular ones:
-- [[http://docker.io][Docker]] is a tool for packaging and running applications
- in lightweight containers.
- Docker makes it easy to isolate, package,
- and deploy applications, and is beloved by system administrators.
- Its creator Solomon Hykes cited Go's standard library,
- concurrency primitives, and ease of deployment as key factors,
- and said "To put it simply, if Docker had not been written in Go,
- it would not have been as successful."
+ - [Docker](http://docker.io) is a tool for packaging and running applications
+ in lightweight containers.
+ Docker makes it easy to isolate, package,
+ and deploy applications, and is beloved by system administrators.
+ Its creator Solomon Hykes cited Go's standard library,
+ concurrency primitives, and ease of deployment as key factors,
+ and said "To put it simply, if Docker had not been written in Go,
+ it would not have been as successful."
-- [[http://packer.io][Packer]] is a tool for automating the creation of
- machine images for deployment to virtual machines or cloud services.
- Its author, Mitchell Hashimoto, is now working on another Go project,
- [[http://www.serfdom.io/][serf]], a decentralized discovery service.
- Like Docker, these projects help with management of large-scale,
- cluster-based services.
+ - [Packer](http://packer.io) is a tool for automating the creation of
+ machine images for deployment to virtual machines or cloud services.
+ Its author, Mitchell Hashimoto, is now working on another Go project,
+ [serf](http://www.serfdom.io/), a decentralized discovery service.
+ Like Docker, these projects help with management of large-scale,
+ cluster-based services.
-- [[http://bit.ly][Bitly]]'s [[http://bitly.github.io/nsq/][NSQ]] is a realtime
- distributed messaging platform designed for fault-tolerance and high-availability,
- and is used in production at bitly and a bunch of other companies.
+ - [Bitly](http://bit.ly)'s [NSQ](http://bitly.github.io/nsq/) is a realtime
+ distributed messaging platform designed for fault-tolerance and high-availability,
+ and is used in production at bitly and a bunch of other companies.
-- [[http://canonical.com/][Canonical]]'s [[https://juju.ubuntu.com/][JuJu]]
- infrastructure automation system was rewritten in Go.
- Project lead Gustavo Niemeyer said "It's not a single aspect of Go that
- makes it a compelling choice,
- but rather the careful organization of well-crafted small pieces."
+ - [Canonical](http://canonical.com/)'s [JuJu](https://juju.ubuntu.com/)
+ infrastructure automation system was rewritten in Go.
+ Project lead Gustavo Niemeyer said "It's not a single aspect of Go that
+ makes it a compelling choice,
+ but rather the careful organization of well-crafted small pieces."
-- The [[https://github.com/goraft/raft][raft]] package provides an implementation
- of the [[https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf][Raft]]
- distributed consensus protocol.
- It is the basis of Go projects like [[https://github.com/coreos/etcd][etcd]]
- and [[https://github.com/skynetservices/skydns][SkyDNS]].
+ - The [raft](https://github.com/goraft/raft) package provides an implementation
+ of the [Raft](https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf)
+ distributed consensus protocol.
+ It is the basis of Go projects like [etcd](https://github.com/coreos/etcd)
+ and [SkyDNS](https://github.com/skynetservices/skydns).
-- Other popular projects include [[https://github.com/biogo/biogo][biogo]],
- the [[http://www.gorillatoolkit.org/][Gorilla Web Toolkit]],
- [[https://github.com/golang/groupcache][groupcache]],
- Mozilla's [[https://github.com/mozilla-services/heka][heka]],
- the [[https://github.com/cznic/kv][kv]] and [[https://github.com/cznic/ql][ql]]
- lightweight storage systems,
- and the [[http://skydb.io/][Sky]] behavioral database.
+ - Other popular projects include [biogo](https://github.com/biogo/biogo),
+ the [Gorilla Web Toolkit](http://www.gorillatoolkit.org/),
+ [groupcache](https://github.com/golang/groupcache),
+ Mozilla's [heka](https://github.com/mozilla-services/heka),
+ the [kv](https://github.com/cznic/kv) and [ql](https://github.com/cznic/ql)
+ lightweight storage systems,
+ and the [Sky](http://skydb.io/) behavioral database.
But this is just the tip of the iceberg. The number of high-quality open
source Go projects is phenomenal.
-Prolific Go hacker [[http://xph.us/software/][Keith Rarick]] put it well:
+Prolific Go hacker [Keith Rarick](http://xph.us/software/) put it well:
"The state of the Go ecosystem after only four years is astounding.
Compare Go in 2013 to Python in 1995 or Java in 1999. Or C++ in 1987!"
-Businesses are enjoying Go, too. The [[https://golang.org/wiki/GoUsers][Go Users wiki page]]
+Businesses are enjoying Go, too. The [Go Users wiki page](https://golang.org/wiki/GoUsers)
lists dozens of success stories (and if you use Go,
please add yourself to it). Some examples:
-- [[https://blog.cloudflare.com/go-at-cloudflare][CloudFlare]] built their
- distributed DNS service entirely with Go,
- and are in the process of migrating their gigabytes-per-minute logging infrastructure to the language.
- Programmer John Graham-Cumming said "We've found Go to be the perfect match for our needs:
- the combination of familiar syntax, a powerful type system,
- a strong network library and built-in concurrency means that more and more
- projects are being built here in Go."
+ - [CloudFlare](https://blog.cloudflare.com/go-at-cloudflare) built their
+ distributed DNS service entirely with Go,
+ and are in the process of migrating their gigabytes-per-minute logging infrastructure to the language.
+ Programmer John Graham-Cumming said "We've found Go to be the perfect match for our needs:
+ the combination of familiar syntax, a powerful type system,
+ a strong network library and built-in concurrency means that more and more
+ projects are being built here in Go."
-- [[http://soundcloud.com][SoundCloud]] is an audio distribution service
- that has "dozens of [[http://backstage.soundcloud.com/2012/07/go-at-soundcloud/][systems in Go]],
- touching almost every part of the site, and in many cases powering features
- from top to bottom." Engineer Peter Bourgon said "Go demonstrates that the
- cruft that burdens other languages and ecosystems—stuff that developers
- have learned to deal with,
- often in anger—is simply not a necessary part of modern programming.
- With Go, I have a straightforward and non-adversarial relationship with my tools,
- from development to production."
+ - [SoundCloud](http://soundcloud.com) is an audio distribution service
+ that has "dozens of [systems in Go](http://backstage.soundcloud.com/2012/07/go-at-soundcloud/),
+ touching almost every part of the site, and in many cases powering features
+ from top to bottom." Engineer Peter Bourgon said "Go demonstrates that the
+ cruft that burdens other languages and ecosystems—stuff that developers
+ have learned to deal with,
+ often in anger—is simply not a necessary part of modern programming.
+ With Go, I have a straightforward and non-adversarial relationship with my tools,
+ from development to production."
-- The [[https://ngrok.com/][ngrok]] service allows web developers to provide
- remote access to their development environments.
- Its author Alan Shreve said that "ngrok's success as a project is due in
- no small part to choosing Go as the implementation language," citing Go's HTTP libraries,
- efficiency, cross-platform compatibility,
- and ease of deployment as the major benefits.
+ - The [ngrok](https://ngrok.com/) service allows web developers to provide
+ remote access to their development environments.
+ Its author Alan Shreve said that "ngrok's success as a project is due in
+ no small part to choosing Go as the implementation language," citing Go's HTTP libraries,
+ efficiency, cross-platform compatibility,
+ and ease of deployment as the major benefits.
-- [[http://poptip.com][Poptip]] provides social analytics services,
- and product engineer Andy Bonventre said "What started as an experiment
- in writing a single service in Go turned into moving almost our entire infrastructure over to it.
- What I love about Go the most is not necessarily the features of the language,
- but the focus on tooling, testing, and other elements that make writing
- large applications much more manageable."
+ - [Poptip](http://poptip.com) provides social analytics services,
+ and product engineer Andy Bonventre said "What started as an experiment
+ in writing a single service in Go turned into moving almost our entire infrastructure over to it.
+ What I love about Go the most is not necessarily the features of the language,
+ but the focus on tooling, testing, and other elements that make writing
+ large applications much more manageable."
-- Music collaboration startup [[http://splice.com][Splice]] chose to build
- their service with Go.
- Co-founder Matt Aimonetti said "We seriously studied and considered many
- programming languages,
- but Go's simplicity, efficiency, philosophy and community won us over."
+ - Music collaboration startup [Splice](http://splice.com) chose to build
+ their service with Go.
+ Co-founder Matt Aimonetti said "We seriously studied and considered many
+ programming languages,
+ but Go's simplicity, efficiency, philosophy and community won us over."
-- And, of course, engineering teams across Google are moving to Go.
- Engineer Matt Welsh recently [[http://matt-welsh.blogspot.com.au/2013/08/rewriting-large-production-system-in-go.html][shared his experience]]
- rewriting a large production service in Go.
- Other notable public examples include YouTube's [[https://github.com/youtube/vitess][vitess project]]
- and [[https://talks.golang.org/2013/oscon-dl.slide][dl.google.com]].
- We hope to share more stories like these soon.
+ - And, of course, engineering teams across Google are moving to Go.
+ Engineer Matt Welsh recently [shared his experience](http://matt-welsh.blogspot.com.au/2013/08/rewriting-large-production-system-in-go.html)
+ rewriting a large production service in Go.
+ Other notable public examples include YouTube's [vitess project](https://github.com/youtube/vitess)
+ and [dl.google.com](https://talks.golang.org/2013/oscon-dl.slide).
+ We hope to share more stories like these soon.
-In September 2012, [[http://apcera.com/][Apcera]] CEO Derek Collison [[https://twitter.com/derekcollison/status/245522124666716160][predicted]]
+In September 2012, [Apcera](http://apcera.com/) CEO Derek Collison [predicted](https://twitter.com/derekcollison/status/245522124666716160)
that "Go will become the dominant language for systems work in [Infastructure-as-a-Service],
Orchestration, and [Platform-as-a-Service] in 24 months." Looking at the list above,
it's easy to believe that prediction.
@@ -134,25 +135,25 @@
So how can you get involved? Whether you're a seasoned Go programmer or just Go-curious,
there are many ways to get started in the Go community:
-- [[https://blog.golang.org/getthee-to-go-meetup][Join your nearest Go User Group]],
- where your local gophers meet to share their knowledge and experience.
- These groups are popping up all over the world.
- I have personally spoken at Go groups in Amsterdam,
- Berlin, Gothenburg, London, Moscow, Munich,
- New York City, Paris, San Francisco, Seoul,
- Stockholm, Sydney, Tokyo, and Warsaw;
- but there are [[https://golang.org/wiki/GoUserGroups][many more]]!
+ - [Join your nearest Go User Group](https://blog.golang.org/getthee-to-go-meetup),
+ where your local gophers meet to share their knowledge and experience.
+ These groups are popping up all over the world.
+ I have personally spoken at Go groups in Amsterdam,
+ Berlin, Gothenburg, London, Moscow, Munich,
+ New York City, Paris, San Francisco, Seoul,
+ Stockholm, Sydney, Tokyo, and Warsaw;
+ but there are [many more](https://golang.org/wiki/GoUserGroups)!
-- Create or contribute to an open source Go project (or [[https://golang.org/doc/contribute.html][to Go itself]]).
- (And if you're building something, we'd love to hear from you on the [[http://groups.google.com/group/golang-nuts][Go mailing list]].)
+ - Create or contribute to an open source Go project (or [to Go itself](https://golang.org/doc/contribute.html)).
+ (And if you're building something, we'd love to hear from you on the [Go mailing list](http://groups.google.com/group/golang-nuts).)
-- If you're in Europe in February 2014, come along to the [[https://code.google.com/p/go-wiki/wiki/Fosdem2014][Go Devroom]]
- at [[https://fosdem.org/2014/][FOSDEM 2014]].
+ - If you're in Europe in February 2014, come along to the [Go Devroom](https://code.google.com/p/go-wiki/wiki/Fosdem2014)
+ at [FOSDEM 2014](https://fosdem.org/2014/).
-- Attend [[http://gophercon.com][GopherCon]],
- the first major Go conference, in Denver in April 2014.
- The event is organized by the [[http://www.gopheracademy.com][Gopher Academy]],
- who also run a [[http://www.gopheracademy.com/jobs][Go job board]].
+ - Attend [GopherCon](http://gophercon.com),
+ the first major Go conference, in Denver in April 2014.
+ The event is organized by the [Gopher Academy](http://www.gopheracademy.com),
+ who also run a [Go job board](http://www.gopheracademy.com/jobs).
The Go team has been amazed by the growth of the Go community over the past
four years. We are thrilled to see so many great things being built with Go,
diff --git a/content/5years.article b/content/5years.article
index 4817f6c..9b5f3b2 100644
--- a/content/5years.article
+++ b/content/5years.article
@@ -1,14 +1,15 @@
-Half a decade with Go
+# Half a decade with Go
10 Nov 2014
+Summary: Five years ago we launched the Go project. It seems like only yesterday that we were preparing the initial public release: our [website](https://web.archive.org/web/20091112094121/http://golang.org/) was a lovely shade of yellow, we were calling Go a "systems language", and you had to terminate statements with a semicolon and write Makefiles to build your code. We had no idea how Go would be received. Would people share our vision and goals? Would people find Go useful?
Andrew Gerrand
adg@golang.org
-* Introduction
+##
Five years ago we launched the Go project. It seems like only yesterday that we
were preparing the initial public release: our
-[[https://web.archive.org/web/20091112094121/http://golang.org/][website]] was
+[website](https://web.archive.org/web/20091112094121/http://golang.org/) was
a lovely shade of yellow, we were calling Go a "systems language", and you had
to terminate statements with a semicolon and write Makefiles to build your
code. We had no idea how Go would be received. Would people share our vision
@@ -23,47 +24,47 @@
.image 5years/gophers5th.jpg _ 850
-[[/gopher][_Gopher_]] _illustration_by_ [[http://reneefrench.blogspot.com.au/][_Renee_French_]]
+[_Gopher_](/gopher) _illustration by_ [_Renee French_](http://reneefrench.blogspot.com.au/)
After the initial release, it took us a while to properly communicate the
goals and design ethos behind Go. Rob Pike did so eloquently in his 2012 essay
-[[https://talks.golang.org/2012/splash.article][_Go_at_Google:_Language_Design_in_the_Service_of_Software_Engineering_]] and
+[_Go at Google: Language Design in the Service of Software Engineering_](https://talks.golang.org/2012/splash.article) and
more personally in his blog post
-[[https://commandcenter.blogspot.com.au/2012/06/less-is-exponentially-more.html][_Less_is_exponentially_more_]].
+[_Less is exponentially more_](https://commandcenter.blogspot.com.au/2012/06/less-is-exponentially-more.html).
Andrew Gerrand's
-[[http://vimeo.com/53221560][_Code_that_grows_with_grace_]]
-([[https://talks.golang.org/2012/chat.slide][slides]]) and
-[[https://www.youtube.com/watch?v=dKGmK_Z1Zl0][_Go_for_Gophers_]]
-([[https://talks.golang.org/2014/go4gophers.slide][slides]]) give a
+[_Code that grows with grace_](http://vimeo.com/53221560)
+([slides](https://talks.golang.org/2012/chat.slide)) and
+[_Go for Gophers_](https://www.youtube.com/watch?v=dKGmK_Z1Zl0)
+([slides](https://talks.golang.org/2014/go4gophers.slide)) give a
more in-depth, technical take on Go's design philosophy.
Over time, the few became many. The turning point for the project was the
release of Go 1 in March 2012, which provided a stable language and standard
library that developers could trust. By 2014, the project had hundreds of core
-contributors, the ecosystem had countless [[https://godoc.org/][libraries and tools]]
+contributors, the ecosystem had countless [libraries and tools](https://godoc.org/)
maintained by thousands of developers, and the greater community had
many passionate members (or, as we call them, "gophers"). Today, by our current
metrics, the Go community is growing faster than we believed possible.
Where can those gophers be found? They are at the many Go events that are
popping up around the world. This year we saw several dedicated Go conferences:
-the inaugural [[https://blog.golang.org/gophercon][GopherCon]] and
-[[http://www.dotgo.eu/][dotGo]] conferences in Denver and Paris, the
-[[https://blog.golang.org/fosdem14][Go DevRoom at FOSDEM]] and two more
-instances of the biannual [[https://github.com/GoCon/GoCon][GoCon]] conference
+the inaugural [GopherCon](https://blog.golang.org/gophercon) and
+[dotGo](http://www.dotgo.eu/) conferences in Denver and Paris, the
+[Go DevRoom at FOSDEM](https://blog.golang.org/fosdem14) and two more
+instances of the biannual [GoCon](https://github.com/GoCon/GoCon) conference
in Tokyo. At each event, gophers from around the globe eagerly presented their
Go projects. For the Go team, it is very satisfying to meet so many programmers
that share our vision and excitement.
.image 5years/conferences.jpg
-_More_than_1,200_gophers_attended_GopherCon_in_Denver_and_dotGo_in_Paris._
+_More than 1,200 gophers attended GopherCon in Denver and dotGo in Paris._
There are also dozens of community-run
-[[https://golang.org/wiki/GoUserGroups][Go User Groups]] spread across cities
+[Go User Groups](https://golang.org/wiki/GoUserGroups) spread across cities
worldwide. If you haven't visited your local group, consider going along. And
if there isn't a group in your area, maybe you should
-[[https://blog.golang.org/getthee-to-go-meetup][start one]]?
+[start one](https://blog.golang.org/getthee-to-go-meetup)?
Today, Go has found a home in the cloud. Go arrived as the industry underwent a
tectonic shift toward cloud computing, and we were thrilled to see it quickly
@@ -71,33 +72,33 @@
concurrency primitives, and modern standard library make it a great fit for
cloud software development (after all, that's what it was designed for).
Significant open source cloud projects like
-[[https://www.docker.com/][Docker]] and
-[[https://github.com/GoogleCloudPlatform/kubernetes][Kubernetes]] have been
+[Docker](https://www.docker.com/) and
+[Kubernetes](https://github.com/GoogleCloudPlatform/kubernetes) have been
written in Go, and infrastructure companies like Google, CloudFlare, Canonical,
Digital Ocean, GitHub, Heroku, and Microsoft are now using Go to do some heavy
lifting.
So, what does the future hold? We think that 2015 will be Go's biggest year yet.
-Go 1.4—in addition to its [[https://golang.org/doc/go1.4][new features and fixes]]—lays
+Go 1.4—in addition to its [new features and fixes](https://golang.org/doc/go1.4)—lays
the groundwork for a new low-latency garbage collector and support for running
Go on mobile devices. It is due to be released on December 1st 2014.
We expect the new GC to be available in Go 1.5, due June 1st 2015, which will
make Go appealing for a broader range of applications.
We can't wait to see where people take it.
-And there will be more great events, with [[http://gothamgo.com/][GothamGo]] in
+And there will be more great events, with [GothamGo](http://gothamgo.com/) in
New York (15 Nov), another Go DevRoom at FOSDEM in Brussels (Jan 31 and Feb 1;
-[[https://groups.google.com/d/msg/golang-nuts/1xgBazQzs1I/hwrZ5ni8cTEJ][get involved!]]),
-[[http://www.gophercon.in/][GopherCon India]] in Bengaluru (19-21 Feb),
-the original [[http://gophercon.com/][GopherCon]] back at Denver in July, and
-[[http://www.dotgo.eu/][dotGo]] on again at Paris in November.
+[get involved!](https://groups.google.com/d/msg/golang-nuts/1xgBazQzs1I/hwrZ5ni8cTEJ)),
+[GopherCon India](http://www.gophercon.in/) in Bengaluru (19-21 Feb),
+the original [GopherCon](http://gophercon.com/) back at Denver in July, and
+[dotGo](http://www.dotgo.eu/) on again at Paris in November.
The Go team would like to extend its thanks to all the gophers out there.
Here's to the next five years.
-_To_celebrate_5_years_of_Go,_over_the_coming_month_the_
-[[http://blog.gopheracademy.com/][_Gopher_Academy_]]
-_will_publish_a_series_of_articles_by_prominent_Go_users._Be_sure_to_check_out_
-[[http://blog.gopheracademy.com/][_their_blog_]]
-_for_more_Go_action._
+_To celebrate 5 years of Go, over the coming month the_
+[_Gopher Academy_](http://blog.gopheracademy.com/)
+_will publish a series of articles by prominent Go users. Be sure to check out_
+[_their blog_](http://blog.gopheracademy.com/)
+_for more Go action._
diff --git a/content/6years.article b/content/6years.article
index a5d3ec1..02b3b3f 100644
--- a/content/6years.article
+++ b/content/6years.article
@@ -1,43 +1,44 @@
-Six years of Go
+# Six years of Go
10 Nov 2015
+Summary: Six years ago today the Go language was released as an open source project. Since then, more than 780 contributors have made over 30,000 commits to the project's 22 repositories. The ecosystem continues to grow, with GitHub reporting more than 90,000 Go repositories. And, offline, we see new Go events and user groups pop up [around](https://blog.golang.org/gophercon2015) [the](https://blog.golang.org/gouk15) [world](https://blog.golang.org/gopherchina) with regularity.
Andrew Gerrand
adg@golang.org
-* Six years of Go
+##
Six years ago today the Go language was released as an open source project.
Since then, more than 780 contributors have made over 30,000 commits to the
project's 22 repositories. The ecosystem continues to grow, with GitHub
reporting more than 90,000 Go repositories. And, offline, we see new Go events
-and user groups pop up [[https://blog.golang.org/gophercon2015][around]]
-[[https://blog.golang.org/gouk15][the]]
-[[https://blog.golang.org/gopherchina][world]] with regularity.
+and user groups pop up [around](https://blog.golang.org/gophercon2015)
+[the](https://blog.golang.org/gouk15)
+[world](https://blog.golang.org/gopherchina) with regularity.
.image 6years-gopher.png
-In August we [[https://blog.golang.org/go1.5][released Go 1.5]], the most
+In August we [released Go 1.5](https://blog.golang.org/go1.5), the most
significant release since Go 1. It features a completely
-[[https://golang.org/doc/go1.5#gc][redesigned garbage collector]] that makes
+[redesigned garbage collector](https://golang.org/doc/go1.5#gc) that makes
the language more suitable for latency-sensitive applications; it marks the
transition from a C-based compiler tool chain to one
-[[https://golang.org/doc/go1.5#c][written entirely in Go]]; and it includes
-ports to [[https://golang.org/doc/go1.5#ports][new architectures]], with better
+[written entirely in Go](https://golang.org/doc/go1.5#c); and it includes
+ports to [new architectures](https://golang.org/doc/go1.5#ports), with better
support for ARM processors (the chips that power most smartphones).
These improvements make Go better suited to a broader range of tasks, a trend
that we hope will continue over the coming years.
Improvements to tools continue to boost developer productivity.
-We introduced the [[https://golang.org/cmd/trace/][execution tracer]] and the
-"[[https://golang.org/cmd/go/#hdr-Show_documentation_for_package_or_symbol][go doc]]"
+We introduced the [execution tracer](https://golang.org/cmd/trace/) and the
+"[go doc](https://golang.org/cmd/go/#hdr-Show_documentation_for_package_or_symbol)"
command, as well as more enhancements to our various
-[[https://talks.golang.org/2014/static-analysis.slide][static analysis tools]].
+[static analysis tools](https://talks.golang.org/2014/static-analysis.slide).
We are also working on an
-[[https://groups.google.com/forum/#!topic/Golang-nuts/8oCSjAiKXUQ][official Go plugin for Sublime Text]],
+[official Go plugin for Sublime Text](https://groups.google.com/forum/#!topic/Golang-nuts/8oCSjAiKXUQ),
with better support for other editors in the pipeline.
Early next year we will release more improvements in Go 1.6, including
-HTTP/2 support for [[https://golang.org/pkg/net/http/][net/http]] servers and
+HTTP/2 support for [net/http](https://golang.org/pkg/net/http/) servers and
clients, an official package vendoring mechanism, support for blocks in text
and HTML templates, a memory sanitizer that checks both Go and C/C++ code, and
the usual assortment of other improvements and fixes.
diff --git a/content/7years.article b/content/7years.article
index 0957e85..b23d724 100644
--- a/content/7years.article
+++ b/content/7years.article
@@ -1,10 +1,11 @@
-Seven years of Go
+# Seven years of Go
10 Nov 2016
+Summary: Today marks seven years since we open-sourced our preliminary sketch of Go. With the help of the open source community, including more than a thousand individual contributors to the Go source repositories, Go has matured into a language used all over the world.
The Go Team
rsc@golang.org
-* Seven years of Go
+##
.html gopherbelly.html
@@ -15,9 +16,9 @@
The most significant user-facing changes to Go over the past year are the
addition of built-in support for
-[[https://www.youtube.com/watch?v=FARQMJndUn0#t=0m0s][HTTP/2]] in
-[[https://golang.org/doc/go1.6][Go 1.6]] and the integration of the
-[[https://blog.golang.org/context][context package]] into the standard library in [[https://golang.org/doc/go1.7][Go 1.7]].
+[HTTP/2](https://www.youtube.com/watch?v=FARQMJndUn0#t=0m0s) in
+[Go 1.6](https://golang.org/doc/go1.6) and the integration of the
+[context package](https://blog.golang.org/context) into the standard library in [Go 1.7](https://golang.org/doc/go1.7).
But we’ve been making many less visible improvements.
Go 1.7 changed the x86-64 compiler to use a new SSA-based back end,
improving the performance of most Go programs by 10–20%.
@@ -26,18 +27,18 @@
We’ve also added new ports, to Android on 32-bit x86, Linux on 64-bit MIPS,
and Linux on IBM z Systems.
And we’ve developed new garbage-collection techniques that reduce typical
-“stop the world” pauses to [[https://golang.org/design/17503-eliminate-rescan][under 100 microseconds]].
-(Contrast that with Go 1.5’s big news of [[https://blog.golang.org/go15gc][10 milliseconds or less]].)
+“stop the world” pauses to [under 100 microseconds](https://golang.org/design/17503-eliminate-rescan).
+(Contrast that with Go 1.5’s big news of [10 milliseconds or less](https://blog.golang.org/go15gc).)
This year kicked off with a global Go hackathon,
-the [[https://blog.golang.org/gophergala][Gopher Gala]], in January.
-Then there were [[https://golang.org/wiki/Conferences][Go conferences]] in India and Dubai in February,
+the [Gopher Gala](https://blog.golang.org/gophergala), in January.
+Then there were [Go conferences](https://golang.org/wiki/Conferences) in India and Dubai in February,
China and Japan in April, San Francisco in May, Denver in July,
London in August, Paris last month, and Brazil this past weekend.
And GothamGo in New York is next week.
-This year also saw more than 30 new [[https://golang.org/wiki/GoUserGroups][Go user groups]],
-eight new [[http://www.womenwhogo.org/][Women Who Go]] chapters,
-and four [[https://golangbridge.org/][GoBridge]] workshops around the world.
+This year also saw more than 30 new [Go user groups](https://golang.org/wiki/GoUserGroups),
+eight new [Women Who Go](http://www.womenwhogo.org/) chapters,
+and four [GoBridge](https://golangbridge.org/) workshops around the world.
We continue to be overwhelmed by and grateful for
the enthusiasm and support of the Go community.
diff --git a/content/8years.article b/content/8years.article
index 617193c..a48bc92 100644
--- a/content/8years.article
+++ b/content/8years.article
@@ -1,13 +1,14 @@
-Eight years of Go
+# Eight years of Go
10 Nov 2017
Tags: community, birthday
+Summary: Today we celebrate 8 years since Go was released as an open source project. During [Go’s 4th anniversary](https://blog.golang.org/4years), Andrew finished the post with “Here's to four more years!”. Now that we have reached that milestone, I cannot help but reflect on how much the project and ecosystem has grown since then. In our post 4 years ago we included a chart demonstrating Go's rising popularity on Google Trends with the search term "golang". Today, we’re including an updated chart. In this relative scale of popularity, what was 100 four years ago is now a mere 17. Go’s popularity has increased exponentially over the last 8 years and continues to grow.
Steve Francia
-* Introduction
+##
Today we celebrate 8 years since Go was released as an open source project.
-During [[https://blog.golang.org/4years][Go’s 4th anniversary]], Andrew
+During [Go’s 4th anniversary](https://blog.golang.org/4years), Andrew
finished the post with “Here's to four more years!”. Now that we have reached
that milestone, I cannot help but reflect on how much the project and
ecosystem has grown since then. In our post 4 years ago we included a chart
@@ -18,43 +19,43 @@
.image 8years/image1.png
-Source: [[https://trends.google.com/trends/explore?date=2009-10-01%202017-10-30&q=golang&hl=en-US][trends.google.com]]
+Source: [trends.google.com](https://trends.google.com/trends/explore?date=2009-10-01%202017-10-30&q=golang&hl=en-US)
-** Developers love Go
+## Developers love Go
Go has been embraced by developers all over the world with approximately one
-million users worldwide. In the [[https://octoverse.github.com/][freshly published 2017 Octoverse]]
-by GitHub, *Go*has*become*the*#9*most*popular*language*, surpassing C.
-*Go*is*the*fastest*growing*language*on*GitHub*in*2017* in the top 10 with
-*52%*growth*over*the*previous*year*. In growth, Go swapped places with
+million users worldwide. In the [freshly published 2017 Octoverse](https://octoverse.github.com/)
+by GitHub, **Go has become the #9 most popular language**, surpassing C.
+**Go is the fastest growing language on GitHub in 2017** in the top 10 with
+**52% growth over the previous year**. In growth, Go swapped places with
Javascript, which fell to the second spot with 44%.
.image 8years/image2.png
-Source: [[https://octoverse.github.com/][octoverse.github.com]]
+Source: [octoverse.github.com](https://octoverse.github.com/)
-In [[https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted][Stack Overflow's 2017 developer survey]]
-, Go was the only language that was both on the *top*5*most*loved*and*top*5*most*wanted* languages.
+In [Stack Overflow's 2017 developer survey](https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted)
+, Go was the only language that was both on the **top 5 most loved and top 5 most wanted** languages.
People who use Go, love it, and the people who aren’t using Go, want to be.
.image 8years/image3.png
.image 8years/image4.png
-Source: [[https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted][insights.stackoverflow.com/survey/2017]]
+Source: [insights.stackoverflow.com/survey/2017](https://insights.stackoverflow.com/survey/2017#most-loved-dreaded-and-wanted)
-** Go: The language of Cloud Infrastructure
+## Go: The language of Cloud Infrastructure
In 2014, analyst Donnie Berkholz called Go
-[[http://redmonk.com/dberkholz/2014/03/18/go-the-emerging-language-of-cloud-infrastructure/][the emerging language of cloud infrastructure]].
-*By*2017,*Go*has*emerged*as*the*language*of*cloud*infrastructure*.
-Today, *every*single*cloud*company*has*critical*components*of*their*cloud*infrastructure*implemented*in*Go*
+[the emerging language of cloud infrastructure](http://redmonk.com/dberkholz/2014/03/18/go-the-emerging-language-of-cloud-infrastructure/).
+**By 2017, Go has emerged as the language of cloud infrastructure**.
+Today, **every single cloud company has critical components of their cloud infrastructure implemented in Go**
including Google Cloud, AWS, Microsoft Azure, Digital Ocean, Heroku and many others. Go
is a key part of cloud companies like Alibaba, Cloudflare, and Dropbox. Go is
a critical part of open infrastructure including Kubernetes, Cloud Foundry,
Openshift, NATS, Docker, Istio, Etcd, Consul, Juju and many more. Companies
are increasingly choosing Go to build cloud infrastructure solutions.
-** Go’s Great Community
+## Go’s Great Community
It may be hard to imagine that only four years ago the Go community was
transitioning from online-only to include in-person community with its first
@@ -70,64 +71,64 @@
Go Bridge and Women Who Go.
This year we had two significant firsts for the Go project. We had our first
-[[https://blog.golang.org/contributors-summit][contributor summit]] where
+[contributor summit](https://blog.golang.org/contributors-summit) where
people from across the Go community came together to
discuss the needs and future of the Go project. Shortly after, we had the
-first [[https://blog.golang.org/contributor-workshop][Go contributor workshop]]
+first [Go contributor workshop](https://blog.golang.org/contributor-workshop)
where hundreds of people came to make their first Go contribution.
.image 8years/photo.jpg
Photo by Sameer Ajmani
-** Go’s impact on open source
+## Go’s impact on open source
Go has become a major force in the world of open source powering some of the
most popular projects and enabling innovations across many industries. Find
-thousands of additional applications and libraries at [[https://github.com/avelino/awesome-go][awesome-go]]. Here are
+thousands of additional applications and libraries at [awesome-go](https://github.com/avelino/awesome-go). Here are
just a handful of the most popular:
-- [[https://mobyproject.org/][Moby]] (formerly Docker) is a tool for packaging
- and running applications in lightweight containers.
- Its creator Solomon Hykes cited Go's standard library,
- concurrency primitives, and ease of deployment as key factors,
- and said "To put it simply, if Docker had not been written in Go,
- it would not have been as successful."
+ - [Moby](https://mobyproject.org/) (formerly Docker) is a tool for packaging
+ and running applications in lightweight containers.
+ Its creator Solomon Hykes cited Go's standard library,
+ concurrency primitives, and ease of deployment as key factors,
+ and said "To put it simply, if Docker had not been written in Go,
+ it would not have been as successful."
-- [[https://kubernetes.io/][Kubernetes]] is a system for automating deployment,
- scaling and management of containerized applications.
- Initially designed by Google and used in the Google cloud,
- Kubernetes now is a critical part of every major cloud offering.
+ - [Kubernetes](https://kubernetes.io/) is a system for automating deployment,
+ scaling and management of containerized applications.
+ Initially designed by Google and used in the Google cloud,
+ Kubernetes now is a critical part of every major cloud offering.
-- [[https://gohugo.io/][Hugo]] is now the most popular open-source static website engine.
- With its amazing speed and flexibility, Hugo makes building websites fun again.
- According to [[https://w3techs.com/technologies/overview/content_management/all][w3techs]],
- Hugo now has nearly 3x the usage of Jekyll, the former leader.
+ - [Hugo](https://gohugo.io/) is now the most popular open-source static website engine.
+ With its amazing speed and flexibility, Hugo makes building websites fun again.
+ According to [w3techs](https://w3techs.com/technologies/overview/content_management/all),
+ Hugo now has nearly 3x the usage of Jekyll, the former leader.
-- [[https://prometheus.io/][Prometheus]] is an open source monitoring solution
- and time series database that powers metrics and alerting designed to be
- the system you go to during an outage to allow you to quickly diagnose problems.
+ - [Prometheus](https://prometheus.io/) is an open source monitoring solution
+ and time series database that powers metrics and alerting designed to be
+ the system you go to during an outage to allow you to quickly diagnose problems.
-- [[https://grafana.com/][Grafana]] is an open source,
- feature-rich metrics dashboard and graph editor for Graphite,
- Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
+ - [Grafana](https://grafana.com/) is an open source,
+ feature-rich metrics dashboard and graph editor for Graphite,
+ Elasticsearch, OpenTSDB, Prometheus and InfluxDB.
-- [[https://getlantern.org/][Lantern]] delivers fast, reliable and secure access to blocked websites and apps.
+ - [Lantern](https://getlantern.org/) delivers fast, reliable and secure access to blocked websites and apps.
-- [[https://syncthing.net/][Syncthing]] is an open-source cross platform
- peer-to-peer continuous file synchronization application
+ - [Syncthing](https://syncthing.net/) is an open-source cross platform
+ peer-to-peer continuous file synchronization application
-- [[https://keybase.io/][Keybase]] is a new and free security app for mobile
- phones and computers.
- Think of it as an open source Dropbox & Slack with end-to-end encryption
- public-key cryptography.
+ - [Keybase](https://keybase.io/) is a new and free security app for mobile
+ phones and computers.
+ Think of it as an open source Dropbox & Slack with end-to-end encryption
+ public-key cryptography.
-- [[https://github.com/junegunn/fzf][Fzf]] is an interactive Unix filter
- for command-line that can be used with any list;
- files, command history, processes, hostnames,
- bookmarks, git commits, etc.
- Fzf supports Unix, macOS and has beta support for Windows.
- It also can operate as a vim plugin.
+ - [Fzf](https://github.com/junegunn/fzf) is an interactive Unix filter
+ for command-line that can be used with any list;
+ files, command history, processes, hostnames,
+ bookmarks, git commits, etc.
+ Fzf supports Unix, macOS and has beta support for Windows.
+ It also can operate as a vim plugin.
Many of these authors have said that their projects would not exist without
Go. Some like Kubernetes and Docker created entirely new solutions. Others
@@ -135,7 +136,7 @@
solutions already existed. The popularity of these applications alone is
proof that Go is a ideal language for a broad set of use cases.
-** Thank You
+## Thank You
This is the eighth time we have had the pleasure of writing a birthday blog
post for Go and we continue to be overwhelmed by and grateful for the
@@ -144,8 +145,8 @@
Since Go was first open sourced we have had 10 releases of the language,
libraries and tooling with more than 1680 contributors making over 50,000
commits to the project's 34 repositories; More than double the number of
-contributors and nearly double the number of commits from only [[https://blog.golang.org/6years][two years ago]].
-This year we announced that we have begun planning [[https://blog.golang.org/toward-go2][Go 2]], our first major
+contributors and nearly double the number of commits from only [two years ago](https://blog.golang.org/6years).
+This year we announced that we have begun planning [Go 2](https://blog.golang.org/toward-go2), our first major
revision of the language and tooling.
The Go team would like to thank everyone who has contributed to the project,
diff --git a/content/9years.article b/content/9years.article
index edc8199..88f63c2 100644
--- a/content/9years.article
+++ b/content/9years.article
@@ -1,56 +1,57 @@
-Nine years of Go
+# Nine years of Go
10 Nov 2018
Tags: community, birthday
+Summary: Today marks the ninth anniversary of the day we open-sourced our initial sketch of Go. On each anniversary we like to take time to reflect on what has happened over the past year. The past 12 months have been a breakout year for the Go language and community.
Steve Francia
-* Introduction
+## Introduction
Today marks the ninth anniversary of the day we open-sourced our initial sketch of Go.
On each anniversary we like to take time to reflect on what has happened over the past year.
The past 12 months have been a breakout year for the Go language and community.
-* Go Love & Adoption
+## Go Love & Adoption
Thanks to all of you, 2018 was an amazing year for Go!
In multiple industry surveys Gophers expressed how happy they were using Go,
and many non-Go developers indicated they intended to learn Go before any other language.
-In [[https://insights.stackoverflow.com/survey/2018#most-loved-dreaded-and-wanted][Stack Overflow’s 2018 Developer Survey]],
+In [Stack Overflow’s 2018 Developer Survey](https://insights.stackoverflow.com/survey/2018#most-loved-dreaded-and-wanted),
Go retained its coveted spot in both the top 5 most loved and top 5 most wanted languages.
People who use Go love it, and people who aren’t using Go want to.
-In [[https://www.activestate.com/developer-survey-2018-open-source-runtime-pains][ActiveState’s 2018 Developer Survey]],
+In [ActiveState’s 2018 Developer Survey](https://www.activestate.com/developer-survey-2018-open-source-runtime-pains),
Go topped the charts with 36% of users responding they were “Extremely Satisfied” using Go
and 61% responding “Very Satisfied” or better.
-[[https://www.jetbrains.com/research/devecosystem-2018/][JetBrains’s 2018 Developer Survey]] awarded Go
+[JetBrains’s 2018 Developer Survey](https://www.jetbrains.com/research/devecosystem-2018/) awarded Go
the “Most promising language” with 12% of respondents using Go today and 16% intending to use Go in the future.
-In [[https://research.hackerrank.com/developer-skills/2018/][HackerRank’s 2018 Developer Survey]],
+In [HackerRank’s 2018 Developer Survey](https://research.hackerrank.com/developer-skills/2018/),
38% of developers responded that they were intending to learn Go next.
We are excited about all of our new gophers and actively working to improve our educational and community resources.
-* Go Community
+## Go Community
It’s hard to believe that it’s only been five years since
the first Go conferences and Go meetups.
We’ve seen major growth in this area of community leadership over the last year.
-There are now over 20 [[https://github.com/golang/go/wiki/Conferences][Go conferences]]
-and over 300 [[https://www.meetup.com/topics/golang/][Go-related meetups]] spanning the globe.
+There are now over 20 [Go conferences](https://github.com/golang/go/wiki/Conferences)
+and over 300 [Go-related meetups](https://www.meetup.com/topics/golang/) spanning the globe.
Thanks to the hard work put into these many conferences and meetups,
there have been hundreds of great talks this year.
Here are a few of our favorite talks specifically discussing the growth of our community
and how we can better support gophers worldwide.
-- [[https://www.youtube.com/watch?v=cVaDY0ChvOQ][Writing Accessible Go]], by Julia Ferraioli at GopherCon
-- [[https://www.youtube.com/watch?v=7yMXs9TRvVI][The Importance of Beginners]], by Natalie Pistunovich at GopherCon
-- [[https://www.youtube.com/watch?v=I_KcpgxcFyU][The Legacy of Go, Part 2]], by Carmen Andoh at GothamGo
-- [[https://www.youtube.com/watch?v=dl1mCGKwlYY][Growing a Community of Gophers]], by Cassandra Salisbury at Gopherpalooza
+ - [Writing Accessible Go](https://www.youtube.com/watch?v=cVaDY0ChvOQ), by Julia Ferraioli at GopherCon
+ - [The Importance of Beginners](https://www.youtube.com/watch?v=7yMXs9TRvVI), by Natalie Pistunovich at GopherCon
+ - [The Legacy of Go, Part 2](https://www.youtube.com/watch?v=I_KcpgxcFyU), by Carmen Andoh at GothamGo
+ - [Growing a Community of Gophers](https://www.youtube.com/watch?v=dl1mCGKwlYY), by Cassandra Salisbury at Gopherpalooza
-On that theme, this year we also [[https://blog.golang.org/conduct-2018][revised our code of conduct]]
+On that theme, this year we also [revised our code of conduct](https://blog.golang.org/conduct-2018)
to better support inclusivity in the Go community.
The Go community is truly global.
@@ -58,27 +59,27 @@
.image 9years-iceland.jpg _ 800
-_(Photo_by_Winter_Francia.)_
+_(Photo by Winter Francia.)_
-* Go 2
+## Go 2
After five years of experience with Go 1, we’ve started looking at
what we should change about Go to better support
-[[https://talks.golang.org/2012/splash.article][programming at scale]].
+[programming at scale](https://talks.golang.org/2012/splash.article).
-Last spring, we published a [[https://blog.golang.org/versioning-proposal][draft design for Go modules]],
+Last spring, we published a [draft design for Go modules](https://blog.golang.org/versioning-proposal),
which provide an integrated mechanism for versioning and package distribution.
The most recent Go release, Go 1.11, included
-[[https://golang.org/doc/go1.11#modules][preliminary support for modules]].
+[preliminary support for modules](https://golang.org/doc/go1.11#modules).
Last summer we published
-[[https://blog.golang.org/go2draft][early draft designs]]
+[early draft designs](https://blog.golang.org/go2draft)
for how Go 2 might better support error values, error handling, and generic programming.
We are excited about refining these designs with the community’s help as we work
-[[https://blog.golang.org/toward-go2][toward Go 2]].
+[toward Go 2](https://blog.golang.org/toward-go2).
-* Go Contributors
+## Go Contributors
The Go project has been increasing in the number of contributions from the community for several years.
The project hit a major milestone in mid-2018 when, for the first time,
@@ -86,7 +87,7 @@
.image 9years-graph.png _ 600
-* Thank You
+## Thank You
On a personal note, from the entire Go team,
we want to sincerely thank all of you.
diff --git a/content/a-conversation-with-the-go-team.article b/content/a-conversation-with-the-go-team.article
index 7c8df47..475d4aa 100644
--- a/content/a-conversation-with-the-go-team.article
+++ b/content/a-conversation-with-the-go-team.article
@@ -1,7 +1,8 @@
-A conversation with the Go team
+# A conversation with the Go team
6 Jun 2013
+Summary: At Google I/O 2013, several members of the Go team hosted a "Fireside chat." Robert Griesemer, Rob Pike, David Symonds, Andrew Gerrand, Ian Lance Taylor, Sameer Ajmani, Brad Fitzpatrick, and Nigel Tao took questions from the audience and people around the world about various aspects of the Go project.
-* Introduction
+##
At Google I/O 2013, several members of the Go team hosted a "Fireside chat."
Robert Griesemer, Rob Pike, David Symonds, Andrew Gerrand, Ian Lance Taylor,
@@ -11,23 +12,23 @@
.iframe //www.youtube.com/embed/p9VUCp98ay4 309 549
We also hosted a similar session at I/O last year:
-[[http://www.youtube.com/watch?v=sln-gJaURzk][_Meet_the_Go_team_]].
+[_Meet the Go team_](http://www.youtube.com/watch?v=sln-gJaURzk).
There were many more questions from Google Moderator than we were able to
answer in the short 40 minute session.
Here we answer some of those we missed in the live session.
-_Linking_speed_(and_memory_usage)_for_the_gc_toolchain_are_a_known_problem._
-_Are_there_any_plans_to_address_this_during_the_1.2_cycle?_
+_Linking speed (and memory usage) for the gc toolchain are a known problem._
+_Are there any plans to address this during the 1.2 cycle?_
-*Rob:* Yes. We are always thinking about ways to improve performance of the
+**Rob:** Yes. We are always thinking about ways to improve performance of the
tools as well as the language and libraries.
-_I_have_been_very_pleased_to_see_how_quickly_Go_appears_to_be_gaining_traction._
-_Can_you_talk_about_the_reactions_you_have_experienced_working_with_other_
-_developers_inside_and_outside_Google?_Are_there_any_major_sticking_points_remaining?_
+_I have been very pleased to see how quickly Go appears to be gaining traction._
+_Can you talk about the reactions you have experienced working with other_
+_developers inside and outside Google? Are there any major sticking points remaining?_
-*Robert:* A lot of developers that seriously tried Go are very happy with it.
+**Robert:** A lot of developers that seriously tried Go are very happy with it.
Many of them report a much smaller, more readable and thus maintainable code
base: A 50% code size reduction or more when coming from C++ seems common.
Developers that switched to Go from Python are invariably pleased with the
@@ -35,34 +36,34 @@
language (some of which we might iron out at some point). What surprises me is
that almost nobody complains about the lack of generics.
-_When_will_Go_be_a_first-class_language_for_Android_development?_
+_When will Go be a first-class language for Android development?_
-*Andrew:* This would be great, but we don't have anything to announce.
+**Andrew:** This would be great, but we don't have anything to announce.
-_Is_there_a_roadmap_for_the_next_version_of_Go?_
+_Is there a roadmap for the next version of Go?_
-*Andrew:* We have no feature roadmap as such. The contributors tend to work on
+**Andrew:** We have no feature roadmap as such. The contributors tend to work on
what interests them. Active areas of development include the gc and gccgo
compilers, the garbage collector and runtime, and many others. We expect the
majority of exciting new additions will be in the form of improvements to our
tools. You can find design discussions and code reviews on the
-[[http://groups.google.com/group/golang-dev][golang-dev mailing list]].
+[golang-dev mailing list](http://groups.google.com/group/golang-dev).
As for the timeline, we do have
-[[https://docs.google.com/document/d/106hMEZj58L9nq9N9p7Zll_WKfo-oyZHFyI6MttuZmBU/edit?usp=sharing][concrete plans]]:
+[concrete plans](https://docs.google.com/document/d/106hMEZj58L9nq9N9p7Zll_WKfo-oyZHFyI6MttuZmBU/edit?usp=sharing):
we expect to release Go 1.2 on December 1, 2013.
-_Where_do_you_guys_want_to_see_Go_used_externally?_
-_What_would_you_consider_a_big_win_for_Go_adoption_outside_Google?_
-_Where_do_you_think_Go_has_the_potential_to_make_a_significant_impact?_
+_Where do you guys want to see Go used externally?_
+_What would you consider a big win for Go adoption outside Google?_
+_Where do you think Go has the potential to make a significant impact?_
-*Rob:* Where Go is deployed is up to its users, not to us. We're happy to see
+**Rob:** Where Go is deployed is up to its users, not to us. We're happy to see
it gain traction anywhere it helps. It was designed with server-side software
in mind, and is showing promise there, but has also shown strengths in many
other areas and the story is really just beginning. There are many surprises to
come.
-*Ian:* It’s easier for startups to use Go, because they don’t have an
+**Ian:** It’s easier for startups to use Go, because they don’t have an
entrenched code base that they need to work with. So I see two future big wins
for Go. One would be a significant use of Go by an existing large software
company other than Google. Another would be a significant IPO or acquisition
@@ -71,25 +72,25 @@
But it would be another way to show that Go can be part of a successful
software system.
-_Have_you_thought_any_(more)_about_the_potential_of_dynamically_loading_
-_Go_packages_or_objects_and_how_it_could_work_in_Go?_
-_I_think_this_could_enable_some_really_interesting_and_expressive_constructs,_
-_especially_coupled_with_interfaces._
+_Have you thought any (more) about the potential of dynamically loading_
+_Go packages or objects and how it could work in Go?_
+_I think this could enable some really interesting and expressive constructs,_
+_especially coupled with interfaces._
-*Rob:* This is an active topic of discussion. We appreciate how powerful the
+**Rob:** This is an active topic of discussion. We appreciate how powerful the
concept can be and hope we can find a way to implement it before too long.
There are serious challenges in the design approach to take and the need to
make it work portably.
-_There_was_a_discussion_a_while_ago_about_collecting_some_best-of-breed_
-`database/sql` _drivers_in_a_more_central_place._
-_Some_people_had_strong_opinions_to_the_contrary_though._
-_Where_is_ `database/sql` _and_its_drivers_going_in_the_next_year?_
+_There was a discussion a while ago about collecting some best-of-breed_
+`database/sql` _drivers in a more central place._
+_Some people had strong opinions to the contrary though._
+_Where is_ `database/sql` _and its drivers going in the next year?_
-*Brad:* While we could create an official subrepo (“go.db”) for database
+**Brad:** While we could create an official subrepo (“go.db”) for database
drivers, we fear that would unduly bless certain drivers. At this point we’d
still rather see healthy competition between different drivers. The
-[[https://golang.org/wiki/SQLDrivers][SQLDrivers wiki page]]
+[SQLDrivers wiki page](https://golang.org/wiki/SQLDrivers)
lists some good ones.
The `database/sql` package didn’t get much attention for a while, due to lack of
@@ -99,12 +100,12 @@
There might be small extensions here and there as needed for performance or to
assist some drivers.
-_What_is_the_status_of_versioning?_
-_Is_importing_some_code_from_github_a_best_practice_recommended_by_the_Go_team?_
-_What_happens_when_we_publish_our_code_that_is_dependent_on_a_github_repo_and_
-_the_API_of_the_dependee_changes?_
+_What is the status of versioning?_
+_Is importing some code from github a best practice recommended by the Go team?_
+_What happens when we publish our code that is dependent on a github repo and_
+_the API of the dependee changes?_
-*Ian:* This is frequently discussed on the mailing list. What we do internally
+**Ian:** This is frequently discussed on the mailing list. What we do internally
is take a snapshot of the imported code, and update that snapshot from time to
time. That way, our code base won't break unexpectedly if the API changes.
But we understand that that approach doesn’t work very well for people who are
@@ -113,17 +114,17 @@
than the language itself; the place to fix this is in the tools, not the
language.
-_What_about_Go_and_Graphical_User_Interfaces?_
+_What about Go and Graphical User Interfaces?_
-*Rob:* This is a subject close to my heart. Newsqueak, a very early precursor
+**Rob:** This is a subject close to my heart. Newsqueak, a very early precursor
language, was designed specifically for writing graphics programs (that's what
we used to call apps). The landscape has changed a lot but I think Go's
concurrency model has much to offer in the field of interactive graphics.
-*Andrew:* There are many
-[[https://golang.org/wiki/Projects#Graphics_and_Audio][bindings for existing graphics libraries]]
+**Andrew:** There are many
+[bindings for existing graphics libraries](https://golang.org/wiki/Projects#Graphics_and_Audio)
out there, and a few Go-specific projects. One of the more promising ones is
-[[https://github.com/skelterjohn/go.uik][go.uik]], but it's still in its early
+[go.uik](https://github.com/skelterjohn/go.uik), but it's still in its early
days. I think there's a lot of potential for a great Go-specific UI toolkit for
writing native applications (consider handling user events by receiving from a
channel), but developing a production-quality package is a significant
@@ -133,12 +134,12 @@
interfaces. Go provides great support for building web apps, albeit only on the
back end.
-_In_the_mailing_lists_Adam_Langley_has_stated_that_the_TLS_code_has_not_been_
-_reviewed_by_outside_groups,_and_thus_should_not_be_used_in_production._
-_Are_there_plans_to_have_the_code_reviewed?_
-_A_good_secure_implementation_of_concurrent_TLS_would_be_very_nice._
+_In the mailing lists Adam Langley has stated that the TLS code has not been_
+_reviewed by outside groups, and thus should not be used in production._
+_Are there plans to have the code reviewed?_
+_A good secure implementation of concurrent TLS would be very nice._
-*Adam*: Cryptography is notoriously easy to botch in subtle and surprising ways
+**Adam**: Cryptography is notoriously easy to botch in subtle and surprising ways
and I’m only human. I don’t feel that I can warrant that Go’s TLS code is
flawless and I wouldn’t want to misrepresent it.
@@ -152,7 +153,7 @@
investigated whether we could get Matasano or the like to do it. That depends
on whether Google wishes to fund it.
-_What_do_you_think_about_ [[http://www.gophercon.com/][_GopherCon_2014_]]_?_
-_Does_anyone_from_the_team_plan_to_attend?_
+_What do you think about_ [_GopherCon 2014_](http://www.gophercon.com/)_?_
+_Does anyone from the team plan to attend?_
-*Andrew:* It's very exciting. I'm sure some of us will be there.
+**Andrew:** It's very exciting. I'm sure some of us will be there.
diff --git a/content/a-new-go-api-for-protocol-buffers.article b/content/a-new-go-api-for-protocol-buffers.article
index f3afe0a..2c5c014 100644
--- a/content/a-new-go-api-for-protocol-buffers.article
+++ b/content/a-new-go-api-for-protocol-buffers.article
@@ -1,19 +1,20 @@
-A new Go API for Protocol Buffers
-02 Mar 2020
+# A new Go API for Protocol Buffers
+2 Mar 2020
Tags: protobuf, technical
+Summary: We are pleased to announce the release of a major revision of the Go API for [protocol buffers](https://developers.google.com/protocol-buffers), Google's language-neutral data interchange format.
Joe Tsai, Damien Neil, and Herbie Ong
-* Introduction
+## Introduction
We are pleased to announce the release of a major revision of the Go API for
-[[https://developers.google.com/protocol-buffers][protocol buffers]],
+[protocol buffers](https://developers.google.com/protocol-buffers),
Google's language-neutral data interchange format.
-* Motivations for a new API
+## Motivations for a new API
The first protocol buffer bindings for Go were
-[[https://blog.golang.org/third-party-libraries-goprotobuf-and][announced by Rob Pike]]
+[announced by Rob Pike](https://blog.golang.org/third-party-libraries-goprotobuf-and)
in March of 2010. Go 1 would not be released for another two years.
In the decade since that first release, the package has grown and
@@ -21,7 +22,7 @@
Many people want to write programs that use reflection to examine protocol
buffer messages. The
-[[https://pkg.go.dev/reflect][`reflect`]]
+[`reflect`](https://pkg.go.dev/reflect)
package provides a view of Go types and
values, but omits information from the protocol buffer type system. For
example, we might want to write a function that traverses a log entry and
@@ -33,7 +34,7 @@
capable of representing messages whose type is not known at compile time.
We also observed that a frequent source of problems was that the
-[[https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#Message][`proto.Message`]]
+[`proto.Message`](https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#Message)
interface, which identifies values of generated message types, does very
little to describe the behavior of those types. When users create types
that implement that interface (often inadvertently by embedding a message
@@ -52,11 +53,11 @@
Today, we're pleased to release that new module. We hope you like it.
-* Reflection
+## Reflection
Reflection is the flagship feature of the new implementation. Similar
to how the `reflect` package provides a view of Go types and values, the
-[[https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc][`google.golang.org/protobuf/reflect/protoreflect`]]
+[`google.golang.org/protobuf/reflect/protoreflect`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc)
package provides a view of values according to the protocol buffer
type system.
@@ -65,7 +66,7 @@
function we mentioned previously.
First, we'll write a `.proto` file defining an extension of the
-[[https://github.com/protocolbuffers/protobuf/blob/b96241b1b716781f5bc4dc25e1ebb0003dfaba6a/src/google/protobuf/descriptor.proto#L509][`google.protobuf.FieldOptions`]]
+[`google.protobuf.FieldOptions`](https://github.com/protocolbuffers/protobuf/blob/b96241b1b716781f5bc4dc25e1ebb0003dfaba6a/src/google/protobuf/descriptor.proto#L509)
type so we can annotate fields as containing
sensitive information or not.
@@ -91,7 +92,7 @@
}
This function accepts a
-[[https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message][`proto.Message`]],
+[`proto.Message`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Message),
an interface type implemented by all generated message types. This type
is an alias for one defined in the `protoreflect` package:
@@ -101,7 +102,7 @@
To avoid filling up the namespace of generated
messages, the interface contains only a single method returning a
-[[https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message][`protoreflect.Message`]],
+[`protoreflect.Message`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message),
which provides access to the message contents.
(Why an alias? Because `protoreflect.Message` has a corresponding
@@ -109,7 +110,7 @@
import cycle between the two packages.)
The
-[[https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message.Range][`protoreflect.Message.Range`]]
+[`protoreflect.Message.Range`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Message.Range)
method calls a function for every populated field in a message.
m := pb.ProtoReflect()
@@ -119,13 +120,13 @@
})
The range function is called with a
-[[https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#FieldDescriptor][`protoreflect.FieldDescriptor`]]
+[`protoreflect.FieldDescriptor`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#FieldDescriptor)
describing the protocol buffer type of the field, and a
-[[https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Value][`protoreflect.Value`]]
+[`protoreflect.Value`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Value)
containing the field value.
The
-[[https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Descriptor.Options][`protoreflect.FieldDescriptor.Options`]]
+[`protoreflect.FieldDescriptor.Options`](https://pkg.go.dev/google.golang.org/protobuf/reflect/protoreflect?tab=doc#Descriptor.Options)
method returns the field options as a `google.protobuf.FieldOptions`
message.
@@ -147,9 +148,9 @@
This is also an example of an area where we
have simplified the `proto` package API. The original
-[[https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#GetExtension][`proto.GetExtension`]]
+[`proto.GetExtension`](https://pkg.go.dev/github.com/golang/protobuf/proto?tab=doc#GetExtension)
returned both a value and an error. The new
-[[https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension][`proto.GetExtension`]]
+[`proto.GetExtension`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#GetExtension)
returns just a value, returning the default value for the field if it is
not present. Extension decoding errors are reported at `Unmarshal` time.
@@ -176,7 +177,7 @@
message-valued fields. We hope that this simple example gives a
taste of protocol buffer reflection and its uses.
-* Versions
+## Versions
We call the original version of Go protocol buffers APIv1, and the
new one APIv2. Because APIv2 is not backwards compatible with APIv1,
@@ -188,11 +189,11 @@
`proto3` language versions.)
The
-[[https://pkg.go.dev/github.com/golang/protobuf?tab=overview][`github.com/golang/protobuf`]]
+[`github.com/golang/protobuf`](https://pkg.go.dev/github.com/golang/protobuf?tab=overview)
module is APIv1.
The
-[[https://pkg.go.dev/google.golang.org/protobuf?tab=overview][`google.golang.org/protobuf`]]
+[`google.golang.org/protobuf`](https://pkg.go.dev/google.golang.org/protobuf?tab=overview)
module is APIv2. We have taken advantage of the need to change the
import path to switch to one that is not tied to a specific hosting
provider. (We considered `google.golang.org/protobuf/v2`, to make it
@@ -205,17 +206,17 @@
one API while others use another. It is essential, therefore, that we
continue to support programs that use APIv1.
-- `github.com/golang/protobuf@v1.3.4` is the most recent pre-APIv2 version of APIv1.
+ - `github.com/golang/protobuf@v1.3.4` is the most recent pre-APIv2 version of APIv1.
-- `github.com/golang/protobuf@v1.4.0` is a version of APIv1 implemented in terms of APIv2.
- The API is the same, but the underlying implementation is backed by the new one.
- This version contains functions to convert between the APIv1 and APIv2 `proto.Message`
- interfaces to ease the transition between the two.
+ - `github.com/golang/protobuf@v1.4.0` is a version of APIv1 implemented in terms of APIv2.
+ The API is the same, but the underlying implementation is backed by the new one.
+ This version contains functions to convert between the APIv1 and APIv2 `proto.Message`
+ interfaces to ease the transition between the two.
-- `google.golang.org/protobuf@v1.20.0` is APIv2.
- This module depends upon `github.com/golang/protobuf@v1.4.0`,
- so any program which uses APIv2 will automatically pick a version of APIv1
- which integrates with it.
+ - `google.golang.org/protobuf@v1.20.0` is APIv2.
+ This module depends upon `github.com/golang/protobuf@v1.4.0`,
+ so any program which uses APIv2 will automatically pick a version of APIv1
+ which integrates with it.
(Why start at version `v1.20.0`? To provide clarity.
We do not anticipate APIv1 to ever reach `v1.20.0`,
@@ -232,31 +233,31 @@
implementation until the maintainers choose to update to the new one
(either directly, or by updating a dependency).
-* Additional features of note
+## Additional features of note
The
-[[https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson][`google.golang.org/protobuf/encoding/protojson`]]
+[`google.golang.org/protobuf/encoding/protojson`](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson)
package converts protocol buffer messages to and from JSON using the
-[[https://developers.google.com/protocol-buffers/docs/proto3#json][canonical JSON mapping]],
+[canonical JSON mapping](https://developers.google.com/protocol-buffers/docs/proto3#json),
and fixes a number of issues with the old `jsonpb` package
that were difficult to change without causing problems for existing users.
The
-[[https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb][`google.golang.org/protobuf/types/dynamicpb`]]
+[`google.golang.org/protobuf/types/dynamicpb`](https://pkg.go.dev/google.golang.org/protobuf/types/dynamicpb)
package provides an implementation of `proto.Message` for messages whose
protocol buffer type is derived at runtime.
The
-[[https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp][`google.golang.org/protobuf/testing/protocmp`]]
+[`google.golang.org/protobuf/testing/protocmp`](https://pkg.go.dev/google.golang.org/protobuf/testing/protocmp)
package provides functions to compare protocol buffer messages with the
-[[https://pkg.go.dev/github.com/google/go-cmp/cmp][`github.com/google/cmp`]]
+[`github.com/google/cmp`](https://pkg.go.dev/github.com/google/go-cmp/cmp)
package.
The
-[[https://pkg.go.dev/google.golang.org/protobuf/compiler/protogen?tab=doc][`google.golang.org/protobuf/compiler/protogen`]]
+[`google.golang.org/protobuf/compiler/protogen`](https://pkg.go.dev/google.golang.org/protobuf/compiler/protogen?tab=doc)
package provides support for writing protocol compiler plugins.
-* Conclusion
+## Conclusion
The `google.golang.org/protobuf` module is a major overhaul of
Go's support for protocol buffers, providing first-class support
diff --git a/content/advanced-go-concurrency-patterns.article b/content/advanced-go-concurrency-patterns.article
index c3f1eab..f9b9298 100644
--- a/content/advanced-go-concurrency-patterns.article
+++ b/content/advanced-go-concurrency-patterns.article
@@ -1,15 +1,16 @@
-Advanced Go Concurrency Patterns
+# Advanced Go Concurrency Patterns
23 May 2013
Tags: talk, video, concurrency
+Summary: At Google I/O a year ago Rob Pike presented [_Go Concurrency Patterns_](https://talks.golang.org/2012/concurrency.slide), an introduction to Go's concurrency model. Last week, at I/O 2013, Go team member Sameer Ajmani continued the story with [_Advanced Go Concurrency Patterns_](http://talks.golang.org/2013/advconc.slide), an in-depth look at a real concurrent programming problem. The talk shows how to detect and avoid deadlocks and race conditions, and demonstrates the implementation of deadlines, cancellation, and more. For those who want to take their Go programming to the next level, this is a must-see.
Andrew Gerrand
-* Introduction
+##
-At Google I/O a year ago Rob Pike presented [[https://talks.golang.org/2012/concurrency.slide][_Go_Concurrency_Patterns_]],
+At Google I/O a year ago Rob Pike presented [_Go Concurrency Patterns_](https://talks.golang.org/2012/concurrency.slide),
an introduction to Go's concurrency model.
Last week, at I/O 2013, Go team member Sameer Ajmani continued the story
-with [[http://talks.golang.org/2013/advconc.slide][_Advanced_Go_Concurrency_Patterns_]],
+with [_Advanced Go Concurrency Patterns_](http://talks.golang.org/2013/advconc.slide),
an in-depth look at a real concurrent programming problem.
The talk shows how to detect and avoid deadlocks and race conditions,
and demonstrates the implementation of deadlines,
@@ -18,9 +19,9 @@
.iframe //www.youtube.com/embed/QDDwwePbDtw?rel=0 309 549
-The slides are [[https://talks.golang.org/2013/advconc.slide][available here]]
+The slides are [available here](https://talks.golang.org/2013/advconc.slide)
(use the left and right arrows to navigate).
-The slides were produced with [[https://godoc.org/golang.org/x/tools/present][the present tool]],
-and the runnable code snippets are powered by the [[http://play.golang.org/][Go Playground]].
-The source code for this talk is in [[https://github.com/golang/talks/tree/master/content/2013/advconc][the go.talks sub-repository]].
+The slides were produced with [the present tool](https://godoc.org/golang.org/x/tools/present),
+and the runnable code snippets are powered by the [Go Playground](http://play.golang.org/).
+The source code for this talk is in [the go.talks sub-repository](https://github.com/golang/talks/tree/master/content/2013/advconc).
diff --git a/content/appengine-dec2013.article b/content/appengine-dec2013.article
index 1e53a7d..21ecd90 100644
--- a/content/appengine-dec2013.article
+++ b/content/appengine-dec2013.article
@@ -1,22 +1,23 @@
-Go on App Engine: tools, tests, and concurrency
+# Go on App Engine: tools, tests, and concurrency
13 Dec 2013
Tags: appengine
+Summary: When we [launched Go for App Engine](https://blog.golang.org/go-and-google-app-engine) in May 2011 the SDK was just a modified version of the Python SDK. At the time, there was no canonical way to build or organize Go programs, so it made sense to take the Python approach. Since then Go 1.0 was released, including the [go tool](https://golang.org/cmd/go/) and a [convention](https://golang.org/doc/code.html) for organizing Go programs.
Andrew Gerrand
Johan Euphrosine
-* Background
+## Background
-When we [[https://blog.golang.org/go-and-google-app-engine][launched Go for App Engine]]
+When we [launched Go for App Engine](https://blog.golang.org/go-and-google-app-engine)
in May 2011 the SDK was just a modified version of the Python SDK.
At the time, there was no canonical way to build or organize Go programs, so it
made sense to take the Python approach. Since then Go 1.0 was released,
-including the [[https://golang.org/cmd/go/][go tool]] and a
-[[https://golang.org/doc/code.html][convention]] for organizing Go programs.
+including the [go tool](https://golang.org/cmd/go/) and a
+[convention](https://golang.org/doc/code.html) for organizing Go programs.
In January 2013 we announced
-[[https://blog.golang.org/the-app-engine-sdk-and-workspaces-gopath][better integration]]
+[better integration](https://blog.golang.org/the-app-engine-sdk-and-workspaces-gopath)
between the Go App Engine SDK and the go tool, promoting the use of
conventional import paths in App Engine apps and making it possible to use "go
get" to fetch app dependencies.
@@ -24,17 +25,17 @@
With the recent release of App Engine 1.8.8 we are pleased to announce more
improvements to the developer experience for Go on App Engine.
-* The goapp tool
+## The goapp tool
The Go App Engine SDK now includes the "goapp" tool, an App Engine-specific
version of the "go" tool. The new name permits users to keep both the regular
"go" tool and the "goapp" tool in their system PATH.
-In addition to the existing "go" tool [[https://golang.org/cmd/go/][commands]],
+In addition to the existing "go" tool [commands](https://golang.org/cmd/go/),
the "goapp" tool provides new commands for working with App Engine apps.
-The "[[https://developers.google.com/appengine/docs/go/tools/devserver][goapp serve]]"
+The "[goapp serve](https://developers.google.com/appengine/docs/go/tools/devserver)"
command starts the local development server and the
-"[[https://developers.google.com/appengine/docs/go/tools/uploadinganapp][goapp deploy]]"
+"[goapp deploy](https://developers.google.com/appengine/docs/go/tools/uploadinganapp)"
command uploads an app to App Engine.
The main advantages offered by the "goapp serve" and "goapp deploy" commands
@@ -53,36 +54,36 @@
$ goapp serve github.com/user/myapp
You can even specify a YAML file to serve or deploy a specific
-[[https://developers.google.com/appengine/docs/go/modules/][module]]:
+[module](https://developers.google.com/appengine/docs/go/modules/):
$ goapp deploy mymodule.yaml
These commands can replace most uses of `dev_appserver.py` and `appcfg.py`,
although the Python tools are still available for their less common uses.
-* Local unit testing
+## Local unit testing
The Go App Engine SDK now supports local unit testing, using Go's native
-[[https://developers.google.com/appengine/docs/go/tools/localunittesting][testing package]]
-and the "[[https://golang.org/cmd/go/#hdr-Test_packages][go test]]" command
+[testing package](https://developers.google.com/appengine/docs/go/tools/localunittesting)
+and the "[go test](https://golang.org/cmd/go/#hdr-Test_packages)" command
(provided as "goapp test" by the SDK).
Furthermore, you can now write tests that use App Engine services.
-The [[https://developers.google.com/appengine/docs/go/tools/localunittesting#Go_Introducing_the_aetest_package][aetest package]]
+The [aetest package](https://developers.google.com/appengine/docs/go/tools/localunittesting#Go_Introducing_the_aetest_package)
provides an appengine.Context value that delegates requests to a temporary
instance of the development server.
For more information about using "goapp test" and the aetest package, see the
-[[https://developers.google.com/appengine/docs/go/tools/localunittesting][Local Unit Testing for Go documentation]].
+[Local Unit Testing for Go documentation](https://developers.google.com/appengine/docs/go/tools/localunittesting).
Note that the aetest package is still in its early days;
we hope to add more features over time.
-* Better concurrency support
+## Better concurrency support
It is now possible to configure the number of concurrent requests served by
each of your app's dynamic instances by setting the
-[[https://developers.google.com/appengine/docs/go/modules/#max_concurrent_requests][`max_concurrent_requests`]] option
-(available to [[https://developers.google.com/appengine/docs/go/modules/#automatic_scaling][Automatic Scaling modules]] only).
+[`max_concurrent_requests`](https://developers.google.com/appengine/docs/go/modules/#max_concurrent_requests) option
+(available to [Automatic Scaling modules](https://developers.google.com/appengine/docs/go/modules/#automatic_scaling) only).
Here's an example `app.yaml` file:
@@ -101,10 +102,10 @@
taking advantage of Go's efficient handling of concurrency, which should yield
better instance utilization and ultimately fewer billable instance hours.
-* Conclusion
+## Conclusion
With these changes Go on App Engine is more convenient and efficient than ever,
and we hope you enjoy the improvements. Please join the
-[[http://groups.google.com/group/google-appengine-go/][google-appengine-go group]]
+[google-appengine-go group](http://groups.google.com/group/google-appengine-go/)
to raise questions or discuss these changes with the engineering team and the
rest of the community.
diff --git a/content/appengine-go111.article b/content/appengine-go111.article
index 3319153..a9eaae4 100644
--- a/content/appengine-go111.article
+++ b/content/appengine-go111.article
@@ -1,19 +1,20 @@
-Announcing App Engine’s New Go 1.11 Runtime
+# Announcing App Engine’s New Go 1.11 Runtime
16 Oct 2018
Tags: appengine
+Summary: [App Engine](https://cloud.google.com/appengine/) launched [experimental support for Go](https://blog.golang.org/go-and-google-app-engine) in 2011. In the subsequent years, the Go community has grown significantly and has settled on idiomatic patterns for cloud-based applications. Today, Google Cloud is [announcing a new Go 1.11 runtime](https://cloud.google.com/blog/products/application-development/go-1-11-is-now-available-on-app-engine) for the App Engine standard environment that provides all the power of App Engine—things like paying only for what you use, automatic scaling, and managed infrastructure—while supporting idiomatic Go.
Eno Compton
Tyler Bui-Palsulich
-* Background
+##
-[[https://cloud.google.com/appengine/][App Engine]] launched
-[[https://blog.golang.org/go-and-google-app-engine][experimental support for Go]]
+[App Engine](https://cloud.google.com/appengine/) launched
+[experimental support for Go](https://blog.golang.org/go-and-google-app-engine)
in 2011. In the subsequent years, the Go community has grown significantly and
has settled on idiomatic
patterns for cloud-based applications. Today, Google Cloud is
-[[https://cloud.google.com/blog/products/application-development/go-1-11-is-now-available-on-app-engine][announcing a new Go 1.11 runtime]]
+[announcing a new Go 1.11 runtime](https://cloud.google.com/blog/products/application-development/go-1-11-is-now-available-on-app-engine)
for the App Engine standard environment that provides all the
power of App Engine—things like paying only for what you use, automatic scaling,
and managed infrastructure—while supporting idiomatic Go.
@@ -22,20 +23,20 @@
supported packages, `context.Context` values, or HTTP clients. Write your Go
application however you prefer, add an `app.yaml` file, and your app is ready
to deploy on App Engine.
-[[https://cloud.google.com/appengine/docs/standard/go111/specifying-dependencies][Specifying Dependencies]]
+[Specifying Dependencies](https://cloud.google.com/appengine/docs/standard/go111/specifying-dependencies)
describes how the new runtime
-supports [[https://golang.org/cmd/go/#hdr-Vendor_Directories][vendoring]] and
-[[https://golang.org/doc/go1.11#modules][modules]] (experimental) for dependency
+supports [vendoring](https://golang.org/cmd/go/#hdr-Vendor_Directories) and
+[modules](https://golang.org/doc/go1.11#modules) (experimental) for dependency
management.
-Along with [[https://twitter.com/kelseyhightower/status/1035278586754813952][Cloud Functions support for Go]]
+Along with [Cloud Functions support for Go](https://twitter.com/kelseyhightower/status/1035278586754813952)
(more on that in a future post), App Engine provides a compelling way to run Go
code on Google Cloud Platform (GCP) with no concern for the underlying
infrastructure.
Let’s take a look at creating a small application for App Engine. For the
example here, we assume a `GOPATH`-based workflow, although Go modules have
-[[https://cloud.google.com/appengine/docs/standard/go111/specifying-dependencies][experimental support]]
+[experimental support](https://cloud.google.com/appengine/docs/standard/go111/specifying-dependencies)
as well.
First, you create the application in your `GOPATH`:
@@ -59,9 +60,9 @@
Finally, set your machine up with a Google Cloud Platform account:
-- Create an account with [[GCP][https://cloud.google.com]].
-- [[https://cloud.google.com/resource-manager/docs/creating-managing-projects][Create a project]].
-- Install the [[https://cloud.google.com/sdk/][Cloud SDK]] on your system.
+ - Create an account with [https://cloud.google.com](GCP).
+ - [Create a project](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
+ - Install the [Cloud SDK](https://cloud.google.com/sdk/) on your system.
With all the setup complete, you can deploy using one command:
@@ -69,8 +70,8 @@
We think Go developers will find the new Go 1.11 runtime for App Engine an
exciting addition to the available options to run Go applications. There is a
-[[https://cloud.google.com/free/][free tier]]. Check out the
-[[https://cloud.google.com/appengine/docs/standard/go111/building-app/][getting started guide]]
+[free tier](https://cloud.google.com/free/). Check out the
+[getting started guide](https://cloud.google.com/appengine/docs/standard/go111/building-app/)
or the
-[[https://cloud.google.com/appengine/docs/standard/go111/go-differences][migration guide]]
-and deploy an app to the new runtime today!
\ No newline at end of file
+[migration guide](https://cloud.google.com/appengine/docs/standard/go111/go-differences)
+and deploy an app to the new runtime today!
diff --git a/content/building-stathat-with-go.article b/content/building-stathat-with-go.article
index ccf3daa..1a01559 100644
--- a/content/building-stathat-with-go.article
+++ b/content/building-stathat-with-go.article
@@ -1,17 +1,18 @@
-Building StatHat with Go
+# Building StatHat with Go
19 Dec 2011
Tags: guest
+Summary: My name is Patrick Crosby and I'm the founder of a company called Numerotron. We recently released [StatHat](http://www.stathat.com). This post is about why we chose to develop StatHat in [Go](https://golang.org), including details about how we are using Go.
Patrick Crosby
-* Introduction
+## Introduction
My name is Patrick Crosby and I'm the founder of a company called Numerotron.
-We recently released [[http://www.stathat.com][StatHat]].
-This post is about why we chose to develop StatHat in [[https://golang.org][Go]],
+We recently released [StatHat](http://www.stathat.com).
+This post is about why we chose to develop StatHat in [Go](https://golang.org),
including details about how we are using Go.
-[[http://www.stathat.com][StatHat]] is a tool to track statistics and events in your code.
+[StatHat](http://www.stathat.com) is a tool to track statistics and events in your code.
Everyone from HTML designers to backend engineers can use StatHat easily,
as it supports sending stats from HTML, JavaScript,
Go, and twelve other languages.
@@ -29,7 +30,7 @@
.image building-stathat-with-go_weather.png
-* Architecture Overview
+## Architecture Overview
StatHat consists of two main services: incoming statistic/event API calls
and the web application for viewing and analyzing stats.
@@ -56,27 +57,27 @@
http, command line, automated tests, mobile API.
StatHat uses MySQL for data storage.
-* Choosing Go
+## Choosing Go
When we designed StatHat, we had the following check list for our development tools:
-- same programming language for backend and frontend systems
+ - same programming language for backend and frontend systems
-- good, fast HTML templating system
+ - good, fast HTML templating system
-- fast start-up, recompilation, testing for lots of tinkering
+ - fast start-up, recompilation, testing for lots of tinkering
-- lots of connections on one machine
+ - lots of connections on one machine
-- language tools for handling application-level concurrency
+ - language tools for handling application-level concurrency
-- good performance
+ - good performance
-- robust RPC layer to talk between tiers
+ - robust RPC layer to talk between tiers
-- lots of libraries
+ - lots of libraries
-- open source
+ - open source
We evaluated many popular and not-so-popular web technologies and ended up choosing to develop it in Go.
@@ -85,30 +86,30 @@
goroutines, channels, garbage collection,
and all the packages that were available.
I was especially pleased with how few lines of code my applications were using.
-I soon experimented with making a web app called [[http://langalot.com/][Langalot]]
+I soon experimented with making a web app called [Langalot](http://langalot.com/)
that concurrently searched through five foreign language dictionaries as
you typed in a query.
It was blazingly fast. I put it online and it's been running since February, 2010.
The following sections detail how Go meets StatHat's requirements and our experience using Go to solve our problems.
-* Runtime
+## Runtime
-We use the standard Go [[https://golang.org/pkg/http/][http package]] for
+We use the standard Go [http package](https://golang.org/pkg/http/) for
our API and web app servers.
All requests first go through Nginx and any non-file requests are proxied
to the Go-powered http servers.
-The backend servers are all written in Go and use the [[https://golang.org/pkg/rpc/][rpc package]]
+The backend servers are all written in Go and use the [rpc package](https://golang.org/pkg/rpc/)
to communicate with the frontend.
-* Templating
+## Templating
-We built a template system using the standard [[https://golang.org/pkg/template/][template package]].
+We built a template system using the standard [template package](https://golang.org/pkg/template/).
Our system adds layouts, some common formatting functions,
and the ability to recompile templates on-the-fly during development.
We are very pleased with the performance and functionality of the Go templates.
-* Tinkering
+## Tinkering
In a previous job, I worked on a video game called Throne of Darkness that was written in C++.
We had a few header files that, when modified,
@@ -126,18 +127,18 @@
The result is that the StatHat system is very easy to work with,
and the compiler is not a bottleneck.
-* RPC
+## RPC
Since StatHat is a multi-tiered system, we wanted an RPC layer so that all
communication was standard.
-With Go, we are using the [[https://golang.org/pkg/rpc/][rpc package]] and
-the [[https://golang.org/pkg/gob/][gob package]] for encoding Go objects.
+With Go, we are using the [rpc package](https://golang.org/pkg/rpc/) and
+the [gob package](https://golang.org/pkg/gob/) for encoding Go objects.
In Go, the RPC server just takes any Go object and registers its exported methods.
There is no need for an intermediary interface description language.
We've found it very easy to use and many of our core application servers
are under 300 lines of code.
-* Libraries
+## Libraries
We don't want to spend time rewriting libraries for things like SSL,
database drivers, JSON/XML parsers.
@@ -145,7 +146,7 @@
number of user-contributed packages.
With only a few exceptions, we have found Go packages for everything we have needed.
-* Open source
+## Open source
In our experience, it has been invaluable to work with open source tools.
If something is going awry, it is immensely helpful to be able to examine
@@ -156,7 +157,7 @@
we frequently read the tests as they often give great examples of how to
use packages and language features.
-* Performance
+## Performance
People rely on StatHat for up to the minute analysis of their data and we
need the system to be as responsive as possible.
@@ -169,7 +170,7 @@
We've also taken advantage of the benchmark performance testing features
of the Go testing package.
-* Application-Level Concurrency
+## Application-Level Concurrency
In a former life, I was the CTO at OkCupid.
My experience there using OKWS taught me the importance of async programming,
@@ -183,17 +184,17 @@
StatHat uses goroutines extensively to run multiple functions concurrently
and channels for sharing data between goroutines.
-* Hosting and Deployment
+## Hosting and Deployment
StatHat runs on Amazon's EC2 servers. Our servers are divided into several types:
-- API
+ - API
-- Web
+ - Web
-- Application servers
+ - Application servers
-- Database
+ - Database
There are at least two of each type of server,
and they are in different zones for high availability.
@@ -208,11 +209,11 @@
for running and starts/stops/restarts any services.
We frequently only deploy to a subset of the servers.
-* More
+## More
-For more information on StatHat, please visit [[http://www.stathat.com][stathat.com]].
+For more information on StatHat, please visit [stathat.com](http://www.stathat.com).
We are releasing some of the Go code we've written.
-Go to [[http://www.stathat.com/src][www.stathat.com/src]] for all of the
+Go to [www.stathat.com/src](http://www.stathat.com/src) for all of the
open source StatHat projects.
-To learn more about Go, visit [[https://golang.org/][golang.org]].
+To learn more about Go, visit [golang.org](https://golang.org/).
diff --git a/content/c-go-cgo.article b/content/c-go-cgo.article
index 2ee6e92..912ed32 100644
--- a/content/c-go-cgo.article
+++ b/content/c-go-cgo.article
@@ -1,10 +1,11 @@
-C? Go? Cgo!
+# C? Go? Cgo!
17 Mar 2011
Tags: cgo, technical
+Summary: Cgo lets Go packages call C code. Given a Go source file written with some special features, cgo outputs Go and C files that can be combined into a single Go package.
Andrew Gerrand
-* Introduction
+## Introduction
Cgo lets Go packages call C code. Given a Go source file written with some special features,
cgo outputs Go and C files that can be combined into a single Go package.
@@ -56,15 +57,15 @@
}
The `Seed` function does the reverse, in a way.
-It takes a regular Go `int`, converts it to the C `unsigned`int` type,
+It takes a regular Go `int`, converts it to the C `unsigned int` type,
and passes it to the C function `srandom`.
func Seed(i int) {
C.srandom(C.uint(i))
}
-Note that cgo knows the `unsigned`int` type as `C.uint`;
-see the [[https://golang.org/cmd/cgo][cgo documentation]] for a complete
+Note that cgo knows the `unsigned int` type as `C.uint`;
+see the [cgo documentation](https://golang.org/cmd/cgo) for a complete
list of these numeric type names.
The one detail of this example we haven't examined yet is the comment above the `import` statement.
@@ -84,13 +85,13 @@
when building the C parts of the package.
There is a limitation: if your program uses any `//export` directives,
-then the C code in the comment may only include declarations (`extern`int`f();`),
-not definitions (`int`f()`{`return`1;`}`).
+then the C code in the comment may only include declarations (`extern int f();`),
+not definitions (`int f() { return 1; }`).
You can use `//export` directives to make Go functions accessible to C code.
-The `#cgo` and `//export` directives are documented in the [[https://golang.org/cmd/cgo/][cgo documentation]].
+The `#cgo` and `//export` directives are documented in the [cgo documentation](https://golang.org/cmd/cgo/).
-* Strings and things
+## Strings and things
Unlike Go, C doesn't have an explicit string type. Strings in C are represented by a zero-terminated array of chars.
@@ -119,9 +120,9 @@
you must remember to free the memory when you're done with it by calling `C.free`.
The call to `C.CString` returns a pointer to the start of the char array,
-so before the function exits we convert it to an [[https://golang.org/pkg/unsafe/#Pointer][`unsafe.Pointer`]]
+so before the function exits we convert it to an [`unsafe.Pointer`](https://golang.org/pkg/unsafe/#Pointer)
and release the memory allocation with `C.free`.
-A common idiom in cgo programs is to [[https://golang.org/doc/articles/defer_panic_recover.html][`defer`]]
+A common idiom in cgo programs is to [`defer`](https://golang.org/doc/articles/defer_panic_recover.html)
the free immediately after allocating (especially when the code that follows
is more complex than a single function call),
as in this rewrite of `Print`:
@@ -132,18 +133,18 @@
C.fputs(cs, (*C.FILE)(C.stdout))
}
-* Building cgo packages
+## Building cgo packages
-To build cgo packages, just use [[https://golang.org/cmd/go/#Compile_packages_and_dependencies][`go`build`]]
-or [[https://golang.org/cmd/go/#Compile_and_install_packages_and_dependencies][`go`install`]] as usual.
+To build cgo packages, just use [`go build`](https://golang.org/cmd/go/#Compile_packages_and_dependencies)
+or [`go install`](https://golang.org/cmd/go/#Compile_and_install_packages_and_dependencies) as usual.
The go tool recognizes the special `"C"` import and automatically uses cgo for those files.
-* More cgo resources
+## More cgo resources
-The [[https://golang.org/cmd/cgo/][cgo command]] documentation has more
+The [cgo command](https://golang.org/cmd/cgo/) documentation has more
detail about the C pseudo-package and the build process.
-The [[https://golang.org/misc/cgo/][cgo examples]] in the Go tree demonstrate
+The [cgo examples](https://golang.org/misc/cgo/) in the Go tree demonstrate
more advanced concepts.
Finally, if you're curious as to how all this works internally,
-take a look at the introductory comment of the runtime package's [[https://golang.org/src/runtime/cgocall.go][cgocall.go]].
+take a look at the introductory comment of the runtime package's [cgocall.go](https://golang.org/src/runtime/cgocall.go).
diff --git a/content/community-outreach-working-group.article b/content/community-outreach-working-group.article
index df97301..d224f11 100644
--- a/content/community-outreach-working-group.article
+++ b/content/community-outreach-working-group.article
@@ -1,11 +1,12 @@
-Community Outreach Working Group
+# Community Outreach Working Group
5 Sep 2017
Tags: community
+Summary: The Go project has grown considerably with over half a million users and community members all over the world. To date all community oriented activities have been organized by the community with minimal involvement from the Go project. We greatly appreciate these efforts.
Steve Francia & Cassandra Salisbury
spf@golang.org
-* Announcing the Go Community Outreach Working Group
+## Announcing the Go Community Outreach Working Group
The Go project has grown considerably with over half a million users and
community members all over the world. To date all community oriented activities
@@ -17,7 +18,7 @@
the Go project. We are forming the Community outreach Working Group (CWG)
to help support these community efforts.
-* The CWG Mission
+## The CWG Mission
The mission of the CWG is to act as a conduit between the broader Go
community, it’s organizers and the Go project. The CWG will help provide
@@ -25,29 +26,29 @@
in person community that is enjoyable and rewarding to participate in. The
CWG leadership represents the Go project in these efforts.
-*The*CWG*is*responsible*for:*
+**The CWG is responsible for:**
-- Defining programs to facilitate deeper collaboration across the community.
-- Facilitating the coordination of Go events
-- Establishing growth and expansion plans for the community
-- Project exposure and accessibility
-- Ecosystem Development
+ - Defining programs to facilitate deeper collaboration across the community.
+ - Facilitating the coordination of Go events
+ - Establishing growth and expansion plans for the community
+ - Project exposure and accessibility
+ - Ecosystem Development
-*Leadership:*
+**Leadership:**
-- [[https://twitter.com/ashleymcnamara][Ashley McNamara]]
-- [[https://twitter.com/Cassandraoid][Cassandra Salisbury]]
-- [[https://twitter.com/francesc][Francesc Campoy]]
-- [[https://twitter.com/spf13][Steve Francia]]
+ - [Ashley McNamara](https://twitter.com/ashleymcnamara)
+ - [Cassandra Salisbury](https://twitter.com/Cassandraoid)
+ - [Francesc Campoy](https://twitter.com/francesc)
+ - [Steve Francia](https://twitter.com/spf13)
-* Plans for Action
+## Plans for Action
-The CWG has an [[https://github.com/golang/cwg][open GitHub repo]] we’ve created for complete transparency
-of our efforts. We have various [[https://github.com/golang/cwg/projects][GitHub projects]] which are acting as our
-primary initiatives. Each project has a variety of [[https://github.com/golang/cwg/issues][issues]] tied to them
-with assignees from our Leadership team and [[https://github.com/golang/cwg/issues/15][our members]].
+The CWG has an [open GitHub repo](https://github.com/golang/cwg) we’ve created for complete transparency
+of our efforts. We have various [GitHub projects](https://github.com/golang/cwg/projects) which are acting as our
+primary initiatives. Each project has a variety of [issues](https://github.com/golang/cwg/issues) tied to them
+with assignees from our Leadership team and [our members](https://github.com/golang/cwg/issues/15).
.image community-outreach-working-group/project.png
If you’d like to get involved, we encourage you to comment on the issue
-that interests you or [[https://github.com/golang/cwg/issues/new][submit an issue]] yourself!
+that interests you or [submit an issue](https://github.com/golang/cwg/issues/new) yourself!
diff --git a/content/company-questionnaire2018.article b/content/company-questionnaire2018.article
index 5395b41..5066f92 100644
--- a/content/company-questionnaire2018.article
+++ b/content/company-questionnaire2018.article
@@ -1,38 +1,39 @@
-Participate in the 2018 Go Company Questionnaire
+# Participate in the 2018 Go Company Questionnaire
4 Oct 2018
Tags: survey, community
+Summary: We need your help to create the best programming language for developing simple, reliable, and scalable software. To do this, we need to better understand how companies are using Go. Please help by participating in a 7-minute company questionnaire.
Ran Tao, Steve Francia
spf@golang.org
-* The Go project wants to hear from you!
+## The Go project wants to hear from you!
We need your help to create the best programming language for developing
simple, reliable, and scalable software. To do this, we need to better
understand how companies are using Go. Please help by participating in a
7-minute company questionnaire.
-*Who:* If you are in a position to share details like “company name,” “if your
+**Who:** If you are in a position to share details like “company name,” “if your
company is hiring Go developers,” and “reasons your team or company adopted Go”
then please help us by taking this company questionnaire. We only need one
response per company (or per department for larger companies). If you aren’t the
right person, please forward this onto the right person at your company.
-_Please_note:_this_is_different_from_our_annual_anonymous_Go_user_survey,_which_
-_will_be_announced_in_November._
+_Please note: this is different from our annual anonymous Go user survey, which_
+_will be announced in November._
-*Where:* Please take this 7-minute questionnaire by October 30th:
-[[http://goo.gl/nnPfct][Go Company Questionnaire 2018]].
+**Where:** Please take this 7-minute questionnaire by October 30th:
+[Go Company Questionnaire 2018](http://goo.gl/nnPfct).
The questionnaire is confidential, but not anonymous. For more information,
please refer to Google’s privacy policy
-[[https://policies.google.com/privacy][here]].
+[here](https://policies.google.com/privacy).
The Go project leadership will use your responses to better understand how
companies use Go and in what ways we can improve their experience.
-* Spread the word!
+## Spread the word!
We would like as many companies as possible to participate to help us better
understand our global user base. Please help us spread the word by sharing this
-post on your social network feeds, at meetups, and in other communities.
\ No newline at end of file
+post on your social network feeds, at meetups, and in other communities.
diff --git a/content/concurrency-is-not-parallelism.article b/content/concurrency-is-not-parallelism.article
index 41563e9..5ba96d0 100644
--- a/content/concurrency-is-not-parallelism.article
+++ b/content/concurrency-is-not-parallelism.article
@@ -1,10 +1,11 @@
-Concurrency is not parallelism
+# Concurrency is not parallelism
16 Jan 2013
Tags: concurrency, talk, video
+Summary: If there's one thing most people know about Go, is that it is designed for concurrency. No introduction to Go is complete without a demonstration of its goroutines and channels.
Andrew Gerrand
-* Introduction
+##
If there's one thing most people know about Go,
is that it is designed for concurrency.
@@ -14,18 +15,18 @@
a related but quite distinct concept.
In programming, concurrency is the _composition_ of independently executing processes,
while parallelism is the simultaneous _execution_ of (possibly related) computations.
-Concurrency is about _dealing_with_ lots of things at once.
+Concurrency is about _dealing with_ lots of things at once.
Parallelism is about _doing_ lots of things at once.
-To clear up this conflation, Rob Pike gave a talk at [[http://heroku.com/][Heroku]]'s
-[[http://waza.heroku.com/][Waza]] conference entitled _Concurrency_is_not_parallelism_,
+To clear up this conflation, Rob Pike gave a talk at [Heroku](http://heroku.com/)'s
+[Waza](http://waza.heroku.com/) conference entitled _Concurrency is not parallelism_,
and a video recording of the talk was released a few months ago.
.iframe //player.vimeo.com/video/49718712?badge=0 281 500
-The slides are available at [[https://talks.golang.org/2012/waza.slide][talks.golang.org]]
+The slides are available at [talks.golang.org](https://talks.golang.org/2012/waza.slide)
(use the left and right arrow keys to navigate).
To learn about Go's concurrency primitives,
-watch [[http://www.youtube.com/watch?v=f6kdp27TYZs][Go concurrency patterns]]
-([[https://talks.golang.org/2012/concurrency.slide][slides]]).
+watch [Go concurrency patterns](http://www.youtube.com/watch?v=f6kdp27TYZs)
+([slides](https://talks.golang.org/2012/concurrency.slide)).
diff --git a/content/conduct-2018.article b/content/conduct-2018.article
index 7fbda8c..1e76e8d 100644
--- a/content/conduct-2018.article
+++ b/content/conduct-2018.article
@@ -1,10 +1,11 @@
-Updating the Go Code of Conduct
+# Updating the Go Code of Conduct
23 May 2018
Tags: conduct
+Summary: In November 2015, we introduced the Go Code of Conduct. It was developed in a collaboration between the Go team members at Google and the Go community. I was fortunate to be one of the community members invited to participate in both drafting and then enforcing the Go Code of Conduct. Since then, we have learned two lessons about limitations in our code of conduct that restricted us from being able to cultivate the safe culture essential to Go’s success.
Steve Francia
-* Introduction
+##
In November 2015, we introduced the Go Code of Conduct.
It was developed in a collaboration between
@@ -33,7 +34,7 @@
of conduct place too heavy of a burden on volunteers.
The initial version of the code of conduct presented the
working group as disciplinarians. It was soon clear
-that this was too much, so in early 2017 [[https://golang.org/cl/37014][we changed the group’s role]]
+that this was too much, so in early 2017 [we changed the group’s role](https://golang.org/cl/37014)
to that of advisors and mediators.
Still, working group community members
reported feeling overwhelmed, untrained, and vulnerable.
@@ -51,15 +52,15 @@
Contributor Covenant Code of Conduct v1.4
and then made changes, influenced by
our experiences in Go community and our collective experiences in open source.
-This resulted in the Google [[https://opensource.google.com/docs/releasing/template/CODE_OF_CONDUCT/][code of conduct template]].
+This resulted in the Google [code of conduct template](https://opensource.google.com/docs/releasing/template/CODE_OF_CONDUCT/).
Today the Go project is adopting this new code of conduct,
-and we’ve updated [[https://golang.org/conduct][golang.org/conduct]].
+and we’ve updated [golang.org/conduct](https://golang.org/conduct).
This revised code of conduct retains much of the intent, structure and
language of the original Go code of conduct while making two critical
changes that address the shortcomings identified above.
-First, [[https://golang.org/conduct/#scope][the new code of conduct makes clear]] that people who
+First, [the new code of conduct makes clear](https://golang.org/conduct/#scope) that people who
participate in any kind of harassment or inappropriate behavior,
even outside our project spaces, are not welcome in our project spaces.
This means that the Code of Conduct applies outside
@@ -68,7 +69,7 @@
impact on the project or its community.
Second, in the place of the working group,
-[[https://golang.org/conduct/#reporting][the new code of conduct introduces a single Project Steward]]
+[the new code of conduct introduces a single Project Steward](https://golang.org/conduct/#reporting)
who will have explicit training and support for this role.
The Project Steward will receive reported violations
and then work with a committee,
@@ -76,7 +77,7 @@
and the Google Open Source Strategy team,
to find a resolution.
-Our first Project Steward will be [[https://twitter.com/cassandraoid][Cassandra Salisbury]].
+Our first Project Steward will be [Cassandra Salisbury](https://twitter.com/cassandraoid).
She is well known to the Go community as a member of Go Bridge,
an organizer of many Go meetups and conferences,
and as a lead of the Go community outreach working group.
diff --git a/content/constants.article b/content/constants.article
index 5148cf1..c165733 100644
--- a/content/constants.article
+++ b/content/constants.article
@@ -1,10 +1,11 @@
-Constants
+# Constants
25 Aug 2014
Tags: constants
+Summary: Go is a statically typed language that does not permit operations that mix numeric types. You can't add a `float64` to an `int`, or even an `int32` to an `int`. Yet it is legal to write `1e6*time.Second` or `math.Exp(1)` or even `1<<('\t'+2.0)`. In Go, constants, unlike variables, behave pretty much like regular numbers. This post explains why that is and what it means.
Rob Pike
-* Introduction
+## Introduction
Go is a statically typed language that does not permit operations that mix numeric types.
You can't add a `float64` to an `int`, or even an `int32` to an `int`.
@@ -12,7 +13,7 @@
In Go, constants, unlike variables, behave pretty much like regular numbers.
This post explains why that is and what it means.
-* Background: C
+## Background: C
In the early days of thinking about Go, we talked about a number of problems
caused by the way C and its descendants let you mix and match numeric types.
@@ -24,7 +25,7 @@
long signed int i = -1;
... i + u ...
-may be familiar, it isn't _a_priori_ obvious.
+may be familiar, it isn't _a priori_ obvious.
How big is the result?
What is its value?
Is it signed or unsigned?
@@ -67,7 +68,7 @@
In short, constants in Go just work, most of the time anyway.
Let's see how that happens.
-* Terminology
+## Terminology
First, a quick definition.
In Go, `const` is a keyword introducing a name for a scalar value such as `2` or `3.14159` or `"scrumptious"`.
@@ -82,7 +83,7 @@
But in Go, a constant is just a simple, unchanging value, and from here on we're talking only about Go.
-* String constants
+## String constants
There are many kinds of numeric constants—integers,
floats, runes, signed, unsigned, imaginary,
@@ -91,19 +92,19 @@
to explore the type issues of constants in Go.
A string constant encloses some text between double quotes.
-(Go also has raw string literals, enclosed by backquotes ``````,
+(Go also has raw string literals, enclosed by backquotes ````````,
but for the purpose of this discussion they have all the same properties.)
Here is a string constant:
"Hello, 世界"
(For much more detail about the representation and interpretation of strings,
-see [[https://blog.golang.org/strings][this blog post]].)
+see [this blog post](https://blog.golang.org/strings).)
What type does this string constant have?
The obvious answer is `string`, but that is _wrong_.
-This is an _untyped_string_constant_, which is to say it is a constant textual
+This is an _untyped string constant_, which is to say it is a constant textual
value that does not yet have a fixed type.
Yes, it's a string, but it's not a Go value of type `string`.
It remains an untyped string constant even when given a name:
@@ -152,14 +153,14 @@
m = hello
because, unlike the typed constants `typedHello` and `myStringHello`,
-the untyped constants `"Hello,`世界"` and `hello` _have_no_type_.
+the untyped constants `"Hello, 世界"` and `hello` _have no type_.
Assigning them to a variable of any type compatible with strings works without error.
These untyped string constants are strings,
of course, so they can only be used where a string is allowed,
but they do not have _type_ `string`.
-* Default type
+## Default type
As a Go programmer, you have certainly seen many declarations like
@@ -214,18 +215,18 @@
.play -edit constants/default3.go /START/,/STOP/
(For more information about how interface values work,
-see the first sections of [[https://blog.golang.org/laws-of-reflection][this blog post]].)
+see the first sections of [this blog post](https://blog.golang.org/laws-of-reflection).)
In summary, a typed constant obeys all the rules of typed values in Go.
On the other hand, an untyped constant does not carry a Go type in the same
way and can be mixed and matched more freely.
It does, however, have a default type that is exposed when, and only when, no other type information is available.
-* Default type determined by syntax
+## Default type determined by syntax
The default type of an untyped constant is determined by its syntax.
For string constants, the only possible implicit type is `string`.
-For [[https://golang.org/ref/spec#Numeric_types][numeric constants]], the implicit type has more variety.
+For [numeric constants](https://golang.org/ref/spec#Numeric_types), the implicit type has more variety.
Integer constants default to `int`, floating-point constants `float64`,
rune constants to `rune` (an alias for `int32`),
and imaginary constants to `complex128`.
@@ -235,7 +236,7 @@
(Exercise: Explain the result for `'x'`.)
-* Booleans
+## Booleans
Everything we said about untyped string constants can be said for untyped boolean constants.
The values `true` and `false` are untyped boolean constants that can be assigned to any boolean variable,
@@ -246,7 +247,7 @@
Run the example and see what happens, then comment out the "Bad" line and run it again.
The pattern here follows exactly that of string constants.
-* Floats
+## Floats
Floating-point constants are just like boolean constants in most respects.
Our standard example works as expected in translation:
@@ -283,7 +284,7 @@
In a related way, floating-point constants may have very high precision,
so that arithmetic involving them is more accurate.
-The constants defined in the [[https://golang.org/pkg/math][math]] package are given with many more digits than are
+The constants defined in the [math](https://golang.org/pkg/math) package are given with many more digits than are
available in a `float64`. Here is the definition of `math.Pi`:
Pi = 3.14159265358979323846264338327950288419716939937510582097494459
@@ -305,7 +306,7 @@
(Division by a constant zero is a compile-time error,
and when everything is a number there's no such thing as "not a number".)
-* Complex numbers
+## Complex numbers
Complex constants behave a lot like floating-point constants.
Here's a version of our now-familiar litany translated into complex numbers:
@@ -342,10 +343,10 @@
Even though `Two` is a complex constant, it can be assigned to scalar floating-point variables.
This ability for a constant to "cross" types like this will prove useful.
-* Integers
+## Integers
At last we come to integers.
-They have more moving parts—[[https://golang.org/ref/spec#Numeric_types][many sizes, signed or unsigned, and more]]—but
+They have more moving parts—[many sizes, signed or unsigned, and more](https://golang.org/ref/spec#Numeric_types)—but
they play by the same rules.
For the last time, here is our familiar example, using just `int` this time:
@@ -397,7 +398,7 @@
If the compiler complains about your use of a constant, it's likely a real bug like this.
-* An exercise: The largest unsigned int
+## An exercise: The largest unsigned int
Here is an informative little exercise.
How do we express a constant representing the largest value that fits in a `uint`?
@@ -409,7 +410,7 @@
The `int` and `uint` types have equal unspecified numbers of bits, either 32 or 64.
Since the number of bits available depends on the architecture, we can't just write down a single value.
-Fans of [[http://en.wikipedia.org/wiki/Two's_complement][two's-complement arithmetic]],
+Fans of [two's-complement arithmetic](http://en.wikipedia.org/wiki/Two's_complement),
which Go's integers are defined to use, know that the representation of `-1` has all its bits set to 1,
so the bit pattern of `-1` is internally the same as that of the
largest unsigned integer.
@@ -424,7 +425,7 @@
.play -edit constants/exercise2.go /const/
Even though at run-time a value of -1 can be converted to an unsigned integer, the rules
-for constant [[https://golang.org/ref/spec#Conversions][conversions]] forbid this kind of coercion at compile time.
+for constant [conversions](https://golang.org/ref/spec#Conversions) forbid this kind of coercion at compile time.
That is to say, this works:
.play -edit constants/exercise3.go /START/,/STOP/
@@ -456,13 +457,13 @@
.play -edit constants/exercise6.go /START/,/STOP/
Whatever the number of bits it takes to represent a `uint` in the current execution environment
-(on the [[https://blog.golang.org/playground][playground]], it's 32),
+(on the [playground](https://blog.golang.org/playground), it's 32),
this constant correctly represents the largest value a variable of type `uint` can hold.
If you understand the analysis that got us to this result,
you understand all the important points about constants in Go.
-* Numbers
+## Numbers
The concept of untyped constants in Go means that all the numeric constants,
whether integer, floating-point, complex,
@@ -486,7 +487,7 @@
.play -edit constants/numbers1.go /START/,/STOP/
-The output from this snippet is: `1`1`1`1`1`(1+0i)`1`.
+The output from this snippet is: `1 1 1 1 1 (1+0i) 1`.
You can even do nutty stuff like
diff --git a/content/context.article b/content/context.article
index 68c7f23..47c320d 100644
--- a/content/context.article
+++ b/content/context.article
@@ -1,10 +1,11 @@
-Go Concurrency Patterns: Context
+# Go Concurrency Patterns: Context
29 Jul 2014
Tags: concurrency, cancelation, cancellation, context
+Summary: In Go servers, each incoming request is handled in its own goroutine. Request handlers often start additional goroutines to access backends such as databases and RPC services. The set of goroutines working on a request typically needs access to request-specific values such as the identity of the end user, authorization tokens, and the request's deadline. When a request is canceled or times out, all the goroutines working on that request should exit quickly so the system can reclaim any resources they are using.
Sameer Ajmani
-* Introduction
+## Introduction
In Go servers, each incoming request is handled in its own goroutine.
Request handlers often start additional goroutines to access backends such as
@@ -20,24 +21,24 @@
request-scoped values, cancelation signals, and deadlines across API boundaries
to all the goroutines involved in handling a request.
The package is publicly available as
-[[https://golang.org/pkg/context][context]].
+[context](https://golang.org/pkg/context).
This article describes how to use the package and provides a complete working
example.
-* Context
+## Context
The core of the `context` package is the `Context` type:
.code context/interface.go /A Context/,/^}/
(This description is condensed; the
-[[https://golang.org/pkg/context][godoc]] is authoritative.)
+[godoc](https://golang.org/pkg/context) is authoritative.)
The `Done` method returns a channel that acts as a cancelation signal to
functions running on behalf of the `Context`: when the channel is closed, the
functions should abandon their work and return.
The `Err` method returns an error indicating why the `Context` was canceled.
-The [[/pipelines][Pipelines and Cancelation]] article discusses the `Done`
+The [Pipelines and Cancelation](/pipelines) article discusses the `Done`
channel idiom in more detail.
A `Context` does _not_ have a `Cancel` method for the same reason the `Done`
@@ -59,7 +60,7 @@
`Value` allows a `Context` to carry request-scoped data.
That data must be safe for simultaneous use by multiple goroutines.
-** Derived contexts
+### Derived contexts
The `context` package provides functions to _derive_ new `Context` values from
existing ones.
@@ -87,24 +88,24 @@
The best way to see how to use the `context` package is through a worked
example.
-* Example: Google Web Search
+## Example: Google Web Search
Our example is an HTTP server that handles URLs like
`/search?q=golang&timeout=1s` by forwarding the query "golang" to the
-[[https://developers.google.com/web-search/docs/][Google Web Search API]] and
+[Google Web Search API](https://developers.google.com/web-search/docs/) and
rendering the results.
The `timeout` parameter tells the server to cancel the request after that
duration elapses.
The code is split across three packages:
-- [[context/server/server.go][server]] provides the `main` function and the handler for `/search`.
-- [[context/userip/userip.go][userip]] provides functions for extracting a user IP address from a request and associating it with a `Context`.
-- [[context/google/google.go][google]] provides the `Search` function for sending a query to Google.
+ - [server](context/server/server.go) provides the `main` function and the handler for `/search`.
+ - [userip](context/userip/userip.go) provides functions for extracting a user IP address from a request and associating it with a `Context`.
+ - [google](context/google/google.go) provides the `Search` function for sending a query to Google.
-** The server program
+### The server program
-The [[context/server/server.go][server]] program handles requests like
+The [server](context/server/server.go) program handles requests like
`/search?q=golang` by serving the first few Google search results for `golang`.
It registers `handleSearch` to handle the `/search` endpoint.
The handler creates an initial `Context` called `ctx` and arranges for it to be
@@ -129,9 +130,9 @@
.code context/server/server.go /resultsTemplate/,/}$/
-** Package userip
+### Package userip
-The [[context/userip/userip.go][userip]] package provides functions for
+The [userip](context/userip/userip.go) package provides functions for
extracting a user IP address from a request and associating it with a `Context`.
A `Context` provides a key-value mapping, where the keys and values are both of
type `interface{}`.
@@ -157,10 +158,10 @@
.code context/userip/userip.go /func FromContext/,/}/
-** Package google
+### Package google
-The [[context/google/google.go][google.Search]] function makes an HTTP request
-to the [[https://developers.google.com/web-search/docs/][Google Web Search API]]
+The [google.Search](context/google/google.go) function makes an HTTP request
+to the [Google Web Search API](https://developers.google.com/web-search/docs/)
and parses the JSON-encoded result.
It accepts a `Context` parameter `ctx` and returns immediately if `ctx.Done` is
closed while the request is in flight.
@@ -182,7 +183,7 @@
.code context/google/google.go /func httpDo/,/^}/
-* Adapting code for Contexts
+## Adapting code for Contexts
Many server frameworks provide packages and types for carrying request-scoped
values.
@@ -190,23 +191,23 @@
code using existing frameworks and code that expects a `Context` parameter.
For example, Gorilla's
-[[http://www.gorillatoolkit.org/pkg/context][github.com/gorilla/context]]
+[github.com/gorilla/context](http://www.gorillatoolkit.org/pkg/context)
package allows handlers to associate data with incoming requests by providing a
mapping from HTTP requests to key-value pairs.
-In [[context/gorilla/gorilla.go][gorilla.go]], we provide a `Context`
+In [gorilla.go](context/gorilla/gorilla.go), we provide a `Context`
implementation whose `Value` method returns the values associated with a
specific HTTP request in the Gorilla package.
Other packages have provided cancelation support similar to `Context`.
-For example, [[https://godoc.org/gopkg.in/tomb.v2][Tomb]] provides a `Kill`
+For example, [Tomb](https://godoc.org/gopkg.in/tomb.v2) provides a `Kill`
method that signals cancelation by closing a `Dying` channel.
`Tomb` also provides methods to wait for those goroutines to exit, similar to
`sync.WaitGroup`.
-In [[context/tomb/tomb.go][tomb.go]], we provide a `Context` implementation that
+In [tomb.go](context/tomb/tomb.go), we provide a `Context` implementation that
is canceled when either its parent `Context` is canceled or a provided `Tomb` is
killed.
-* Conclusion
+## Conclusion
At Google, we require that Go programmers pass a `Context` parameter as the
first argument to every function on the call path between incoming and outgoing
diff --git a/content/contributor-workshop.article b/content/contributor-workshop.article
index 3560c6c..e7cdd28 100644
--- a/content/contributor-workshop.article
+++ b/content/contributor-workshop.article
@@ -1,14 +1,14 @@
-Contribution Workshop
+# Contribution Workshop
9 Aug 2017
Tags: community
Steve Francia, Cassandra Salisbury, Matt Broberg, Dmitri Shuralyov
-* Contribution Workshop
+##
-** Event Overview
+## Event Overview
-by [[https://twitter.com/spf13][Steve]]
+by [Steve](https://twitter.com/spf13)
During the community day at GopherCon, the Go team held two workshops
where we worked with people to help them make their first contribution to the
@@ -26,7 +26,7 @@
section and built a tool `go-contrib-init`, which automated the process of
setting up a development environment to be able to contribute to Go.
-For the workshop itself, we developed a presentation _"Contributing_to_Go,"_
+For the workshop itself, we developed a presentation _"Contributing to Go,"_
and a dashboard / scoreboard that was presented during the event. The
scoreboard was designed to encourage us all to work together towards a common
goal of seeing our collective score increase. Participants added 1, 2 or 3 points to
@@ -44,7 +44,7 @@
.image contributor-workshop/image9.jpg
.image contributor-workshop/image6.png
-*** Impact
+### Impact
We had a total of 65 CLs submitted from the people who participated in the
workshop (within a week of the workshop). Of these, 44 were from contributors
@@ -53,35 +53,35 @@
waiting on the codebase to thaw as we are in the middle of a freeze for the
upcoming 1.9 release. In addition to CLs, many contributed to the project in
the form of bug reports,
-[[https://golang.org/wiki/Gardening][gardening tasks]], and other types
+[gardening tasks](https://golang.org/wiki/Gardening), and other types
of contributions.
The most common type of contribution was an example function to be used in the
-documentation. The [[https://blog.golang.org/survey2016-results][Go User survey]]
+documentation. The [Go User survey](https://blog.golang.org/survey2016-results)
identified that our documentation was significantly lacking examples. In the
presentation, we asked users to find a package they loved and to add an example. In
the Go project, examples are written as code in Go files
-(with specific naming) and the `go`doc` tool displays them along side the documentation.
+(with specific naming) and the `go doc` tool displays them along side the documentation.
This is a perfect first contribution as it's something that can be merged
during a freeze, it's of critical importance to our users, and it's an addition
that has a relatively narrow scope.
One of the examples added is that of creating a Stringer, one of the more
widely used interfaces in Go.
-[[https://golang.org/cl/49270/][CL 49270]]
+[CL 49270](https://golang.org/cl/49270/)
In addition to examples, many people contributed critical bug fixes including:
-- [[https://golang.org/cl/48988/][CL 48988]] fixing [[https://golang.org/issue/21029][issue #21029]]
-- [[https://golang.org/cl/49050/][CL 49050]] fixing [[https://golang.org/issue/20054][issue #20054]]
-- [[https://golang.org/cl/49031/][CL 49031]] fixing [[https://golang.org/issue/20166][issue #20166]]
-- [[https://golang.org/cl/49170/][CL 49170]] fixing [[https://golang.org/issue/20877][issue #20877]]
+ - [CL 48988](https://golang.org/cl/48988/) fixing [issue #21029](https://golang.org/issue/21029)
+ - [CL 49050](https://golang.org/cl/49050/) fixing [issue #20054](https://golang.org/issue/20054)
+ - [CL 49031](https://golang.org/cl/49031/) fixing [issue #20166](https://golang.org/issue/20166)
+ - [CL 49170](https://golang.org/cl/49170/) fixing [issue #20877](https://golang.org/issue/20877)
Some people even surprised us by arriving with a bug in mind that they wanted
to fix. Nikhita arrived ready to tackle
-[[https://golang.org/issue/20786][issue #20786]]
+[issue #20786](https://golang.org/issue/20786)
and she did submitting
-[[https://golang.org/cl/48871/][CL 48871]],
+[CL 48871](https://golang.org/cl/48871/),
after which she tweeted:
.image contributor-workshop/image19.png
@@ -96,7 +96,7 @@
.image contributor-workshop/image13.png
.image contributor-workshop/image3.png
-*** Future
+### Future
The event was successful well beyond our expectations. Sameer Ajmani, Go team
manager said, "The contributor workshop was incredibly fun and educational–for
@@ -107,13 +107,13 @@
We are looking into ways to make this workshop easier to run for future events
(like meetups and conferences). Our biggest challenge is providing enough
mentorship so that users feel supported. If you have any ideas or would like to
-help with this process please [[mailto:spf@golang.org][let me know]].
+help with this process please [let me know](mailto:spf@golang.org).
I've asked a few participants of the event to share their experiences below:
-** My Contribution Experience
+## My Contribution Experience
-by [[https://twitter.com/cassandraoid][Cassandra]]
+by [Cassandra](https://twitter.com/cassandraoid)
When I heard about the go-contrib workshop I was very excited and then I was
extremely intimidated. I was encouraged by a member of the Go team to
@@ -126,7 +126,7 @@
Brought up my screen and was ready to roll…
Jess Frazelle stood up and started the presentation and provided the group with
-[[https://docs.google.com/presentation/d/1ap2fycBSgoo-jCswhK9lqgCIFroE1pYpsXC1ffYBCq4/edit#slide=id.p][a link]]
+[a link](https://docs.google.com/presentation/d/1ap2fycBSgoo-jCswhK9lqgCIFroE1pYpsXC1ffYBCq4/edit#slide=id.p)
to make it easy to follow.
.image contributor-workshop/image16.png
@@ -142,7 +142,7 @@
.image contributor-workshop/image10.png
-Ok, now it was time to become a *freaking*Go*contributor*.
+Ok, now it was time to become a **freaking Go contributor**.
To make this more exciting than it already is, the Go team set up a game where
we could track as a group how many points we could rack up based on the Gerrit
@@ -167,9 +167,9 @@
fellow participants for making it one of my most memorable moments at
GopherCon.
-** My Contribution Experience
+## My Contribution Experience
-by [[https://twitter.com/mbbroberg][Matt]]
+by [Matt](https://twitter.com/mbbroberg)
I've always found programming languages to be intimidating. It's the code that
enables the world to write code. Given the impact, surely smarter people than
@@ -180,9 +180,9 @@
Here are my very verbose steps to go from 0 to 2 contributions to Go:
-*** The Setup
+### The Setup
-Given Go's use of Gerrit, I started by setting up my environment for it. [[https://docs.google.com/presentation/d/1ap2fycBSgoo-jCswhK9lqgCIFroE1pYpsXC1ffYBCq4/edit#slide=id.g1f953ef7df_0_9][Jess Frazzelle's guide]]
+Given Go's use of Gerrit, I started by setting up my environment for it. [Jess Frazzelle's guide](https://docs.google.com/presentation/d/1ap2fycBSgoo-jCswhK9lqgCIFroE1pYpsXC1ffYBCq4/edit#slide=id.g1f953ef7df_0_9)
is a great place to start to not miss a step.
The real fun starts when you clone the Go repo. Ironically, you don't hack on
@@ -206,14 +206,14 @@
This package includes `git change` and `git mail` which will replace your
normal workflow of `git commit` and `git push` respectively.
-Okay, installations are out of the way. Now setup your [[https://go-review.googlesource.com/settings/#Profile][Gerrit account here]],
-then [[https://go-review.googlesource.com/settings#Agreements][sign the CLA]] appropriate for
+Okay, installations are out of the way. Now setup your [Gerrit account here](https://go-review.googlesource.com/settings/#Profile),
+then [sign the CLA](https://go-review.googlesource.com/settings#Agreements) appropriate for
you (I signed a personal one for all Google projects, but choose the right option for you.
-You can see all CLAs you've signed at [[https://cla.developers.google.com/clas][cla.developers.google.com/clas]]).
+You can see all CLAs you've signed at [cla.developers.google.com/clas](https://cla.developers.google.com/clas)).
AND BAM. You're good (to go)! But where to contribute?
-*** Contributing
+### Contributing
In the workshop, they sent us into the `scratch` repository, which is a safe place to
fool around in order to master the workflow:
@@ -236,7 +236,7 @@
Two good notes to take at this point: `git change` also works like `git commit --amend`, so
if you need to update your patch you can `add` then `change` and it will all
link to the same patch. Secondly, you can always review your patch from your
-[[https://go-review.googlesource.com/dashboard/][personal Gerrit dashboard]].
+[personal Gerrit dashboard](https://go-review.googlesource.com/dashboard/).
After a few back and forths, I officially had a contribute to Go! And if Jaana
is right, it might be the first with emojis ✌️.
@@ -244,7 +244,7 @@
.image contributor-workshop/image15.png
.image contributor-workshop/image23.png
-*** Contributing, For Real
+### Contributing, For Real
The scratch repo is fun and all, but there's a ton of ways to get into the
depths of Go's packages and give back. It's at this point where I cruised
@@ -256,7 +256,7 @@
I decided to see what I can do in the `regexp` package, maybe out of love and
fear of regex. Here's where I switched to the
-[[https://godoc.org/regexp][website's view of the package]] (it's good to know
+[website's view of the package](https://godoc.org/regexp) (it's good to know
that each standard package can be found at https://godoc.org/$PACKAGENAME). In
there I noticed that `QuoteMeta` was missing the same level of detailed examples
other functions have (and I could use the practice using Gerrit).
@@ -264,7 +264,7 @@
.image contributor-workshop/image1.png
I started looking at `go/src/regexp` to try to find where to add examples and I
-got lost pretty quickly. Lucky for me, [[https://twitter.com/francesc][Francesc]] was around that day. He walked
+got lost pretty quickly. Lucky for me, [Francesc](https://twitter.com/francesc) was around that day. He walked
me through how all examples are actually in-line tests in a `example_test.go`
file. They follow the format of test cases followed by "Output" commented out
and then the answers to the tests. For example:
@@ -288,23 +288,23 @@
but I think it's worth it on this one.
I can hear your question already: how did I verify it worked? Well it wasn't
-easy to be honest. Running `go`test`example_test.go`-run`QuoteMeta`-v` won't do
+easy to be honest. Running `go test example_test.go -run QuoteMeta -v` won't do
it since we're working outside of our $GOPATH. I struggled to figure it out
-until [[https://medium.com/@vCabbage/go-testing-standard-library-changes-1e9cbed11339][Kale Blakenship wrote this awesome post on testing in Go]].
+until [Kale Blakenship wrote this awesome post on testing in Go](https://medium.com/@vCabbage/go-testing-standard-library-changes-1e9cbed11339).
Bookmark this one for later.
-You can see my completed [[https://go-review.googlesource.com/c/49130/][contribution here]]. What I also hope you see is
+You can see my completed [contribution here](https://go-review.googlesource.com/c/49130/). What I also hope you see is
how simple it is to get into the flow of contributing. If you're like me,
you'll be good at finding a small typo or missing example in the docs to start to
get used to the `git codereview` workflow. After that, you'll be ready to find
-an open issue, ideally one [[https://github.com/golang/go/milestones][tagged for an upcoming release]], and give it a go. No matter
+an open issue, ideally one [tagged for an upcoming release](https://github.com/golang/go/milestones), and give it a go. No matter
what you choose to do, definitely go forth and do it. The Go team proved to me
just how much they care about helping us all contribute back. I can't wait for
my next `git mail`.
-** My Mentorship Experience
+## My Mentorship Experience
-by [[https://twitter.com/dmitshur][Dmitri]]
+by [Dmitri](https://twitter.com/dmitshur)
I was looking forward to participating in the Contribution Workshop event as a
mentor. I had high expectations for the event, and thought it was a great idea
@@ -323,12 +323,12 @@
After a few months passed, I thought "enough is enough," and decided to
dedicate an entire day of an upcoming weekend to figuring out the process. I
set aside all of Saturday for doing one thing: sending my first CL to Go. I
-opened up [[https://golang.org/doc/contribute.html][the Contribution Guide]]
+opened up [the Contribution Guide](https://golang.org/doc/contribute.html)
and started following all the steps, from the very top. Within an hour, I was
done. I had send my first CL. I was both in awe and shock. In awe, because I
had finally sent a contribution to Go, and it was accepted! In shock, because,
why did I wait so long to finally do this? Following the steps in
-[[https://golang.org/doc/contribute.html][the Contribution Guide]] was very
+[the Contribution Guide](https://golang.org/doc/contribute.html) was very
easy, and the entire process went completely smoothly. If only someone had told
me that I'd be done within an hour and nothing would go wrong, I would've done
it much sooner!
@@ -376,7 +376,7 @@
they sometimes found themselves. From what I can tell, many happy gophers
walked away from the event, myself included!
-** Photos from the event
+## Photos from the event
.image contributor-workshop/image2.jpg
.image contributor-workshop/image4.jpg
diff --git a/content/contributors-summit-2019.article b/content/contributors-summit-2019.article
index ae43178..58ec47c 100644
--- a/content/contributors-summit-2019.article
+++ b/content/contributors-summit-2019.article
@@ -1,10 +1,11 @@
-Contributors Summit 2019
+# Contributors Summit 2019
15 Aug 2019
Tags: community
+Summary: For the third year in a row, the Go team and contributors convened the day before GopherCon to discuss and plan for the future of the Go project. The event included self-organizing into breakout groups, a town-hall style discussion about the proposal process in the morning, and afternoon break-out roundtable discussions based on topics our contributors chose. We asked five contributors to write about their experience in various discussions at this year’s summit.
Carmen Andoh and contributors
-* Introduction
+## Introduction
For the third year in a row, the Go team and contributors convened
the day before GopherCon to discuss and plan for the future of the Go project.
@@ -17,9 +18,9 @@
.image contributors-summit-2019/group.jpg _ 800
-_(Photo_by_Steve_Francia.)_
+_(Photo by Steve Francia.)_
-* Compiler and Runtime (report by Lynn Boger)
+## Compiler and Runtime (report by Lynn Boger)
The Go contributors summit was a great opportunity
to meet and discuss topics and ideas with others who also contribute to Go.
@@ -40,7 +41,7 @@
here is my list of those topics which had the most interest and discussion,
followed by some brief comments that were made on other topics.
-*Binary*size*.
+**Binary size**.
There was a concern expressed about binary size,
especially that it continues to grow with each release.
Some possible reasons were identified such as increased inlining and other optimizations.
@@ -54,7 +55,7 @@
those changes could be made, but if performance were affected
some users would prefer better performance.
-*Vector*assembly*.
+**Vector assembly**.
How to leverage vector assembly in Go was discussed for a while
and has been a topic of interest in the past.
I have split this into three separate possibilities, since they all relate to the use of vector instructions,
@@ -95,44 +96,44 @@
There was some discussion of designing an experimental vector package
to try and implement some of these ideas.
-*New*calling*convention*.
+**New calling convention**.
Several people were interested in the topic of the
-[[https://golang.org/issue/18597][ABI changes to provide a register based calling convention]].
+[ABI changes to provide a register based calling convention](https://golang.org/issue/18597).
The current status was reported with details.
There was discussion on what remained to be done before it could be used.
The ABI specification needs to be written first and it was not clear when that would be done.
I know this will benefit some target platforms more than others
and a register calling convention is used in most compilers for other platforms.
-*General*optimizations*.
+**General optimizations**.
Certain optimizations that are more beneficial for some platforms other than x86 were discussed.
In particular, loop optimizations such as hoisting of invariants and strength reduction could be done
and provide more benefit on some platforms.
Potential solutions were discussed, and implementation would probably be
up to the targets that find those improvements important.
-*Feedback-directed*optimizations*.
+**Feedback-directed optimizations**.
This was discussed and debated as a possible future enhancement.
In my experience, it is hard to find meaningful programs to use for
collecting performance data that can later be used to optimize code.
It increases compile time and takes a lot of space to save the data
which might only be meaningful for a small set of programs.
-*Pending*submissions*.
+**Pending submissions**.
A few members in the group mentioned changes they had been working on
and plan to submit soon, including improvements to makeslice, and a rewrite of rulegen.
-*Compile*time*concerns*.
+**Compile time concerns**.
Compile time was discussed briefly. It was noted that phase timing was added to the GOSSAFUNC output.
-*Compiler*contributor*communication*.
+**Compiler contributor communication**.
Someone asked if there was a need for a Go compiler mailing list.
It was suggested that we use golang-dev for that purpose,
adding compiler to the subject line to identify it.
If there is too much traffic on golang-dev, then a compiler-specific mailing list
can be considered at some later point in time.
-*Community*.
+**Community**.
I found the day very beneficial in terms of connecting with people
who have been active in the community and have similar areas of interest.
I was able to meet many people who I’ve only known by the user name
@@ -146,15 +147,15 @@
Hopefully these connections will lead to more effective communication
and improved handling of issues and code changes in the future.
-* Tools (report by Paul Jolly)
+## Tools (report by Paul Jolly)
The tools breakout session during the contributor summit took an extended form,
with two further sessions on the main conference days organized by the
-[[https://github.com/golang/go/wiki/golang-tools][golang-tools]] group.
+[golang-tools](https://github.com/golang/go/wiki/golang-tools) group.
This summary is broken down into two parts: the tools session at the contributor workshop,
and a combined report from the golang-tools sessions on the main conference days.
-*Contributor*summit*.
+**Contributor summit**.
The tools session started with introductions from ~25 folks gathered,
followed by a brainstorming of topics, including:
gopls, ARM 32-bit, eval, signal, analysis, go/packages api, refactoring, pprof,
@@ -163,8 +164,8 @@
A lot of people with lots of interest in lots of tools!
The session focused on two areas (all that time allowed): gopls and visualizations.
-[[https://golang.org/wiki/gopls][Gopls]] (pronounced: “go please”) is an implementation of the
-[[https://langserver.org][Language Server Protocol (LSP)]] server for Go.
+[Gopls](https://golang.org/wiki/gopls) (pronounced: “go please”) is an implementation of the
+[Language Server Protocol (LSP)](https://langserver.org) server for Go.
Rebecca Stamber, the gopls lead author, and the rest of the Go tools team were interested
in hearing people’s experiences with gopls: stability, missing features, integrations in editors working, etc?
The general feeling was that gopls was in really good shape and working extremely well for the majority of use cases.
@@ -177,19 +178,19 @@
Currently there is no good solution, but it’s actively under investigation.
Conversation shifted to the very broad topic of visualizations, with a
demo-based introduction from Anthony Starks (who, incidentally, gave an excellent talk about
-[[https://www.youtube.com/watch?v=NyDNJnioWhI][Go for information displays]] at GopherCon 2018).
+[Go for information displays](https://www.youtube.com/watch?v=NyDNJnioWhI) at GopherCon 2018).
-*Conference*days*.
+**Conference days**.
The golang-tools sessions on the main conference days were a continuation of the
-[[https://golang.org/wiki/golang-tools][monthly calls]] that have been happening since the group’s inception at GopherCon 2018.
+[monthly calls](https://golang.org/wiki/golang-tools) that have been happening since the group’s inception at GopherCon 2018.
Full notes are available for the
-[[https://docs.google.com/document/d/1-RVyttQ0ncjCpR_sRwizf-Ubedkr0Emwmk2LhnsUOmE/edit][day 1]] and
-[[https://docs.google.com/document/d/1ZI_WqpLCB8DO6teJ3aBuXTeYD2iZZZlkDptmcY6Ja60/edit#heading=h.x9lkytc2gxmg][day 2]] sessions.
+[day 1](https://docs.google.com/document/d/1-RVyttQ0ncjCpR_sRwizf-Ubedkr0Emwmk2LhnsUOmE/edit) and
+[day 2](https://docs.google.com/document/d/1ZI_WqpLCB8DO6teJ3aBuXTeYD2iZZZlkDptmcY6Ja60/edit#heading=h.x9lkytc2gxmg) sessions.
These sessions were again well attended with 25-30 people at each session.
The Go tools team was there in strength (a good sign of the support being put behind this area), as was the Uber platform team.
In contrast to the contributor summit, the goal from these sessions was to come away with specific action items.
-*Gopls*.
+**Gopls**.
Gopls “readiness” was a major focus for both sessions.
This answer effectively boiled down to determining when it makes sense to tell
editor integrators “we have a good first cut of gopls” and then compiling a
@@ -210,28 +211,28 @@
now the state of debugger-editor integration needs to be established,
following a process similar to that of gopls and the “blessed” integrations.
-*Go*Discovery*Site*.
+**Go Discovery Site**.
The second golang-tools session started with an excellent introduction to
the Go Discovery Site by Julie Qiu from the Go tools team, along with a quick demo.
Julie talked about the plans for the Discovery Site: open sourcing the project,
-what signals are used in search ranking, how [[http://godoc.org/][godoc.org]] will ultimately be replaced,
+what signals are used in search ranking, how [godoc.org](http://godoc.org/) will ultimately be replaced,
how submodules should work, how users can discover new major versions.
-*Build*Tags*.
+**Build Tags**.
Conversation then moved to build tag support within gopls.
This is an area that clearly needs to be better understood
-(use cases are currently being gathered in [[https://golang.org/issue/33389][issue 33389]]).
+(use cases are currently being gathered in [issue 33389](https://golang.org/issue/33389)).
In light of this conversation, the session wrapped up with
Alexander Zolotov from the JetBrains GoLand team suggesting that the gopls and
GoLand teams should share experience in this and more areas, given GoLand
has already gained lots of experience.
-*Join*Us!*
+**Join Us!**
We could easily have talked about tools-related topics for days!
The good news is that the golang-tools calls will continue for the foreseeable future.
-Anyone interested in Go tooling is very much encouraged to join: [[https://golang.org/wiki/golang-tools][the wiki]] has more details.
+Anyone interested in Go tooling is very much encouraged to join: [the wiki](https://golang.org/wiki/golang-tools) has more details.
-* Enterprise Use (report by Daniel Theophanes)
+## Enterprise Use (report by Daniel Theophanes)
Actively asking after the needs of less vocal developers will be the largest challenge,
and greatest win, for the Go language. There is a large segment of programmers
@@ -270,7 +271,7 @@
If you are in an organization where Go is only used for a subsection of programming tasks,
but not others, why isn’t it used for more? Are there specific blockers to adoption?
-* Education (report by Andy Walker)
+## Education (report by Andy Walker)
One of the roundtables I was involved in at the Contributors Summit
this year was on the topic of Go education,
@@ -284,21 +285,21 @@
Early on, talk turned to whether or not Go makes a good first programming language.
I wasn’t sure, and advocated against it.
Go isn’t a good first language, I argued, because it isn’t intended to be.
-As Rob Pike [[https://talks.golang.org/2012/splash.article][wrote back in 2012]],
+As Rob Pike [wrote back in 2012](https://talks.golang.org/2012/splash.article),
“the language was designed by and for people who write—and read and debug and maintain—large software systems”.
To me, this guiding ethos is clear: Go is a deliberate response to perceived flaws
in the processes used by experienced engineers, not an attempt to create an ideal
programming language, and as such a certain basic familiarity with programming concepts is assumed.
-This is evident in the official documentation at [[https://golang.org/doc/][golang.org/doc]].
+This is evident in the official documentation at [golang.org/doc](https://golang.org/doc/).
It jumps right into how to install the language before passing the user on to the
-[[https://tour.golang.org/][tour]], which is geared towards programmers
+[tour](https://tour.golang.org/), which is geared towards programmers
who are already familiar with a C-like language.
-From there, they are taken to [[https://golang.org/doc/code.html][How to Write Go Code]],
+From there, they are taken to [How to Write Go Code](https://golang.org/doc/code.html),
which provides a very basic introduction to the classic non-module Go workspace,
before moving immediately on to writing libraries and testing.
-Finally, we have [[https://golang.org/doc/effective_go.html][Effective Go]],
-and a series of references including the [[https://golang.org/ref/spec][spec]],
+Finally, we have [Effective Go](https://golang.org/doc/effective_go.html),
+and a series of references including the [spec](https://golang.org/ref/spec),
rounded out by some examples.
These are all decent resources if you’re already familiar with a C-like language,
but they still leave a lot to be desired, and there’s nothing to be found
@@ -322,12 +323,12 @@
design decisions principles of good architecture in Go.
They should find answers to questions like:
-- Why are there so many integer types when I am encouraged to use `int` most of the time?
-- Is there ever a good reason to pick a value receiver?
-- Why is there a plain `int`, but no plain `float`?
-- What are send- and receive-only channels, and when would I use them?
-- How do I effectively compose concurrency primitives, and when would I _not_ want to use channels?
-- What is `uint` good for? Should I use it to restrict my user to positive values? Why not?
+ - Why are there so many integer types when I am encouraged to use `int` most of the time?
+ - Is there ever a good reason to pick a value receiver?
+ - Why is there a plain `int`, but no plain `float`?
+ - What are send- and receive-only channels, and when would I use them?
+ - How do I effectively compose concurrency primitives, and when would I _not_ want to use channels?
+ - What is `uint` good for? Should I use it to restrict my user to positive values? Why not?
The tour should be someplace they can revisit upon finishing the first run-through
to dive more deeply into some of the more interesting choices in language design.
@@ -340,9 +341,9 @@
both a frontend and a backend environment,
but WASM is fast becoming a first-order platform,
and there are so many places we could go with that.
-We could provide something like [[https://github.com/gopherjs/vecty][vecty]]
-in [[https://goplay.space/][The Go Play Space]],
-or perhaps [[https://gioui.org/][Gio]], targeting WASM, for people to get
+We could provide something like [vecty](https://github.com/gopherjs/vecty)
+in [The Go Play Space](https://goplay.space/),
+or perhaps [Gio](https://gioui.org/), targeting WASM, for people to get
started programming in the browser right away, inspiring their imagination,
and provide them a migration path out of our playground into
a terminal and onto GitHub.
@@ -354,7 +355,7 @@
learning about their journey and their process,
and shaping the future of Go education with their input.
-* Learning Platforms (report by Ronna Steinberg)
+## Learning Platforms (report by Ronna Steinberg)
We discussed what a learning platform for Go should look like
and how we can combine global resources to effectively teach the language.
@@ -385,7 +386,7 @@
(If you are interested in helping in educational efforts for Go,
please email Carmen Andoh candoh@google.com.)
-* Thank You!
+## Thank You!
Thanks to all the attendees for the excellent discussions on contributor day,
and thanks especially to Lynn, Paul, Daniel, Andy, and Ronna
diff --git a/content/contributors-summit.article b/content/contributors-summit.article
index a213674..33d41ed 100644
--- a/content/contributors-summit.article
+++ b/content/contributors-summit.article
@@ -1,10 +1,11 @@
-Contributors Summit
+# Contributors Summit
3 Aug 2017
Tags: community
+Summary: The day before GopherCon, a group of Go team members and contributors gathered in Denver to discuss and plan for the future of the Go project. This was the first ever event of its kind, a major milestone for the Go project. The event comprised a morning session revolving around focused discussions on a theme, and an afternoon session made up of round table discussions in small break-out groups.
Sam Whited
-* Introduction
+## Introduction
The day before GopherCon, a group of Go team members and contributors gathered
in Denver to discuss and plan for the future of the Go project.
@@ -13,7 +14,7 @@
theme, and an afternoon session made up of round table discussions in small
break-out groups.
-** Compiler and runtime
+### Compiler and runtime
The compiler and runtime session started out with a discussion about refactoring
`gc` and related tools into importable packages.
@@ -42,9 +43,9 @@
I learned a lot about the current state of the world, the problems, and where
people want to go from here.
-** Dependency management
+### Dependency management
-After a quick update from the [[https://github.com/golang/dep][dep]] team on the
+After a quick update from the [dep](https://github.com/golang/dep) team on the
status of the project, the dependency management session gravitated towards how
the Go world will work once dep (or something dep-like) becomes the primary
means of package management.
@@ -64,10 +65,10 @@
There are many good options for making the Go tooling easier to use, and
discussion will likely continue on the mailing lists.
-** The standard library
+### The standard library
The discussions we had around the future of the Go language are mostly covered
-in Russ Cox's blog post: [[https://blog.golang.org//toward-go2][Toward Go 2]], so
+in Russ Cox's blog post: [Toward Go 2](https://blog.golang.org//toward-go2), so
let's move on to the standard library session.
As a contributor to the standard library and subrepos, this session was
@@ -88,15 +89,15 @@
For instance, it would be nice if `io.Reader` accepted a context so that
blocking read operations could be canceled.
-More [[https://golang.org/wiki/experiencereports][experience reports]] are
+More [experience reports](https://golang.org/wiki/experiencereports) are
necessary before we can determine what will change in the standard library.
-** Tooling and editors
+### Tooling and editors
A language server for editors to use was a hot topic in the tooling session,
with a number of people advocating for IDE and tool developers to adopt a common
"Go Language Server" to index and display information about code and packages.
-Microsoft's [[https://www.github.com/Microsoft/language-server-protocol][Language Server Protocol]]
+Microsoft's [Language Server Protocol](https://www.github.com/Microsoft/language-server-protocol)
was suggested as a good starting point because of its wide support in editors
and IDEs.
@@ -107,7 +108,7 @@
experience reports from the community will be required before such an API can be
designed.
-** The contributor experience
+### The contributor experience
The final session of the day was on the contributor experience.
The first discussion was all about how the current Gerrit workflow could be made
@@ -121,7 +122,7 @@
Hopefully we'll see improvements to these and many more areas of the
contribution process in the coming weeks and months!
-** Breakout sessions
+### Breakout sessions
In the afternoon, participants broke out into smaller groups to have more
in-depth discussions about some of the topics from the morning session.
@@ -129,7 +130,7 @@
For example, one group worked on identifying the useful parts of an experience
report and a list of existing literature documenting Go user experiences,
resulting in the experience report
-[[https://golang.org/wiki/experiencereports][wiki page]].
+[wiki page](https://golang.org/wiki/experiencereports).
Another group considered the future of errors in Go.
Many Go users are initially confused by, or don't understand the fact that
@@ -139,7 +140,7 @@
these issues in upcoming Go releases, but also ways error handling could be
improved in Go 2.
-* Community
+## Community
Outside of the technical discussions, the summit also provided an opportunity
for a group of people from all over the world who often talk and work together
@@ -151,7 +152,7 @@
for discussions both about Go and a little general socialization, which really
helped to put faces to the names that review our code every day.
-As Russ discussed in [[https://blog.golang.org//toward-go2][Toward Go 2]],
+As Russ discussed in [Toward Go 2](https://blog.golang.org//toward-go2),
communicating effectively requires knowing your audience.
Having a broad sample of Go contributors in a room together helped us all to
understand the Go audience better and start many productive discussions about
diff --git a/content/cover.article b/content/cover.article
index 40ed1d9..e4ac0bf 100644
--- a/content/cover.article
+++ b/content/cover.article
@@ -1,21 +1,22 @@
-The cover story
+# The cover story
2 Dec 2013
Tags: tools, coverage, testing
+Summary: From the beginning of the project, Go was designed with tools in mind. Those tools include some of the most iconic pieces of Go technology such as the documentation presentation tool [godoc](https://golang.org/cmd/godoc), the code formatting tool [gofmt](https://golang.org/cmd/gofmt), and the API rewriter [gofix](https://golang.org/cmd/fix). Perhaps most important of all is the [`go` command](https://golang.org/cmd/go), the program that automatically installs, builds, and tests Go programs using nothing more than the source code as the build specification.
Rob Pike
-* Introduction
+## Introduction
From the beginning of the project, Go was designed with tools in mind.
Those tools include some of the most iconic pieces of Go technology such as
the documentation presentation tool
-[[https://golang.org/cmd/godoc][godoc]],
+[godoc](https://golang.org/cmd/godoc),
the code formatting tool
-[[https://golang.org/cmd/gofmt][gofmt]],
+[gofmt](https://golang.org/cmd/gofmt),
and the API rewriter
-[[https://golang.org/cmd/fix][gofix]].
+[gofix](https://golang.org/cmd/fix).
Perhaps most important of all is the
-[[https://golang.org/cmd/go][`go` command]],
+[`go` command](https://golang.org/cmd/go),
the program that automatically installs, builds, and tests Go programs
using nothing more than the source code as the build specification.
@@ -23,10 +24,10 @@
unusual approach to the way it generates coverage statistics, an approach
that builds on the technology laid down by godoc and friends.
-* Support for tools
+## Support for tools
First, some background: What does it mean for a
-[[https://talks.golang.org/2012/splash.article#TOC_17.][language to support good tooling]]?
+[language to support good tooling](https://talks.golang.org/2012/splash.article#TOC_17.)?
It means that the language makes it easy to write good tools and that its ecosystem
supports the construction of tools of all flavors.
@@ -50,7 +51,7 @@
One example is the gofix tool, which automates the
rewriting of code to use new language features or updated libraries.
Gofix let us make fundamental changes to the language and libraries in the
-[[https://blog.golang.org/the-path-to-go-1][run-up to Go 1.0]],
+[run-up to Go 1.0](https://blog.golang.org/the-path-to-go-1),
with the confidence that users could just run the tool to update their source to the newest version.
Inside Google, we have used gofix to make sweeping changes in a huge code repository that would be almost
@@ -63,7 +64,7 @@
All these items build on each other, making the Go environment
more productive by automating many tasks.
-* Test coverage
+## Test coverage
Test coverage is a term that describes how much of a package's code is exercised by running the package's tests.
If executing the test suite causes 80% of the package's source statements to be run, we say that the test coverage is 80%.
@@ -71,7 +72,7 @@
The program that provides test coverage in Go 1.2 is the latest to exploit the tooling support in the Go ecosystem.
The usual way to compute test coverage is to instrument the binary.
-For instance, the GNU [[http://gcc.gnu.org/onlinedocs/gcc/Gcov.html][gcov]] program sets breakpoints at branches
+For instance, the GNU [gcov](http://gcc.gnu.org/onlinedocs/gcc/Gcov.html) program sets breakpoints at branches
executed by the binary.
As each branch executes, the breakpoint is cleared and the target statements of the branch are marked as 'covered'.
@@ -90,7 +91,7 @@
information.
However If you're a user of gc, the more commonly used Go compiler suite, until Go 1.2 you were out of luck.
-* Test coverage for Go
+## Test coverage for Go
For the new test coverage tool for Go, we took a different approach that avoids dynamic debugging.
The idea is simple: Rewrite the package's source code before compilation to add instrumentation,
@@ -135,7 +136,7 @@
Its run-time overhead is therefore modest, adding only about 3% when running a typical (more realistic) test.
That makes it reasonable to include test coverage as part of the standard development pipeline.
-* Viewing the results
+## Viewing the results
The test coverage for our example was poor.
To discover why, we ask `go` `test` to write a "coverage profile" for us, a file that holds
@@ -177,7 +178,7 @@
And we can see exactly which ones they are, which makes it easy to
improve our test coverage.
-* Heat maps
+## Heat maps
A big advantage of this source-level approach to test coverage is that it's
easy to instrument the code in different ways.
@@ -187,14 +188,14 @@
The `go` `test` command accepts a `-covermode` flag to set the coverage mode
to one of three settings:
-- set: did each statement run?
-- count: how many times did each statement run?
-- atomic: like count, but counts precisely in parallel programs
+ - set: did each statement run?
+ - count: how many times did each statement run?
+ - atomic: like count, but counts precisely in parallel programs
The default is 'set', which we've already seen.
The `atomic` setting is needed only when accurate counts are required
when running parallel algorithms. It uses atomic operations from the
-[[https://golang.org/pkg/sync/atomic/][sync/atomic]] package,
+[sync/atomic](https://golang.org/pkg/sync/atomic/) package,
which can be quite expensive.
For most purposes, though, the `count` mode works fine and, like
the default `set` mode, is very cheap.
@@ -256,7 +257,7 @@
That's a lot of information about the execution of the function,
information that might be useful in profiling.
-* Basic blocks
+## Basic blocks
You might have noticed that the counts in the previous example
were not what you expected on the lines with closing braces.
@@ -287,7 +288,7 @@
instrumentation right but the presentation is line-based and
can therefore miss some nuances.
-* The big picture
+## The big picture
That's the story about test coverage in Go 1.2.
A new tool with an interesting implementation enables not only
diff --git a/content/debugging-go-code-status-report.article b/content/debugging-go-code-status-report.article
index 9da89e1..e253a10 100644
--- a/content/debugging-go-code-status-report.article
+++ b/content/debugging-go-code-status-report.article
@@ -1,10 +1,11 @@
-Debugging Go code (a status report)
+# Debugging Go code (a status report)
2 Nov 2010
Tags: debug, gdb
+Summary: When it comes to debugging, nothing beats a few strategic print statements to inspect variables or a well-placed panic to obtain a stack trace. However, sometimes you’re missing either the patience or the source code, and in those cases a good debugger can be invaluable. That's why over the past few releases we have been improving the support in Go’s gc linker (6l, 8l) for GDB, the GNU debugger.
Luuk van Dijk
-* Introduction
+##
When it comes to debugging, nothing beats a few strategic print statements
to inspect variables or a well-placed panic to obtain a stack trace.
@@ -19,42 +20,42 @@
FreeBSD) or Mach-O (Mac OS X) binaries.
The DWARF code is rich enough to let you do the following:
-- load a Go program in GDB version 7.x,
-- list all Go, C, and assembly source files by line (parts of the Go runtime are written in C and assembly),
-- set breakpoints by line and step through the code,
-- print stack traces and inspect stack frames, and
-- find the addresses and print the contents of most variables.
+ - load a Go program in GDB version 7.x,
+ - list all Go, C, and assembly source files by line (parts of the Go runtime are written in C and assembly),
+ - set breakpoints by line and step through the code,
+ - print stack traces and inspect stack frames, and
+ - find the addresses and print the contents of most variables.
There are still some inconveniences:
-- The emitted DWARF code is unreadable by the GDB version 6.x that ships with Mac OS X.
- We would gladly accept patches to make the DWARF output compatible with
- the standard OS X GDB,
- but until that’s fixed you’ll need to download,
- build, and install GDB 7.x to use it under OS X.
- The source can be found at [[http://sourceware.org/gdb/download/][http://sourceware.org/gdb/download/]].
- Due to the particulars of OS X you’ll need to install the binary on a
- local file system with `chgrp`procmod` and `chmod`g+s`.
-- Names are qualified with a package name and,
- as GDB doesn't understand Go packages, you must reference each item by its full name.
- For example, the variable named `v` in package `main` must be referred to
- as `'main.v'`, in single quotes.
- A consequence of this is that tab completion of variable and function names does not work.
-- Lexical scoping information is somewhat obfuscated.
- If there are multiple variables of the same name,
- the nth instance will have a suffix of the form ‘#n’.
- We plan to fix this, but it will require some changes to the data exchanged
- between the compiler and linker.
-- Slice and string variables are represented as their underlying structure
- in the runtime library.
- They will look something like `{data`=`0x2aaaaab3e320,`len`=`1,`cap`=`1}.` For slices,
- you must dereference the data pointer to inspect the elements.
+ - The emitted DWARF code is unreadable by the GDB version 6.x that ships with Mac OS X.
+ We would gladly accept patches to make the DWARF output compatible with
+ the standard OS X GDB,
+ but until that’s fixed you’ll need to download,
+ build, and install GDB 7.x to use it under OS X.
+ The source can be found at [http://sourceware.org/gdb/download/](http://sourceware.org/gdb/download/).
+ Due to the particulars of OS X you’ll need to install the binary on a
+ local file system with `chgrp procmod` and `chmod g+s`.
+ - Names are qualified with a package name and,
+ as GDB doesn't understand Go packages, you must reference each item by its full name.
+ For example, the variable named `v` in package `main` must be referred to
+ as `'main.v'`, in single quotes.
+ A consequence of this is that tab completion of variable and function names does not work.
+ - Lexical scoping information is somewhat obfuscated.
+ If there are multiple variables of the same name,
+ the nth instance will have a suffix of the form ‘#n’.
+ We plan to fix this, but it will require some changes to the data exchanged
+ between the compiler and linker.
+ - Slice and string variables are represented as their underlying structure
+ in the runtime library.
+ They will look something like `{data = 0x2aaaaab3e320, len = 1, cap = 1}.` For slices,
+ you must dereference the data pointer to inspect the elements.
Some things don't work yet:
-- Channel, function, interface, and map variables cannot be inspected.
-- Only Go variables are annotated with type information; the runtime's C variables are not.
-- Windows and ARM binaries do not contain DWARF debugging information and, as such, cannot be inspected with GDB.
+ - Channel, function, interface, and map variables cannot be inspected.
+ - Only Go variables are annotated with type information; the runtime's C variables are not.
+ - Windows and ARM binaries do not contain DWARF debugging information and, as such, cannot be inspected with GDB.
Over the coming months we intend to address these issues,
either by changing the compiler and linker or by using the Python extensions to GDB.
diff --git a/content/debugging-go-programs-with-gnu-debugger.article b/content/debugging-go-programs-with-gnu-debugger.article
index 2df3997..e5308cb 100644
--- a/content/debugging-go-programs-with-gnu-debugger.article
+++ b/content/debugging-go-programs-with-gnu-debugger.article
@@ -1,13 +1,14 @@
-Debugging Go programs with the GNU Debugger
+# Debugging Go programs with the GNU Debugger
30 Oct 2011
Tags: debug, gdb, technical
+Summary: Last year we [reported](https://blog.golang.org/2010/11/debugging-go-code-status-report.html) that Go's [gc](https://golang.org/cmd/gc/)/[ld](https://golang.org/cmd/6l/) toolchain produces DWARFv3 debugging information that can be read by the GNU Debugger (GDB). Since then, work has continued steadily on improving support for debugging Go code with GDB. Among the improvements are the ability to inspect goroutines and to print native Go data types, including structs, slices, strings, maps, interfaces, and channels.
Andrew Gerrand
-* Introduction
+##
-Last year we [[https://blog.golang.org/2010/11/debugging-go-code-status-report.html][reported]]
-that Go's [[https://golang.org/cmd/gc/][gc]]/[[https://golang.org/cmd/6l/][ld]]
+Last year we [reported](https://blog.golang.org/2010/11/debugging-go-code-status-report.html)
+that Go's [gc](https://golang.org/cmd/gc/)/[ld](https://golang.org/cmd/6l/)
toolchain produces DWARFv3 debugging information that can be read by the GNU Debugger (GDB).
Since then, work has continued steadily on improving support for debugging Go code with GDB.
Among the improvements are the ability to inspect goroutines and to print
@@ -15,4 +16,4 @@
including structs, slices, strings, maps,
interfaces, and channels.
-To learn more about Go and GDB, see the [[https://golang.org/doc/debugging_with_gdb.html][Debugging with GDB]] article.
+To learn more about Go and GDB, see the [Debugging with GDB](https://golang.org/doc/debugging_with_gdb.html) article.
diff --git a/content/debugging-what-you-deploy.article b/content/debugging-what-you-deploy.article
index 4685715..79543a7 100644
--- a/content/debugging-what-you-deploy.article
+++ b/content/debugging-what-you-deploy.article
@@ -1,10 +1,11 @@
-Debugging what you deploy in Go 1.12
+# Debugging what you deploy in Go 1.12
21 Mar 2019
Tags: debug, technical
+Summary: Go 1.11 and Go 1.12 make significant progress toward allowing developers to debug the same optimized binaries that they deploy to production.
David Chase
-* Introduction
+## Introduction
Go 1.11 and Go 1.12 make significant progress toward allowing developers
to debug the same optimized binaries that they deploy to production.
@@ -23,32 +24,32 @@
optimized binaries (the default setting of the Go compiler).
Improvements include
-- More accurate value inspection, in particular for arguments at function entry;
-- More precisely identifying statement boundaries so that stepping is less
- jumpy and breakpoints more often land where the programmer expects;
-- And preliminary support for Delve to call Go functions (goroutines and
- garbage collection make this trickier than it is in C and C++).
+ - More accurate value inspection, in particular for arguments at function entry;
+ - More precisely identifying statement boundaries so that stepping is less
+ jumpy and breakpoints more often land where the programmer expects;
+ - And preliminary support for Delve to call Go functions (goroutines and
+ garbage collection make this trickier than it is in C and C++).
-* Debugging optimized code with Delve
+## Debugging optimized code with Delve
-[[https://github.com/go-delve/delve][Delve]] is a debugger for Go on x86
+[Delve](https://github.com/go-delve/delve) is a debugger for Go on x86
supporting both Linux and macOS.
Delve is aware of goroutines and other Go features and provides one of the
best Go debugging experiences.
-Delve is also the debugging engine behind [[https://www.jetbrains.com/go/][GoLand]],
-[[https://code.visualstudio.com/][VS Code]],
-and [[https://github.com/fatih/vim-go][Vim]].
+Delve is also the debugging engine behind [GoLand](https://www.jetbrains.com/go/),
+[VS Code](https://code.visualstudio.com/),
+and [Vim](https://github.com/fatih/vim-go).
-Delve normally rebuilds the code it is debugging with `-gcflags`"all=-N`-l"`,
+Delve normally rebuilds the code it is debugging with `-gcflags "all=-N -l"`,
which disables inlining and most optimizations.
To debug optimized code with delve, first build the optimized binary,
-then use `dlv`exec`your_program` to debug it.
+then use `dlv exec your_program` to debug it.
Or, if you have a core file from a crash,
-you can examine it with `dlv`core`your_program`your_core`.
+you can examine it with `dlv core your_program your_core`.
With 1.12 and the latest Delve releases, you should be able to examine many variables,
even in optimized binaries.
-* Improved value inspection
+## Improved value inspection
When debugging optimized binaries produced by Go 1.10,
variable values were usually completely unavailable.
@@ -59,7 +60,7 @@
can track variables as they move in and out of registers and reconstruct
complex objects that are split across different registers and stack slots.
-* Improved stepping
+## Improved stepping
This shows an example of stepping through a simple function in a debugger in 1.10,
with flaws (skipped and repeated lines) highlighted by red arrows.
@@ -74,7 +75,7 @@
As a result, in Go 1.12, stepping through this code stops on every line
and does so in the order you would expect.
-* Function calls
+## Function calls
Function call support in Delve is still under development, but simple cases work. For example:
@@ -83,7 +84,7 @@
Values returned:
~r1: 8
-* The path forward
+## The path forward
Go 1.12 is a step toward a better debugging experience for optimized binaries
and we have plans to improve it even further.
@@ -102,13 +103,13 @@
the order of stepping around loops, and generally trying to follow source
order where possible.
-* A note on macOS support
+## A note on macOS support
Go 1.11 started compressing debug information to reduce binary sizes.
This is natively supported by Delve, but neither LLDB nor GDB support compressed
debug info on macOS.
If you are using LLDB or GDB, there are two workarounds:
build binaries with `-ldflags=-compressdwarf=false`,
-or use [[https://godoc.org/golang.org/x/tools/cmd/splitdwarf][splitdwarf]]
-(`go`get`golang.org/x/tools/cmd/splitdwarf`) to decompress the debug information
+or use [splitdwarf](https://godoc.org/golang.org/x/tools/cmd/splitdwarf)
+(`go get golang.org/x/tools/cmd/splitdwarf`) to decompress the debug information
in an existing binary.
diff --git a/content/defer-panic-and-recover.article b/content/defer-panic-and-recover.article
index 2c95aa3..e3773ba 100644
--- a/content/defer-panic-and-recover.article
+++ b/content/defer-panic-and-recover.article
@@ -1,10 +1,11 @@
-Defer, Panic, and Recover
+# Defer, Panic, and Recover
4 Aug 2010
Tags: defer, panic, recover, technical, function
+Summary: Go has the usual mechanisms for control flow: if, for, switch, goto. It also has the go statement to run code in a separate goroutine. Here I'd like to discuss some of the less common ones: defer, panic, and recover.
Andrew Gerrand
-* Introduction
+##
Go has the usual mechanisms for control flow:
if, for, switch, goto.
@@ -12,7 +13,7 @@
Here I'd like to discuss some of the less common ones:
defer, panic, and recover.
-A *defer*statement* pushes a function call onto a list.
+A **defer statement** pushes a function call onto a list.
The list of saved calls is executed after the surrounding function returns.
Defer is commonly used to simplify functions that perform various clean-up actions.
@@ -64,7 +65,7 @@
The behavior of defer statements is straightforward and predictable. There are three simple rules:
-1. _A_deferred_function's_arguments_are_evaluated_when_the_defer_statement_is_evaluated._
+1. _A deferred function's arguments are evaluated when the defer statement is evaluated._
In this example, the expression "i" is evaluated when the Println call is deferred.
The deferred call will print "0" after the function returns.
@@ -76,7 +77,7 @@
return
}
-2. _Deferred_function_calls_are_executed_in_Last_In_First_Out_order_after_the_surrounding_function_returns._
+2. _Deferred function calls are executed in Last In First Out order after the surrounding function returns._
This function prints "3210":
@@ -86,7 +87,7 @@
}
}
-3. _Deferred_functions_may_read_and_assign_to_the_returning_function's_named_return_values._
+3. _Deferred functions may read and assign to the returning function's named return values._
In this example, a deferred function increments the return value i _after_
the surrounding function returns.
@@ -99,7 +100,7 @@
This is convenient for modifying the error return value of a function; we will see an example of this shortly.
-*Panic* is a built-in function that stops the ordinary flow of control and begins _panicking_.
+**Panic** is a built-in function that stops the ordinary flow of control and begins _panicking_.
When the function F calls panic, execution of F stops,
any deferred functions in F are executed normally,
and then F returns to its caller.
@@ -110,7 +111,7 @@
They can also be caused by runtime errors,
such as out-of-bounds array accesses.
-*Recover* is a built-in function that regains control of a panicking goroutine.
+**Recover** is a built-in function that regains control of a panicking goroutine.
Recover is only useful inside deferred functions.
During normal execution, a call to recover will return nil and have no other effect.
If the current goroutine is panicking, a call to recover will capture the
@@ -189,19 +190,19 @@
panic PC=0x2a9cd8
[stack trace omitted]
-For a real-world example of *panic* and *recover*,
-see the [[https://golang.org/pkg/encoding/json/][json package]] from the
+For a real-world example of **panic** and **recover**,
+see the [json package](https://golang.org/pkg/encoding/json/) from the
Go standard library.
It encodes an interface with a set of recursive functions.
If an error occurs when traversing the value,
panic is called to unwind the stack to the top-level function call,
which recovers from the panic and returns an appropriate error value (see
-the 'error' and 'marshal' methods of the encodeState type in [[https://golang.org/src/pkg/encoding/json/encode.go][encode.go]]).
+the 'error' and 'marshal' methods of the encodeState type in [encode.go](https://golang.org/src/pkg/encoding/json/encode.go)).
The convention in the Go libraries is that even when a package uses panic internally,
its external API still presents explicit error return values.
-Other uses of *defer* (beyond the file.Close example given earlier) include releasing a mutex:
+Other uses of **defer** (beyond the file.Close example given earlier) include releasing a mutex:
mu.Lock()
defer mu.Unlock()
diff --git a/content/developer-experience.article b/content/developer-experience.article
index 4122127..16889bf 100644
--- a/content/developer-experience.article
+++ b/content/developer-experience.article
@@ -1,9 +1,10 @@
-Introducing the Developer Experience Working Group
+# Introducing the Developer Experience Working Group
10 Apr 2017
+Summary: Over the last several years, Go's audience has shifted from early adopters to mainstream users. Today, our users come from a wide variety of backgrounds, experiences, and expectations. The needs of users are growing faster than the Go project can currently address them. To streamline the experience for first-time Go users, we've created the Developer eXperience Working Group (DXWG).
The Developer Experience Working Group
-* Introducing the Developer Experience Working Group
+##
Over the last several years, Go's audience has shifted from early
adopters to mainstream users. Today, our users come from a wide
@@ -14,11 +15,11 @@
For the next three months, this group will work together on delivering:
-- improvements to the Go installation experience
-- better guidelines to help new users
-- guides on tooling and developer environments (editors and IDEs)
-- running user studies to systematically analyze and measure friction points
-- improvements to the [[https://tour.golang.org/][Go Tour]] and [[https://play.golang.org/][Go Playground]]
+ - improvements to the Go installation experience
+ - better guidelines to help new users
+ - guides on tooling and developer environments (editors and IDEs)
+ - running user studies to systematically analyze and measure friction points
+ - improvements to the [Go Tour](https://tour.golang.org/) and [Go Playground](https://play.golang.org/)
A secondary goal of the working group is to better understand how to
involve the Go community in charting Go’s future. We hope that working
@@ -35,5 +36,5 @@
code, writing documentation, sharing feedback and experiences
(user stories), reviewing contributions, and more. If you are
interested in any of our current areas of focus, please subscribe to the
-[[https://groups.google.com/forum/#!forum/golang-devexp][golang-devexp]]
+[golang-devexp](https://groups.google.com/forum/#!forum/golang-devexp)
mailing list.
diff --git a/content/docker.article b/content/docker.article
index 2ec5cc3..397431b 100644
--- a/content/docker.article
+++ b/content/docker.article
@@ -1,36 +1,37 @@
-Deploying Go servers with Docker
+# Deploying Go servers with Docker
26 Sep 2014
+Summary: This week Docker [announced](https://blog.docker.com/2014/09/docker-hub-official-repos-announcing-language-stacks/) official base images for Go and other major languages, giving programmers a trusted and easy way to build containers for their Go programs.
Andrew Gerrand
-* Introduction
+## Introduction
-This week Docker [[https://blog.docker.com/2014/09/docker-hub-official-repos-announcing-language-stacks/][announced]]
+This week Docker [announced](https://blog.docker.com/2014/09/docker-hub-official-repos-announcing-language-stacks/)
official base images for Go and other major languages,
giving programmers a trusted and easy way to build containers for their Go programs.
In this article we'll walk through a recipe for creating a Docker container for
a simple Go web application and deploying that container to Google Compute Engine.
If you're not familiar with Docker, you should read
-[[https://docs.docker.com/engine/understanding-docker/][Understanding Docker]]
+[Understanding Docker](https://docs.docker.com/engine/understanding-docker/)
before reading on.
-* The demo app
+## The demo app
For our demonstration we will use the
-[[https://godoc.org/github.com/golang/example/outyet][outyet]] program from the
-[[https://github.com/golang/example][Go examples repository]],
+[outyet](https://godoc.org/github.com/golang/example/outyet) program from the
+[Go examples repository](https://github.com/golang/example),
a simple web server that reports whether the next version of Go has been released
-(designed to power sites like [[http://isgo1point4.outyet.org/][isgo1point4.outyet.org]]).
+(designed to power sites like [isgo1point4.outyet.org](http://isgo1point4.outyet.org/)).
It has no dependencies outside the standard library and requires no additional
data files at run time; for a web server, it's about as simple as it gets.
Use "go get" to fetch and install outyet in your
-[[https://golang.org/doc/code.html#Workspaces][workspace]]:
+[workspace](https://golang.org/doc/code.html#Workspaces):
$ go get github.com/golang/example/outyet
-* Write a Dockerfile
+## Write a Dockerfile
Replace a file named `Dockerfile` in the `outyet` directory with the following contents:
@@ -54,12 +55,12 @@
This `Dockerfile` specifies how to construct a container that runs `outyet`,
starting with the basic dependencies (a Debian system with Go installed;
-the [[https://registry.hub.docker.com/_/golang/][official `golang` docker image]]),
+the [official `golang` docker image](https://registry.hub.docker.com/_/golang/)),
adding the `outyet` package source, building it, and then finally running it.
The `ADD`, `RUN`, and `ENTRYPOINT` steps are common tasks for any Go project.
To simplify this, there is an
-[[https://github.com/docker-library/golang/blob/9ff2ccca569f9525b023080540f1bb55f6b59d7f/1.3.1/onbuild/Dockerfile][`onbuild` variant]]
+[`onbuild` variant](https://github.com/docker-library/golang/blob/9ff2ccca569f9525b023080540f1bb55f6b59d7f/1.3.1/onbuild/Dockerfile)
of the `golang` image that automatically copies the package source, fetches the
application dependencies, builds the program, and configures it to run on
startup.
@@ -69,7 +70,7 @@
FROM golang:onbuild
EXPOSE 8080
-* Build and run the image
+## Build and run the image
Invoke Docker from the `outyet` package directory to build an image using the `Dockerfile`:
@@ -96,31 +97,31 @@
(If your docker daemon is running on another machine (or in a virtual machine),
you should replace `localhost` with the address of that machine. If you're
-using [[http://boot2docker.io/][boot2docker]] on OS X or Windows you can find
-that address with `boot2docker`ip`.)
+using [boot2docker](http://boot2docker.io/) on OS X or Windows you can find
+that address with `boot2docker ip`.)
Now that we've verified that the image works, shut down the running container
from another terminal window:
$ docker stop test
-* Create a repository on Docker Hub
+## Create a repository on Docker Hub
-[[https://hub.docker.com/][Docker Hub]], the container registry from which we
+[Docker Hub](https://hub.docker.com/), the container registry from which we
pulled the `golang` image earlier, offers a feature called
-[[http://docs.docker.com/docker-hub/builds/][Automated Builds]] that builds
+[Automated Builds](http://docs.docker.com/docker-hub/builds/) that builds
images from a GitHub or BitBucket repository.
-By committing [[https://github.com/golang/example/blob/master/outyet/Dockerfile][the Dockerfile]]
+By committing [the Dockerfile](https://github.com/golang/example/blob/master/outyet/Dockerfile)
to the repository and creating an
-[[https://registry.hub.docker.com/u/adg1/outyet/][automated build]]
+[automated build](https://registry.hub.docker.com/u/adg1/outyet/)
for it, anyone with Docker installed can download and run our image with a
single command. (We will see the utility of this in the next section.)
To set up an Automated Build, commit the Dockerfile to your repo on
-[[https://github.com/][GitHub]] or [[https://bitbucket.org/][BitBucket]],
+[GitHub](https://github.com/) or [BitBucket](https://bitbucket.org/),
create an account on Docker Hub, and follow the instructions for
-[[http://docs.docker.com/docker-hub/builds/][creating an Automated Build]].
+[creating an Automated Build](http://docs.docker.com/docker-hub/builds/).
When you're done, you can run your container using the name of the automated build:
@@ -128,15 +129,15 @@
(Replace `goexample/outyet` with the name of the automated build you created.)
-* Deploy the container to Google Compute Engine
+## Deploy the container to Google Compute Engine
Google provides
-[[https://developers.google.com/compute/docs/containers/container_vms][container-optimized Google Compute Engine images]]
+[container-optimized Google Compute Engine images](https://developers.google.com/compute/docs/containers/container_vms)
that make it easy to spin up a virtual machine running an arbitrary Docker container.
On startup, a program running on the instance reads a configuration file that
specifies which container to run, fetches the container image, and runs it.
-Create a [[https://cloud.google.com/compute/docs/containers/container_vms#container_manifest][containers.yaml]]
+Create a [containers.yaml](https://cloud.google.com/compute/docs/containers/container_vms#container_manifest)
file that specifies the docker image to run and the ports to expose:
version: v1beta2
@@ -152,7 +153,7 @@
the default port for serving HTTP traffic. And, again, you should replace
`goexample/outyet` with the name of your Automated Build.)
-Use the [[https://cloud.google.com/sdk/#Quick_Start][gcloud tool]]
+Use the [gcloud tool](https://cloud.google.com/sdk/#Quick_Start)
to create a VM instance running the container:
$ gcloud compute instances create outyet \
@@ -176,7 +177,7 @@
The `--zone` and `--machine-type` flags specify the zone in which to run the VM
and the type of machine to run. (To see a list of machine types and the zones,
-run `gcloud`compute`machine-types`list`.)
+run `gcloud compute machine-types list`.)
Once this has completed, the gcloud command should print some information about
the instance. In the output, locate the `networkInterfaces` section to find the
@@ -185,17 +186,17 @@
yet?" page.
(To see what's happening on the new VM instance you can ssh into it with
-`gcloud`compute`ssh`outyet`. From there, try `sudo`docker`ps` to see which
+`gcloud compute ssh outyet`. From there, try `sudo docker ps` to see which
Docker containers are running.)
-* Learn more
+## Learn more
This is just the tip of the iceberg—there's a lot more you can do with Go, Docker, and Google Compute Engine.
-To learn more about Docker, see their [[https://docs.docker.com/][extensive documentation]].
+To learn more about Docker, see their [extensive documentation](https://docs.docker.com/).
-To learn more about Docker and Go, see the [[https://registry.hub.docker.com/_/golang/][official `golang` Docker Hub repository]] and Kelsey Hightower's [[https://medium.com/@kelseyhightower/optimizing-docker-images-for-static-binaries-b5696e26eb07][Optimizing Docker Images for Static Go Binaries]].
+To learn more about Docker and Go, see the [official `golang` Docker Hub repository](https://registry.hub.docker.com/_/golang/) and Kelsey Hightower's [Optimizing Docker Images for Static Go Binaries](https://medium.com/@kelseyhightower/optimizing-docker-images-for-static-binaries-b5696e26eb07).
-To learn more about Docker and [[http://cloud.google.com/compute][Google Compute Engine]],
-see the [[https://cloud.google.com/compute/docs/containers/container_vms][Container-optimized VMs page]]
-and the [[https://registry.hub.docker.com/u/google/docker-registry/][google/docker-registry Docker Hub repository]].
+To learn more about Docker and [Google Compute Engine](http://cloud.google.com/compute),
+see the [Container-optimized VMs page](https://cloud.google.com/compute/docs/containers/container_vms)
+and the [google/docker-registry Docker Hub repository](https://registry.hub.docker.com/u/google/docker-registry/).
diff --git a/content/error-handling-and-go.article b/content/error-handling-and-go.article
index 07d84d5..709b016 100644
--- a/content/error-handling-and-go.article
+++ b/content/error-handling-and-go.article
@@ -1,10 +1,11 @@
-Error handling and Go
+# Error handling and Go
12 Jul 2011
Tags: error, interface, type, technical
+Summary: If you have written any Go code you have probably encountered the built-in `error` type. Go code uses `error` values to indicate an abnormal state. For example, the `os.Open` function returns a non-nil `error` value when it fails to open a file.
Andrew Gerrand
-* Introduction
+## Introduction
If you have written any Go code you have probably encountered the built-in `error` type.
Go code uses `error` values to indicate an abnormal state.
@@ -16,17 +17,17 @@
The following code uses `os.Open` to open a file.
If an error occurs it calls `log.Fatal` to print the error message and stop.
- f, err := os.Open("filename.ext")
- if err != nil {
- log.Fatal(err)
- }
- // do something with the open *File f
+ f, err := os.Open("filename.ext")
+ if err != nil {
+ log.Fatal(err)
+ }
+ // do something with the open *File f
You can get a lot done in Go knowing just this about the `error` type,
but in this article we'll take a closer look at `error` and discuss some
good practices for error handling in Go.
-* The error type
+## The error type
The `error` type is an interface type. An `error` variable represents any
value that can describe itself as a string.
@@ -37,10 +38,10 @@
}
The `error` type, as with all built in types,
-is [[https://golang.org/doc/go_spec.html#Predeclared_identifiers][predeclared]]
-in the [[https://golang.org/doc/go_spec.html#Blocks][universe block]].
+is [predeclared](https://golang.org/doc/go_spec.html#Predeclared_identifiers)
+in the [universe block](https://golang.org/doc/go_spec.html#Blocks).
-The most commonly-used `error` implementation is the [[https://golang.org/pkg/errors/][errors]]
+The most commonly-used `error` implementation is the [errors](https://golang.org/pkg/errors/)
package's unexported `errorString` type.
// errorString is a trivial implementation of error.
@@ -76,12 +77,12 @@
square root of...") by calling the `error`'s `Error` method,
or by just printing it:
- f, err := Sqrt(-1)
- if err != nil {
- fmt.Println(err)
- }
+ f, err := Sqrt(-1)
+ if err != nil {
+ fmt.Println(err)
+ }
-The [[https://golang.org/pkg/fmt/][fmt]] package formats an `error` value by calling its `Error()`string` method.
+The [fmt](https://golang.org/pkg/fmt/) package formats an `error` value by calling its `Error() string` method.
It is the error implementation's responsibility to summarize the context.
The error returned by `os.Open` formats as "open /etc/passwd:
@@ -92,9 +93,9 @@
It formats a string according to `Printf`'s rules and returns it as an `error`
created by `errors.New`.
- if f < 0 {
- return 0, fmt.Errorf("math: square root of negative number %g", f)
- }
+ if f < 0 {
+ return 0, fmt.Errorf("math: square root of negative number %g", f)
+ }
In many cases `fmt.Errorf` is good enough,
but since `error` is an interface, you can use arbitrary data structures as error values,
@@ -111,12 +112,12 @@
return fmt.Sprintf("math: square root of negative number %g", float64(f))
}
-A sophisticated caller can then use a [[https://golang.org/doc/go_spec.html#Type_assertions][type assertion]]
+A sophisticated caller can then use a [type assertion](https://golang.org/doc/go_spec.html#Type_assertions)
to check for a `NegativeSqrtError` and handle it specially,
while callers that just pass the error to `fmt.Println` or `log.Fatal` will
see no change in behavior.
-As another example, the [[https://golang.org/pkg/encoding/json/][json]]
+As another example, the [json](https://golang.org/pkg/encoding/json/)
package specifies a `SyntaxError` type that the `json.Decode` function returns
when it encounters a syntax error parsing a JSON blob.
@@ -130,20 +131,20 @@
The `Offset` field isn't even shown in the default formatting of the error,
but callers can use it to add file and line information to their error messages:
- if err := dec.Decode(&val); err != nil {
- if serr, ok := err.(*json.SyntaxError); ok {
- line, col := findLine(f, serr.Offset)
- return fmt.Errorf("%s:%d:%d: %v", f.Name(), line, col, err)
- }
- return err
+ if err := dec.Decode(&val); err != nil {
+ if serr, ok := err.(*json.SyntaxError); ok {
+ line, col := findLine(f, serr.Offset)
+ return fmt.Errorf("%s:%d:%d: %v", f.Name(), line, col, err)
}
+ return err
+ }
-(This is a slightly simplified version of some [[https://github.com/camlistore/go4/blob/03efcb870d84809319ea509714dd6d19a1498483/jsonconfig/eval.go#L123-L135][actual code]]
-from the [[http://camlistore.org][Camlistore]] project.)
+(This is a slightly simplified version of some [actual code](https://github.com/camlistore/go4/blob/03efcb870d84809319ea509714dd6d19a1498483/jsonconfig/eval.go#L123-L135)
+from the [Camlistore](http://camlistore.org) project.)
The `error` interface requires only a `Error` method;
specific error implementations might have additional methods.
-For instance, the [[https://golang.org/pkg/net/][net]] package returns errors of type `error`,
+For instance, the [net](https://golang.org/pkg/net/) package returns errors of type `error`,
following the usual convention, but some of the error implementations have
additional methods defined by the `net.Error` interface:
@@ -160,15 +161,15 @@
For instance, a web crawler might sleep and retry when it encounters a temporary
error and give up otherwise.
- if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
- time.Sleep(1e9)
- continue
- }
- if err != nil {
- log.Fatal(err)
- }
+ if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
+ time.Sleep(1e9)
+ continue
+ }
+ if err != nil {
+ log.Fatal(err)
+ }
-* Simplifying repetitive error handling
+## Simplifying repetitive error handling
In Go, error handling is important. The language's design and conventions
encourage you to explicitly check for errors where they occur (as distinct
@@ -176,7 +177,7 @@
In some cases this makes Go code verbose,
but fortunately there are some techniques you can use to minimize repetitive error handling.
-Consider an [[https://cloud.google.com/appengine/docs/go/][App Engine]]
+Consider an [App Engine](https://cloud.google.com/appengine/docs/go/)
application with an HTTP handler that retrieves a record from the datastore
and formats it with a template.
@@ -222,7 +223,7 @@
}
This is simpler than the original version,
-but the [[https://golang.org/pkg/net/http/][http]] package doesn't understand
+but the [http](https://golang.org/pkg/net/http/) package doesn't understand
functions that return `error`.
To fix this we can implement the `http.Handler` interface's `ServeHTTP`
method on `appHandler`:
@@ -237,7 +238,7 @@
returned error (if any) to the user.
Notice that the method's receiver, `fn`, is a function.
(Go can do that!) The method invokes the function by calling the receiver
-in the expression `fn(w,`r)`.
+in the expression `fn(w, r)`.
Now when registering `viewRecord` with the http package we use the `Handle`
function (instead of `HandleFunc`) as `appHandler` is an `http.Handler`
@@ -266,7 +267,7 @@
type appHandler func(http.ResponseWriter, *http.Request) *appError
(It's usually a mistake to pass back the concrete type of an error rather than `error`,
-for reasons discussed in [[https://golang.org/doc/go_faq.html#nil_error][the Go FAQ]],
+for reasons discussed in [the Go FAQ](https://golang.org/doc/go_faq.html#nil_error),
but it's the right thing to do here because `ServeHTTP` is the only place
that sees the value and uses its contents.)
@@ -304,20 +305,20 @@
It doesn't end there; we can further improve the error handling in our application. Some ideas:
-- give the error handler a pretty HTML template,
+ - give the error handler a pretty HTML template,
-- make debugging easier by writing the stack trace to the HTTP response when the user is an administrator,
+ - make debugging easier by writing the stack trace to the HTTP response when the user is an administrator,
-- write a constructor function for `appError` that stores the stack trace for easier debugging,
+ - write a constructor function for `appError` that stores the stack trace for easier debugging,
-- recover from panics inside the `appHandler`,
- logging the error to the console as "Critical," while telling the user "a
- serious error has occurred." This is a nice touch to avoid exposing the
- user to inscrutable error messages caused by programming errors.
- See the [[https://golang.org/doc/articles/defer_panic_recover.html][Defer, Panic, and Recover]]
- article for more details.
+ - recover from panics inside the `appHandler`,
+ logging the error to the console as "Critical," while telling the user "a
+ serious error has occurred." This is a nice touch to avoid exposing the
+ user to inscrutable error messages caused by programming errors.
+ See the [Defer, Panic, and Recover](https://golang.org/doc/articles/defer_panic_recover.html)
+ article for more details.
-* Conclusion
+## Conclusion
Proper error handling is an essential requirement of good software.
By employing the techniques described in this post you should be able to
diff --git a/content/errors-are-values.article b/content/errors-are-values.article
index 0876d7a..2d78aa7 100644
--- a/content/errors-are-values.article
+++ b/content/errors-are-values.article
@@ -1,9 +1,10 @@
-Errors are values
+# Errors are values
12 Jan 2015
+Summary: A common point of discussion among Go programmers, especially those new to the language, is how to handle errors. The conversation often turns into a lament at the number of times the sequence
Rob Pike
-* Introduction
+##
A common point of discussion among Go programmers,
especially those new to the language, is how to handle errors.
@@ -33,7 +34,7 @@
Regardless of whether this explanation fits,
it is clear that these Go programmers miss a fundamental point about errors:
-_Errors_are_values._
+_Errors are values._
Values can be programmed, and since errors are values, errors can be programmed.
@@ -43,8 +44,8 @@
eliminating much of the boilerplate that arises if every error is checked with a rote if statement.
Here's a simple example from the `bufio` package's
-[[https://golang.org/pkg/bufio/#Scanner][`Scanner`]] type.
-Its [[https://golang.org/pkg/bufio/#Scanner.Scan][`Scan`]] method performs the underlying I/O,
+[`Scanner`](https://golang.org/pkg/bufio/#Scanner) type.
+Its [`Scan`](https://golang.org/pkg/bufio/#Scanner.Scan) method performs the underlying I/O,
which can of course lead to an error.
Yet the `Scan` method does not expose an error at all.
Instead, it returns a boolean, and a separate method, to be run at the end of the scan,
@@ -86,7 +87,7 @@
Under the covers what's happening, of course,
is that as soon as `Scan` encounters an I/O error, it records it and returns `false`.
-A separate method, [[https://golang.org/pkg/bufio/#Scanner.Err][`Err`]],
+A separate method, [`Err`](https://golang.org/pkg/bufio/#Scanner.Err),
reports the error value when the client asks.
Trivial though this is, it's not the same as putting
@@ -102,7 +103,7 @@
it's about using the language to handle errors with grace.
The topic of repetitive error-checking code arose when I attended the autumn 2014 GoCon in Tokyo.
-An enthusiastic gopher, who goes by [[https://twitter.com/jxck_][`@jxck_`]] on Twitter,
+An enthusiastic gopher, who goes by [`@jxck_`](https://twitter.com/jxck_) on Twitter,
echoed the familiar lament about error checking.
He had some code that looked schematically like this:
@@ -198,12 +199,12 @@
And much more.
In fact, this pattern appears often in the standard library.
-The [[https://golang.org/pkg/archive/zip/][`archive/zip`]] and
-[[https://golang.org/pkg/net/http/][`net/http`]] packages use it.
-More salient to this discussion, the [[https://golang.org/pkg/bufio/][`bufio` package's `Writer`]]
+The [`archive/zip`](https://golang.org/pkg/archive/zip/) and
+[`net/http`](https://golang.org/pkg/net/http/) packages use it.
+More salient to this discussion, the [`bufio` package's `Writer`](https://golang.org/pkg/bufio/)
is actually an implementation of the `errWriter` idea.
Although `bufio.Writer.Write` returns an error,
-that is mostly about honoring the [[https://golang.org/pkg/io/#Writer][`io.Writer`]] interface.
+that is mostly about honoring the [`io.Writer`](https://golang.org/pkg/io/#Writer) interface.
The `Write` method of `bufio.Writer` behaves just like our `errWriter.write`
method above, with `Flush` reporting the error, so our example could be written like this:
@@ -231,5 +232,5 @@
But remember: Whatever you do, always check your errors!
-Finally, for the full story of my interaction with @jxck_, including a little video he recorded,
-visit [[http://jxck.hatenablog.com/entry/golang-error-handling-lesson-by-rob-pike][his blog]].
+Finally, for the full story of my interaction with @jxck\_, including a little video he recorded,
+visit [his blog](http://jxck.hatenablog.com/entry/golang-error-handling-lesson-by-rob-pike).
diff --git a/content/examples.article b/content/examples.article
index dc24423..16614d3 100644
--- a/content/examples.article
+++ b/content/examples.article
@@ -1,12 +1,13 @@
-Testable Examples in Go
+# Testable Examples in Go
7 May 2015
Tags: godoc, testing
+Summary: Godoc [examples](https://golang.org/pkg/testing/#hdr-Examples) are snippets of Go code that are displayed as package documentation and that are verified by running them as tests. They can also be run by a user visiting the godoc web page for the package and clicking the associated "Run" button.
Andrew Gerrand
-* Introduction
+## Introduction
-Godoc [[https://golang.org/pkg/testing/#hdr-Examples][examples]] are snippets of
+Godoc [examples](https://golang.org/pkg/testing/#hdr-Examples) are snippets of
Go code that are displayed as package documentation and that are verified by
running them as tests.
They can also be run by a user visiting the godoc web page for the package
@@ -16,12 +17,12 @@
will not go out of date as the API changes.
The standard library includes many such examples
-(see the [[https://golang.org/pkg/strings/#Contains][`strings` package]],
+(see the [`strings` package](https://golang.org/pkg/strings/#Contains),
for instance).
This article explains how to write your own example functions.
-* Examples are tests
+## Examples are tests
Examples are compiled (and optionally executed) as part of a package's test
suite.
@@ -31,8 +32,8 @@
Unlike normal test functions, though, example functions take no arguments
and begin with the word `Example` instead of `Test`.
-The [[https://godoc.org/github.com/golang/example/stringutil/][`stringutil` package]]
-is part of the [[https://github.com/golang/example][Go example repository]].
+The [`stringutil` package](https://godoc.org/github.com/golang/example/stringutil/)
+is part of the [Go example repository](https://github.com/golang/example).
Here's an example that demonstrates its `Reverse` function:
package stringutil_test
@@ -65,7 +66,7 @@
PASS
ok github.com/golang/example/stringutil 0.009s
-* Output comments
+## Output comments
What does it mean that the `ExampleReverse` function "passes"?
@@ -110,7 +111,7 @@
run as unit tests, such as that which accesses the network,
while guaranteeing the example at least compiles.
-* Example function names
+## Example function names
Godoc uses a naming convention to associate an example function with a
package-level identifier.
@@ -130,11 +131,11 @@
func ExampleReverse_second()
func ExampleReverse_third()
-* Larger examples
+## Larger examples
Sometimes we need more than just a function to write a good example.
-For instance, to demonstrate the [[https://golang.org/pkg/sort/][`sort` package]]
+For instance, to demonstrate the [`sort` package](https://golang.org/pkg/sort/)
we should show an implementation of `sort.Interface`.
Since methods cannot be declared inside a function body, the example must
include some context in addition to the example function.
@@ -189,10 +190,10 @@
}
A package can contain multiple whole file examples; one example per file.
-Take a look at the [[https://golang.org/src/sort/][`sort` package's source code]]
+Take a look at the [`sort` package's source code](https://golang.org/src/sort/)
to see this in practice.
-* Conclusion
+## Conclusion
Godoc examples are a great way to write and maintain code as documentation.
They also present editable, working, runnable examples your users can build on.
diff --git a/content/experiment.article b/content/experiment.article
index 7255f3e..d93e976 100644
--- a/content/experiment.article
+++ b/content/experiment.article
@@ -1,10 +1,11 @@
-Experiment, Simplify, Ship
-01 Aug 2019
+# Experiment, Simplify, Ship
+1 Aug 2019
Tags: community, go2, proposals
+Summary: This is the blog post version of my talk last week at Gophercon 2019.
Russ Cox
-* Introduction
+## Introduction
This is the blog post version of my talk last week at Gophercon 2019.
@@ -34,13 +35,13 @@
And so on.
And so on.
-* The Four R’s of Simplifying
+## The Four R’s of Simplifying
During this process, there are four main ways that we can simplify
the overall experience of writing Go programs:
reshaping, redefining, removing, and restricting.
-*Simplify*by*Reshaping*
+**Simplify by Reshaping**
The first way we simplify is by reshaping what exists into a new form,
one that ends up being simpler overall.
@@ -94,7 +95,7 @@
The new structure also created space for other interesting experiments,
which we’ll see later.
-*Simplify*by*Redefining*
+**Simplify by Redefining**
A second way we simplify is by redefining
functionality we already have,
@@ -117,7 +118,7 @@
var more string
b = append(b, more...) // ok later
-*Simplify*by*Removing*
+**Simplify by Removing**
A third way we simplify is by removing functionality
when it has turned out to be less useful
@@ -142,7 +143,7 @@
making it confusing to need to decide which form to use.
Removing them simplified the language without reducing its power.
-*Simplify*by*Restricting*
+**Simplify by Restricting**
We can also simplify by restricting what is allowed.
From day one, Go has restricted the encoding of Go source files:
@@ -163,7 +164,7 @@
and led to successful experiments like
`goimports`, `gorename`, and many others.
-* Go Development Process
+## Go Development Process
This cycle of experiment and simplify is a good model for what we’ve been doing the past ten years.
but it has a problem:
@@ -229,7 +230,7 @@
of what will be shipping soon in Go 1.13
for error handling.
-* Errors
+## Errors
It is hard enough to write a program
that works the right way in all cases
@@ -250,7 +251,7 @@
with the technical detour I promised focusing
on the Go 1.13 error value changes.
-*Error*Values*
+**Error Values**
Error values had to start somewhere.
Here is the `Read` function from the first version of the `os` package:
@@ -262,7 +263,7 @@
There was no `File` type yet, and also no error type.
`Read` and the other functions in the package
-returned an `errno`int64` directly from the underlying Unix system call.
+returned an `errno int64` directly from the underlying Unix system call.
This code was checked in on September 10, 2008 at 12:14pm.
Like everything back then, it was an experiment,
@@ -308,13 +309,13 @@
and as a result we have experimented a lot with how
best to implement and use errors.
-*Errors*Are*Values*
+**Errors Are Values**
Making `error` a simple interface
and allowing many different implementations
means we have the entire Go language
available to define and inspect errors.
-We like to say that [[https://blog.golang.org/errors-are-values][errors are values]],
+We like to say that [errors are values](https://blog.golang.org/errors-are-values),
the same as any other Go value.
Here’s an example.
@@ -341,7 +342,7 @@
In this case, on this system, `ECONNREFUSED` is number 61.
Code that gets an error from a function
can test whether the error is `ECONNREFUSED`
-using ordinary [[https://golang.org/ref/spec#Comparison_operators][value equality]].
+using ordinary [value equality](https://golang.org/ref/spec#Comparison_operators).
Moving up a level,
in package `os`,
@@ -430,7 +431,7 @@
return err == syscall.EADDRNOTAVAIL
}
-A [[https://golang.org/ref/spec#Type_assertions][type assertion]] peels away any `net.OpError` wrapping.
+A [type assertion](https://golang.org/ref/spec#Type_assertions) peels away any `net.OpError` wrapping.
And then a second type assertion peels away any `os.SyscallError` wrapping.
And then the function checks the unwrapped error for equality with `EADDRNOTAVAIL`.
@@ -451,11 +452,11 @@
additional functionality that an error might provide,
leading to many packages,
such as
-[[https://godoc.org/github.com/pkg/errors][github.com/pkg/errors]],
-[[https://godoc.org/gopkg.in/errgo.v2][gopkg.in/errgo.v2]],
-[[https://godoc.org/github.com/hashicorp/errwrap][github.com/hashicorp/errwrap]],
-[[https://godoc.org/upspin.io/errors][upspin.io/errors]],
-[[https://godoc.org/github.com/spacemonkeygo/errors][github.com/spacemonkeygo/errors]],
+[github.com/pkg/errors](https://godoc.org/github.com/pkg/errors),
+[gopkg.in/errgo.v2](https://godoc.org/gopkg.in/errgo.v2),
+[github.com/hashicorp/errwrap](https://godoc.org/github.com/hashicorp/errwrap),
+[upspin.io/errors](https://godoc.org/upspin.io/errors),
+[github.com/spacemonkeygo/errors](https://godoc.org/github.com/spacemonkeygo/errors),
and more.
One problem with unconstrained experimentation,
@@ -467,7 +468,7 @@
in the form of agreed-upon optional interfaces,
so that different implementations could interoperate.
-*Unwrap*
+**Unwrap**
The most commonly-added functionality
in these packages is some method that can be
@@ -561,7 +562,7 @@
...
}
-*To*Unwrap*Or*Not*To*Unwrap?*
+**To Unwrap Or Not To Unwrap?**
Whether to make it possible to unwrap an error is an API decision,
the same way that whether to export a struct field is an API decision.
@@ -610,11 +611,11 @@
but implementations with unexported error fields do not,
and existing uses of `fmt.Errorf` with `%v` still use `%v`, not `%w`.
-*Error*Value*Printing*(Abandoned)*
+**Error Value Printing (Abandoned)**
Along with the design draft for Unwrap,
we also published a
-[[https://golang.org/design/go2draft-error-printing][design draft for an optional method for richer error printing]],
+[design draft for an optional method for richer error printing](https://golang.org/design/go2draft-error-printing),
including stack frame information
and support for localized, translated errors.
@@ -641,14 +642,14 @@
As a result of this community discussion,
we abandoned this printing design.
-*Error*Syntax*
+**Error Syntax**
That was error values.
Let’s look briefly at error syntax,
another abandoned experiment.
Here is some code from
-[[https://go.googlesource.com/go/+/go1.12/src/compress/lzw/writer.go#209][`compress/lzw/writer.go`]] in the standard library:
+[`compress/lzw/writer.go`](https://go.googlesource.com/go/+/go1.12/src/compress/lzw/writer.go#209) in the standard library:
// Write the savedCode if valid.
if e.savedCode != invalidCode {
@@ -675,7 +676,7 @@
If you were debugging this code, how long would it take to notice that?
At Gophercon last year we
-[[https://golang.org/design/go2draft-error-handling][presented a draft design]]
+[presented a draft design](https://golang.org/design/go2draft-error-handling)
for a new control flow construct marked by the keyword `check`.
`Check` consumes the error result from a function call or expression.
If the error is non-nil, the `check` returns that error.
@@ -723,18 +724,18 @@
In essence, `check` was a short way to write the `if` statement,
and `handle` was like
-[[https://golang.org/ref/spec#Defer_statements][`defer`]] but only for error return paths.
+[`defer`](https://golang.org/ref/spec#Defer_statements) but only for error return paths.
In contrast to exceptions in other languages,
this design retained Go’s important property that
every potential failing call was marked explicitly in the code,
-now using the `check` keyword instead of `if`err`!=`nil`.
+now using the `check` keyword instead of `if err != nil`.
The big problem with this design
was that `handle` overlapped too much,
and in confusing ways, with `defer`.
In May we posted
-[[https://golang.org/design/32437-try-builtin][a new design with three simplifications]]:
+[a new design with three simplifications](https://golang.org/design/32437-try-builtin):
to avoid the confusion with `defer`, the design dropped `handle` in favor of just using `defer`;
to match a similar idea in Rust and Swift, the design renamed `check` to `try`;
and to allow experimentation in a way that existing parsers like `gofmt` would recognize,
@@ -777,7 +778,7 @@
That’s everything about error handling,
which was one of the main focuses for this year.
-* Generics
+## Generics
Now for something a little less controversial: generics.
@@ -820,7 +821,7 @@
Last year we started exploring and experimenting again,
and we presented a
-[[https://github.com/golang/proposal/blob/master/design/go2draft-contracts.md][new design]],
+[new design](https://github.com/golang/proposal/blob/master/design/go2draft-contracts.md),
based on the idea of a contract,
at Gophercon last summer.
We’ve continued to experiment and simplify,
@@ -838,15 +839,15 @@
At Gophercon 2019, Ian Lance Taylor talked about
why we might want to add generics to Go
and briefly previewed the latest design draft.
-For details, see his blog post “[[https://blog.golang.org/why-generics][Why Generics?]]”
+For details, see his blog post “[Why Generics?](https://blog.golang.org/why-generics)”
-* Dependencies
+## Dependencies
The third big topic we identified for Go 2 was dependency management.
In 2010 we published a tool called `goinstall`,
which we called
-“[[https://groups.google.com/forum/#!msg/golang-nuts/8JFwR3ESjjI/cy7qZzN7Lw4J][an experiment in package installation]].”
+“[an experiment in package installation](https://groups.google.com/forum/#!msg/golang-nuts/8JFwR3ESjjI/cy7qZzN7Lw4J).”
It downloaded dependencies and stored them in your
Go distribution tree, in GOROOT.
@@ -863,7 +864,7 @@
but simplified Go development overall,
by separating your Go distribution from your Go libraries.
-*Compatibility*
+**Compatibility**
The `goinstall` experiment intentionally left out
an explicit concept of package versioning.
@@ -871,7 +872,7 @@
We did this so we could focus on the other
design problems for package installation.
-`Goinstall` became `go`get` as part of Go 1.
+`Goinstall` became `go get` as part of Go 1.
When people asked about versions,
we encouraged them to experiment by
creating additional tools, and they did.
@@ -879,7 +880,7 @@
to provide their USERS
with the same backwards compatibility
we did for the Go 1 libraries.
-Quoting [[https://golang.org/doc/faq#get_version][the Go FAQ]]:
+Quoting [the Go FAQ](https://golang.org/doc/faq#get_version):
.html experiment/div-quote.html
@@ -905,7 +906,7 @@
One of the most interesting experiments
was started by Gustavo Niemeyer.
He created a Git redirector called
-[[https://gopkg.in][`gopkg.in`]],
+[`gopkg.in`](https://gopkg.in),
which provided different import paths
for different API versions,
to help package authors
@@ -915,21 +916,21 @@
For example,
the Go source code in the GitHub repository
-[[https://github.com/go-yaml/yaml][go-yaml/yaml]]
+[go-yaml/yaml](https://github.com/go-yaml/yaml)
has different APIs
in the v1 and v2 semantic version tags.
The `gopkg.in` server provides these with
different import paths
-[[https://godoc.org/gopkg.in/yaml.v1][gopkg.in/yaml.v1]]
+[gopkg.in/yaml.v1](https://godoc.org/gopkg.in/yaml.v1)
and
-[[https://godoc.org/gopkg.in/yaml.v2][gopkg.in/yaml.v2]].
+[gopkg.in/yaml.v2](https://godoc.org/gopkg.in/yaml.v2).
The convention of providing backwards compatibility,
so that a newer version of a package can be used
in place of an older version,
-is what makes `go`get`’s very simple rule—“always download the latest copy”—work well even today.
+is what makes `go get`’s very simple rule—“always download the latest copy”—work well even today.
-*Versioning*And*Vendoring*
+**Versioning And Vendoring**
But in production contexts you need to be more precise
about dependency versions, to make builds reproducible.
@@ -958,7 +959,7 @@
Shipping vendor directories in the `go` command
led to more experimentation with vendoring itself,
and we realized that we had introduced a few problems.
-The most serious was that we lost _package_uniqueness_.
+The most serious was that we lost _package uniqueness_.
Before, during any given build,
an import path
might appear in lots of different packages,
@@ -998,7 +999,7 @@
likely breaking their respective users.
Convergence did not happen.
-*Dep*
+**Dep**
At Gophercon in 2016, we started an effort
to define a single tool to manage dependencies.
@@ -1069,7 +1070,7 @@
The dep experiment helped us
appreciate that convention better,
and we gave it a name:
-the _import_compatibility_rule_:
+the _import compatibility rule_:
.html experiment/div-quote.html
@@ -1078,7 +1079,7 @@
.html experiment/div-end.html
-*Go*Modules*
+**Go Modules**
We took what worked well in the dep experiment
and what we learned about what didn’t work well,
@@ -1099,7 +1100,7 @@
Go modules are now integrated with the `go` command,
which avoids needing to copy around vendor directories at all.
-*Replacing*GOPATH*
+**Replacing GOPATH**
With Go modules comes the end of GOPATH as a
global name space.
@@ -1144,21 +1145,21 @@
Everything needs updating for this new convention.
Most development tools use the
-[[https://godoc.org/go/build][`go/build`]] package to find and load Go source code.
+[`go/build`](https://godoc.org/go/build) package to find and load Go source code.
We’ve kept that package working,
but the API did not anticipate modules,
and the workarounds we added to avoid API changes
are slower than we’d like.
We’ve published a replacement,
-[[https://godoc.org/golang.org/x/tools/go/packages][`golang.org/x/tools/go/packages`]].
+[`golang.org/x/tools/go/packages`](https://godoc.org/golang.org/x/tools/go/packages).
Developer tools should now use that instead.
It supports both GOPATH and Go modules,
and it is faster and easier to use.
In a release or two we may move it into the standard library,
-but for now [[https://godoc.org/golang.org/x/tools/go/packages][`golang.org/x/tools/go/packages`]]
+but for now [`golang.org/x/tools/go/packages`](https://godoc.org/golang.org/x/tools/go/packages)
is stable and ready for use.
-*Go*Module*Proxies*
+**Go Module Proxies**
One of the ways modules simplify Go development
is by separating the concept of a group of packages
@@ -1167,7 +1168,7 @@
When we talked to Go users about dependencies,
almost everyone using Go at their companies
-asked how to route `go`get` package fetches
+asked how to route `go get` package fetches
through their own servers,
to better control what code can be used.
And even open-source developers were concerned
@@ -1186,18 +1187,18 @@
Companies can now easily run their own module proxy,
with custom rules about what is allowed
and where cached copies are stored.
-The open-source [[https://docs.gomods.io][Athens project]] has built just such a proxy,
+The open-source [Athens project](https://docs.gomods.io) has built just such a proxy,
and Aaron Schlesinger gave a talk about it at Gophercon 2019.
(We’ll add a link here when the video becomes available.)
And for individual developers and open source teams,
-the Go team at Google has [[https://groups.google.com/forum/#!topic/golang-announce/0wo8cOhGuAI][launched a proxy]] that serves
+the Go team at Google has [launched a proxy](https://groups.google.com/forum/#!topic/golang-announce/0wo8cOhGuAI) that serves
as a public mirror of all open-source Go packages,
and Go 1.13 will use that proxy by default when in module mode.
Katie Hockman gave a talk about this system at Gophercon 2019.
(We’ll add a link here when the video becomes available.)
-*Go*Modules*Status*
+**Go Modules Status**
Go 1.11 introduced modules as an experimental, opt-in preview.
We keep experimenting and simplifying.
@@ -1229,10 +1230,10 @@
And if you can’t,
please let us know what’s not working for you
or what’s too complex,
-by [[https://golang.org/issue/new][filing a bug report]],
+by [filing a bug report](https://golang.org/issue/new),
and we will experiment and simplify.
-* Tools
+## Tools
Error handling, generics, and dependency management
are going to take a few more years at least,
@@ -1265,7 +1266,7 @@
development helpers into a single tool,
now called `gopls` (pronounced “go, please”).
`Gopls` speaks the
-[[https://langserver.org/][Language Server Protocol, LSP]],
+[Language Server Protocol, LSP](https://langserver.org/),
and works with any integrated development environment
or text editor with LSP support,
which is essentially everything at this point.
@@ -1277,10 +1278,10 @@
Rebecca Stambler gave a talk with more details about `gopls` and IDEs at Gophercon 2019.
(We’ll add a link here when the video becomes available.)
-After `gopls`, we also have ideas for reviving `go`fix` in an
-extensible way and for making `go`vet` even more helpful.
+After `gopls`, we also have ideas for reviving `go fix` in an
+extensible way and for making `go vet` even more helpful.
-* Coda
+## Coda
.html experiment/div-indent.html
.image experiment/expsimp2.png _ 326
diff --git a/content/first-class-functions-in-go-and-new-go.article b/content/first-class-functions-in-go-and-new-go.article
index 29cab3a..a6f6728 100644
--- a/content/first-class-functions-in-go-and-new-go.article
+++ b/content/first-class-functions-in-go-and-new-go.article
@@ -1,17 +1,18 @@
-"First Class Functions in Go"
+# "First Class Functions in Go"
30 Jun 2011
Tags: codewalk, function, technical
+Summary: Programmers new to Go are often surprised by its support for function types, functions as values, and closures. The [First Class Functions in Go](https://golang.org/doc/codewalk/functions/) code walk demonstrates these features with a simulation of the dice game [Pig](http://en.wikipedia.org/wiki/Pig_(dice)). It is a pretty program that uses the language to great effect, and a fun read for Go beginners and veterans alike.
Andrew Gerrand
-* Introduction
+##
Programmers new to Go are often surprised by its support for function types,
functions as values, and closures.
-The [[https://golang.org/doc/codewalk/functions/][First Class Functions in Go]]
+The [First Class Functions in Go](https://golang.org/doc/codewalk/functions/)
code walk demonstrates these features with a simulation of the dice game
-[[http://en.wikipedia.org/wiki/Pig_(dice)][Pig]].
+[Pig](http://en.wikipedia.org/wiki/Pig_(dice)).
It is a pretty program that uses the language to great effect,
and a fun read for Go beginners and veterans alike.
-More resources are available at [[https://golang.org/doc/docs.html][golang.org]].
+More resources are available at [golang.org](https://golang.org/doc/docs.html).
diff --git a/content/first-go-program.article b/content/first-go-program.article
index 7554e03..de0507f 100644
--- a/content/first-go-program.article
+++ b/content/first-go-program.article
@@ -1,25 +1,26 @@
-The first Go program
+# The first Go program
18 Jul 2013
Tags: history
+Summary: Brad Fitzpatrick and I (Andrew Gerrand) recently started restructuring [godoc](https://golang.org/cmd/godoc/), and it occurred to me that it is one of the oldest Go programs. Robert Griesemer started writing it back in early 2009, and we're still using it today.
Andrew Gerrand
-* Introduction
+##
Brad Fitzpatrick and I (Andrew Gerrand) recently started restructuring
-[[https://golang.org/cmd/godoc/][godoc]], and it occurred to me that it is one
+[godoc](https://golang.org/cmd/godoc/), and it occurred to me that it is one
of the oldest Go programs.
Robert Griesemer started writing it back in early 2009,
and we're still using it today.
-When I [[https://twitter.com/enneff/status/357403054632484865][tweeted]] about
-this, Dave Cheney replied with an [[https://twitter.com/davecheney/status/357406479415914497][interesting question]]:
+When I [tweeted](https://twitter.com/enneff/status/357403054632484865) about
+this, Dave Cheney replied with an [interesting question](https://twitter.com/davecheney/status/357406479415914497):
what is the oldest Go program? Rob Pike dug into his mail and found it
in an old message to Robert and Ken Thompson.
What follows is the first Go program. It was written by Rob in February 2008,
when the team was just Rob, Robert, and Ken. They had a solid feature list
-(mentioned in [[https://commandcenter.blogspot.com.au/2012/06/less-is-exponentially-more.html][this blog post]])
+(mentioned in [this blog post](https://commandcenter.blogspot.com.au/2012/06/less-is-exponentially-more.html))
and a rough language specfication. Ken had just finished the first working version of
a Go compiler (it didn't produce native code, but rather transliterated Go code
to C for fast prototyping) and it was time to try writing a program with it.
@@ -47,11 +48,11 @@
.code first-go-program/slist.go
The program parses and prints an
-[[https://en.wikipedia.org/wiki/S-expression][S-expression]].
+[S-expression](https://en.wikipedia.org/wiki/S-expression).
It takes no user input and has no imports, relying only on the built-in
`print` facility for output.
It was written literally the first day there was a
-[[https://golang.org/change/8b8615138da3][working but rudimentary compiler]].
+[working but rudimentary compiler](https://golang.org/change/8b8615138da3).
Much of the language wasn't implemented and some of it wasn't even specified.
Still, the basic flavor of the language today is recognizable in this program.
@@ -115,7 +116,7 @@
For instance, Rob called his method receivers `this`, but now we use shorter
context-specific names. There are hundreds of more significant examples
and to this day we're still discovering better ways to write Go code.
-(Check out the [[https://github.com/golang/glog][glog package]]'s clever trick for
-[[https://github.com/golang/glog/blob/c6f9652c7179652e2fd8ed7002330db089f4c9db/glog.go#L893][handling verbosity levels]].)
+(Check out the [glog package](https://github.com/golang/glog)'s clever trick for
+[handling verbosity levels](https://github.com/golang/glog/blob/c6f9652c7179652e2fd8ed7002330db089f4c9db/glog.go#L893).)
I wonder what we'll learn tomorrow.
diff --git a/content/fosdem14.article b/content/fosdem14.article
index dd73c87..5817dd3 100644
--- a/content/fosdem14.article
+++ b/content/fosdem14.article
@@ -1,12 +1,13 @@
-Go talks at FOSDEM 2014
+# Go talks at FOSDEM 2014
24 Feb 2014
Tags: fosdem, youtube, talk
+Summary: At [FOSDEM](http://fosdem.org/) on the 2nd of February 2014 members of the Go community presented a series of talks in the Go Devroom. The day was a huge success, with 13 great talks presented to a consistently jam-packed room.
Andrew Gerrand
-* Introduction
+## Introduction
-At [[http://fosdem.org/][FOSDEM]] on the 2nd of February 2014 members of the Go
+At [FOSDEM](http://fosdem.org/) on the 2nd of February 2014 members of the Go
community presented a series of talks in the Go Devroom. The day was a huge
success, with 13 great talks presented to a consistently jam-packed room.
@@ -14,15 +15,15 @@
videos are presented below.
The complete series of talks is available
-[[http://www.youtube.com/playlist?list=PLtLJO5JKE5YDKG4WcaNts3IVZqhDmmuBH][as a YouTube playlist]].
+[as a YouTube playlist](http://www.youtube.com/playlist?list=PLtLJO5JKE5YDKG4WcaNts3IVZqhDmmuBH).
(You can also get them directly at the
-[[http://video.fosdem.org/2014/K4601/Sunday/][FOSDEM video archive]].)
+[FOSDEM video archive](http://video.fosdem.org/2014/K4601/Sunday/).)
-* Scaling with Go: YouTube's Vitess
+## Scaling with Go: YouTube's Vitess
Google Engineer Sugu Sougoumarane described how he and his
-team built [[https://github.com/youtube/vitess][Vitess]] in Go to help scale
-[[https://youtube.com][YouTube]].
+team built [Vitess](https://github.com/youtube/vitess) in Go to help scale
+[YouTube](https://youtube.com).
Vitess is a set of servers and tools primarily developed in Go.
It helps scale MySQL databases for the web, and is currently used as a
@@ -34,11 +35,11 @@
.iframe //www.youtube.com/embed/qATTTSg6zXk 310 550
-The slides for the talk are [[https://github.com/youtube/vitess/blob/master/doc/Vitess2014.pdf?raw=true][available here]].
+The slides for the talk are [available here](https://github.com/youtube/vitess/blob/master/doc/Vitess2014.pdf?raw=true).
-* Camlistore
+## Camlistore
-[[http://camlistore.org/][Camlistore]] is designed to be "your personal storage
+[Camlistore](http://camlistore.org/) is designed to be "your personal storage
system for life, putting you in control, and designed to last." It's open
source, under nearly 4 years of active development, and extremely flexible. In
this talk, Brad Fitzpatrick and Mathieu Lonjaret explain why they built it,
@@ -46,7 +47,7 @@
.iframe //www.youtube.com/embed/yvjeIZgykiA 310 550
-* Write your own Go compiler
+## Write your own Go compiler
Elliot Stoneham explains the potential for Go as a portable language and
reviews the Go tools that make that such an exciting possibility.
@@ -61,11 +62,11 @@
.iframe //www.youtube.com/embed/Qe8Dq7V3hXY 310 550
-* More
+## More
There were many more great talks, so please check out the complete series
-[[http://www.youtube.com/playlist?list=PLtLJO5JKE5YDKG4WcaNts3IVZqhDmmuBH][as a YouTube playlist]].
-In particular, the [[http://www.youtube.com/watch?v=cwpI5ONWGxc&list=PLtLJO5JKE5YDKG4WcaNts3IVZqhDmmuBH&index=7][lightning talks]] were a lot of fun.
+[as a YouTube playlist](http://www.youtube.com/playlist?list=PLtLJO5JKE5YDKG4WcaNts3IVZqhDmmuBH).
+In particular, the [lightning talks](http://www.youtube.com/watch?v=cwpI5ONWGxc&list=PLtLJO5JKE5YDKG4WcaNts3IVZqhDmmuBH&index=7) were a lot of fun.
I would like to give my personal thanks to the excellent speakers, Mathieu
Lonjaret for managing the video gear, and to the FOSDEM staff for making all
diff --git a/content/from-zero-to-go-launching-on-google.article b/content/from-zero-to-go-launching-on-google.article
index c0ef417..e0f6904 100644
--- a/content/from-zero-to-go-launching-on-google.article
+++ b/content/from-zero-to-go-launching-on-google.article
@@ -1,16 +1,17 @@
-From zero to Go: launching on the Google homepage in 24 hours
+# From zero to Go: launching on the Google homepage in 24 hours
13 Dec 2011
Tags: appengine, google, guest
+Summary: _This article was written by Reinaldo Aguiar, a software engineer from the Search team at Google. He shares his experience developing his first Go program and launching it to an audience of millions - all in one day!_
Reinaldo Aguiar
-* Introduction
+## Introduction
-_This_article_was_written_by_Reinaldo_Aguiar,_a_software_engineer_from_the_Search_team_at_Google._He_shares_his_experience_developing_his_first_Go_program_and_launching_it_to_an_audience_of_millions_-_all_in_one_day!_
+_This article was written by Reinaldo Aguiar, a software engineer from the Search team at Google. He shares his experience developing his first Go program and launching it to an audience of millions - all in one day!_
I was recently given the opportunity to collaborate on a small but highly
visible "20% project":
-the [[http://www.google.com/logos/2011/thanksgiving.html][Thanksgiving 2011 Google Doodle]].
+the [Thanksgiving 2011 Google Doodle](http://www.google.com/logos/2011/thanksgiving.html).
The doodle features a turkey produced by randomly combining different styles of head,
wings, feathers and legs.
The user can customize it by clicking on the different parts of the turkey.
@@ -37,8 +38,8 @@
Image manipulation tasks are CPU-bound, so performance is the deciding factor in this case.
To make an informed decision we ran a test.
-We quickly prepared a couple of equivalent demo apps for the new [[http://code.google.com/appengine/docs/python/python27/newin27.html][Python 2.7 runtime]]
-(which provides [[http://www.pythonware.com/products/pil/][PIL]],
+We quickly prepared a couple of equivalent demo apps for the new [Python 2.7 runtime](http://code.google.com/appengine/docs/python/python27/newin27.html)
+(which provides [PIL](http://www.pythonware.com/products/pil/),
a C-based imaging library) and the Go runtime.
Each app generates an image composed of several small images,
encodes the image as a JPEG, and sends the JPEG data as the HTTP response.
@@ -55,7 +56,7 @@
How fast can a person with no Go experience pick it up and build something
that performs and scales?
-* Design
+## Design
The approach was to encode the state of the turkey in the URL, drawing and encoding the snapshot on the fly.
@@ -81,7 +82,7 @@
There's no point serving an error page because the user will never see it -
the browser is almost certainly loading this URL into an image tag.
-* Implementation
+## Implementation
In the package scope we declare some data structures to describe the elements of the turkey,
the location of the corresponding images,
@@ -122,7 +123,7 @@
location and size of each layout element within the image.
Loading the images from disk on each request would be wasteful repetition,
-so we load all 106 images (13 * 8 elements + 1 background + 1 default) into
+so we load all 106 images (13 \* 8 elements + 1 background + 1 default) into
global variables upon receipt of the first request.
var (
@@ -157,15 +158,15 @@
Requests are handled in a straightforward sequence:
-- Parse the request URL, decoding the decimal value of each character in the path.
+ - Parse the request URL, decoding the decimal value of each character in the path.
-- Make a copy of the background image as the base for the final image.
+ - Make a copy of the background image as the base for the final image.
-- Draw each image element onto the background image using the layoutMap to determine where they should be drawn.
+ - Draw each image element onto the background image using the layoutMap to determine where they should be drawn.
-- Encode the image as a JPEG
+ - Encode the image as a JPEG
-- Return the image to user by writing the JPEG directly to the HTTP response writer.
+ - Return the image to user by writing the JPEG directly to the HTTP response writer.
Should any error occur, we serve the defaultImage to the user and log the
error to the App Engine dashboard for later analysis.
@@ -227,9 +228,9 @@
}
For brevity, I've omitted several helper functions from these code listings.
-See the [[http://code.google.com/p/go-thanksgiving/source/browse/][source code]] for the full scoop.
+See the [source code](http://code.google.com/p/go-thanksgiving/source/browse/) for the full scoop.
-* Performance
+## Performance
.image from-zero-to-go-launching-on-google_image02.png
@@ -240,7 +241,7 @@
This is wicked fast, considering that our request handler is doing image
manipulation and encoding on the fly.
-* Conclusions
+## Conclusions
I found Go's syntax to be intuitive, simple and clean.
I have worked a lot with interpreted languages in the past,
@@ -248,7 +249,7 @@
writing this app felt more like working with a dynamic,
interpreted language.
-The development server provided with the [[http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go][SDK]]
+The development server provided with the [SDK](http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go)
quickly recompiles the program after any change,
so I could iterate as fast as I would with an interpreted language.
It's dead simple, too - it took less than a minute to set up my development environment.
@@ -261,14 +262,14 @@
making it easier to learn good style and conventions.
In writing this application I used just three resources:
-App Engine's [[http://code.google.com/appengine/docs/go/gettingstarted/helloworld.html][Hello World Go example]],
-[[https://golang.org/pkg/][the Go packages documentation]],
-and [[https://blog.golang.org/2011/09/go-imagedraw-package.html][a blog post showcasing the Draw package]].
+App Engine's [Hello World Go example](http://code.google.com/appengine/docs/go/gettingstarted/helloworld.html),
+[the Go packages documentation](https://golang.org/pkg/),
+and [a blog post showcasing the Draw package](https://blog.golang.org/2011/09/go-imagedraw-package.html).
Thanks to the rapid iteration made possible by the development server and
the language itself,
I was able to pick up the language and build a super fast,
production ready, doodle generator in less than 24 hours.
-Download the full app source code (including images) at [[http://code.google.com/p/go-thanksgiving/source/browse/][the Google Code project]].
+Download the full app source code (including images) at [the Google Code project](http://code.google.com/p/go-thanksgiving/source/browse/).
Special thanks go to Guillermo Real and Ryan Germick who designed the doodle.
diff --git a/content/gccgo-in-gcc-471.article b/content/gccgo-in-gcc-471.article
index 6c90a93..a11a21a 100644
--- a/content/gccgo-in-gcc-471.article
+++ b/content/gccgo-in-gcc-471.article
@@ -1,12 +1,13 @@
-Gccgo in GCC 4.7.1
+# Gccgo in GCC 4.7.1
11 Jul 2012
Tags: release
+Summary: The Go language has always been defined by a [spec](https://golang.org/ref/spec), not an implementation. The Go team has written two different compilers that implement that spec: gc and gccgo. Having two different implementations helps ensure that the spec is complete and correct: when the compilers disagree, we fix the spec, and change one or both compilers accordingly. Gc is the original compiler, and the go tool uses it by default. Gccgo is a different implementation with a different focus, and in this post we’ll take a closer look at it.
Ian Lance Taylor
-* Introduction
+##
-The Go language has always been defined by a [[https://golang.org/ref/spec][spec]],
+The Go language has always been defined by a [spec](https://golang.org/ref/spec),
not an implementation.
The Go team has written two different compilers that implement that spec: gc and gccgo.
Having two different implementations helps ensure that the spec is complete and correct:
@@ -53,13 +54,13 @@
Gccgo distributions do not yet include a version of the go command.
However, if you install the go command from a standard Go release,
it already supports gccgo via the `-compiler` option:
-go build `-compiler`gccgo`myprog`.
+go build `-compiler gccgo myprog`.
The tools used for calls between Go and C/C++,
cgo and SWIG, also support gccgo.
We have put the Go frontend under the same BSD license as the rest of the Go
tools. You can download the source code for the frontend at the
-[[https://github.com/golang/gofrontend][gofrontend project]].
+[gofrontend project](https://github.com/golang/gofrontend).
Note that when the Go frontend is linked with the GCC backend to make gccgo,
GCC’s GPL license takes precedence.
diff --git a/content/gcdk-whats-new-in-march-2019.article b/content/gcdk-whats-new-in-march-2019.article
index 29bff99..cf66124 100644
--- a/content/gcdk-whats-new-in-march-2019.article
+++ b/content/gcdk-whats-new-in-march-2019.article
@@ -1,11 +1,12 @@
-What's new in the Go Cloud Development Kit
+# What's new in the Go Cloud Development Kit
4 Mar 2019
+Summary: Last July, we [introduced](https://blog.golang.org/go-cloud) the [Go Cloud Development Kit](https://gocloud.dev) (previously referred to as simply "Go Cloud"), an open source project building libraries and tools to improve the experience of developing for the cloud with Go. We've made a lot of progress since then -- thank you to early contributors! We look forward to growing the Go CDK community of users and contributors, and are excited to work closely with early adopters.
The Go Cloud Development Kit team at Google, Twitter #GoCDK
-* Introduction
+## Introduction
-Last July, we [[https://blog.golang.org/go-cloud][introduced]] the [[https://gocloud.dev][Go Cloud Development Kit]]
+Last July, we [introduced](https://blog.golang.org/go-cloud) the [Go Cloud Development Kit](https://gocloud.dev)
(previously referred to as simply "Go Cloud"),
an open source project building libraries and tools to improve the experience
of developing for the cloud with Go.
@@ -13,7 +14,7 @@
We look forward to growing the Go CDK community of users and contributors,
and are excited to work closely with early adopters.
-* Portable APIs
+## Portable APIs
Our first initiative is a set of portable APIs for common cloud services.
You write your application using these APIs,
@@ -23,10 +24,10 @@
These portable APIs are a great fit if any of the following are true:
-- You develop cloud applications locally.
-- You have on-premise applications that you want to run in the cloud (permanently, or as part of a migration).
-- You want portability across multiple clouds.
-- You are creating a new Go application that will use cloud services.
+ - You develop cloud applications locally.
+ - You have on-premise applications that you want to run in the cloud (permanently, or as part of a migration).
+ - You want portability across multiple clouds.
+ - You are creating a new Go application that will use cloud services.
Unlike traditional approaches where you would need to write new application
code for each cloud provider,
@@ -36,43 +37,43 @@
Our current set of APIs includes:
-- [[https://godoc.org/gocloud.dev/blob][blob]],
- for persistence of blob data.
- Supported providers include: AWS S3, Google Cloud Storage (GCS),
- Azure Storage, the filesystem, and in-memory.
-- [[https://godoc.org/gocloud.dev/pubsub][pubsub]] for publishing/subscribing
- of messages to a topic.
- Supported providers include: Amazon SNS/SQS,
- Google Pub/Sub, Azure Service Bus, RabbitMQ, and in-memory.
-- [[https://godoc.org/gocloud.dev/runtimevar][runtimevar]],
- for watching external configuration variables.
- Supported providers include AWS Parameter Store,
- Google Runtime Configurator, etcd, and the filesystem.
-- [[https://godoc.org/gocloud.dev/secrets][secrets]],
- for encryption/decryption.
- Supported providers include AWS KMS, GCP KMS,
- Hashicorp Vault, and local symmetric keys.
-- Helpers for connecting to cloud SQL providers. Supported providers include AWS RDS and Google Cloud SQL.
-- We are also working on a document storage API (e.g. MongoDB, DynamoDB, Firestore).
+ - [blob](https://godoc.org/gocloud.dev/blob),
+ for persistence of blob data.
+ Supported providers include: AWS S3, Google Cloud Storage (GCS),
+ Azure Storage, the filesystem, and in-memory.
+ - [pubsub](https://godoc.org/gocloud.dev/pubsub) for publishing/subscribing
+ of messages to a topic.
+ Supported providers include: Amazon SNS/SQS,
+ Google Pub/Sub, Azure Service Bus, RabbitMQ, and in-memory.
+ - [runtimevar](https://godoc.org/gocloud.dev/runtimevar),
+ for watching external configuration variables.
+ Supported providers include AWS Parameter Store,
+ Google Runtime Configurator, etcd, and the filesystem.
+ - [secrets](https://godoc.org/gocloud.dev/secrets),
+ for encryption/decryption.
+ Supported providers include AWS KMS, GCP KMS,
+ Hashicorp Vault, and local symmetric keys.
+ - Helpers for connecting to cloud SQL providers. Supported providers include AWS RDS and Google Cloud SQL.
+ - We are also working on a document storage API (e.g. MongoDB, DynamoDB, Firestore).
-* Feedback
+## Feedback
-We hope you're as excited about the Go CDK as we are -- check out our [[https://godoc.org/gocloud.dev][godoc]],
-walk through our [[https://github.com/google/go-cloud/tree/master/samples/tutorial][tutorial]],
+We hope you're as excited about the Go CDK as we are -- check out our [godoc](https://godoc.org/gocloud.dev),
+walk through our [tutorial](https://github.com/google/go-cloud/tree/master/samples/tutorial),
and use the Go CDK in your application(s).
We'd love to hear your ideas for other APIs and API providers you'd like to see.
If you're digging into Go CDK please share your experiences with us:
-- What went well?
-- Were there any pain points using the APIs?
-- Are there any features missing in the API you used?
-- Suggestions for documentation improvements.
+ - What went well?
+ - Were there any pain points using the APIs?
+ - Are there any features missing in the API you used?
+ - Suggestions for documentation improvements.
To send feedback, you can:
-- Submit issues to our public [[https://github.com/google/go-cloud/issues/new/choose][GitHub repository]].
-- Email [[mailto:go-cdk-feedback@google.com][go-cdk-feedback@google.com]].
-- Post to our [[https://groups.google.com/forum/#!forum/go-cloud][public Google group]].
+ - Submit issues to our public [GitHub repository](https://github.com/google/go-cloud/issues/new/choose).
+ - Email [go-cdk-feedback@google.com](mailto:go-cdk-feedback@google.com).
+ - Post to our [public Google group](https://groups.google.com/forum/#!forum/go-cloud).
Thanks!
diff --git a/content/generate.article b/content/generate.article
index a1fa9fd..3f601cf 100644
--- a/content/generate.article
+++ b/content/generate.article
@@ -1,10 +1,11 @@
-Generating code
+# Generating code
22 Dec 2014
Tags: programming, technical
+Summary: A property of universal computation—Turing completeness—is that a computer program can write a computer program. This is a powerful idea that is not appreciated as often as it might be, even though it happens frequently. It's a big part of the definition of a compiler, for instance. It's also how the `go` `test` command works: it scans the packages to be tested, writes out a Go program containing a test harness customized for the package, and then compiles and runs it. Modern computers are so fast this expensive-sounding sequence can complete in a fraction of a second.
Rob Pike
-* Generating code
+##
A property of universal computation—Turing completeness—is that a computer program can write a computer program.
This is a powerful idea that is not appreciated as often as it might be, even though it happens frequently.
@@ -15,7 +16,7 @@
Modern computers are so fast this expensive-sounding sequence can complete in a fraction of a second.
There are lots of other examples of programs that write programs.
-[[https://godoc.org/golang.org/x/tools/cmd/goyacc][Yacc]], for instance, reads in a description of a grammar and writes out a program to parse that grammar.
+[Yacc](https://godoc.org/golang.org/x/tools/cmd/goyacc), for instance, reads in a description of a grammar and writes out a program to parse that grammar.
The protocol buffer "compiler" reads an interface description and emits structure definitions,
methods, and other support code.
Configuration tools of all sorts work like this too, examining metadata or the environment
@@ -30,7 +31,7 @@
Until now, that is.
-The [[https://blog.golang.org/go1.4][latest Go release]], 1.4,
+The [latest Go release](https://blog.golang.org/go1.4), 1.4,
includes a new command that makes it easier to run such tools.
It's called `go` `generate`, and it works by scanning for special comments in Go source code
that identify general commands to run.
@@ -75,7 +76,7 @@
Every time `gopher.y` is modified, just rerun `go` `generate` to regenerate the parser.
For more details about how `go` `generate` works, including options, environment variables,
-and so on, see the [[https://golang.org/s/go1.4-generate][design document]].
+and so on, see the [design document](https://golang.org/s/go1.4-generate).
Go generate does nothing that couldn't be done with Make or some other build mechanism,
but it comes with the `go` tool—no extra installation required—and fits nicely into the Go ecosystem.
@@ -94,7 +95,7 @@
$ go get golang.org/x/tools/cmd/stringer
Here's an example from the documentation for
-[[https://godoc.org/golang.org/x/tools/cmd/stringer][`stringer`]].
+[`stringer`](https://godoc.org/golang.org/x/tools/cmd/stringer).
Imagine we have some code that contains a set of integer constants defining different types of pills:
package painkiller
diff --git a/content/getthee-to-go-meetup.article b/content/getthee-to-go-meetup.article
index 6f12947..69f9261 100644
--- a/content/getthee-to-go-meetup.article
+++ b/content/getthee-to-go-meetup.article
@@ -1,15 +1,16 @@
-Get thee to a Go meetup
+# Get thee to a Go meetup
27 Feb 2013
Tags: community, talk
+Summary: Last week, David Symonds and I each gave talks at Sydney's Go meetup, [golang-syd](http://www.meetup.com/golang-syd/). Dave spoke about [Go API design in the context of Protocol Buffers](http://talks.godoc.org/github.com/dsymonds/talks/2013-feb-golang-syd/golang-syd.slide), and I discussed some neat tricks in the construction of [a small command-line program](http://talks.godoc.org/github.com/nf/streak/talk.slide). The presentations were short but provoked some good questions and interesting discussion. Of the 50-odd attendees, most were regular Go programmers and a fair chunk write Go code professionally. It was a fun night.
Andrew Gerrand
-* Introduction
+##
Last week, David Symonds and I each gave talks at Sydney's Go meetup,
-[[http://www.meetup.com/golang-syd/][golang-syd]].
-Dave spoke about [[http://talks.godoc.org/github.com/dsymonds/talks/2013-feb-golang-syd/golang-syd.slide][Go API design in the context of Protocol Buffers]],
-and I discussed some neat tricks in the construction of [[http://talks.godoc.org/github.com/nf/streak/talk.slide][a small command-line program]].
+[golang-syd](http://www.meetup.com/golang-syd/).
+Dave spoke about [Go API design in the context of Protocol Buffers](http://talks.godoc.org/github.com/dsymonds/talks/2013-feb-golang-syd/golang-syd.slide),
+and I discussed some neat tricks in the construction of [a small command-line program](http://talks.godoc.org/github.com/nf/streak/talk.slide).
The presentations were short but provoked some good questions and interesting discussion.
Of the 50-odd attendees, most were regular Go programmers and a fair chunk
write Go code professionally. It was a fun night.
@@ -19,13 +20,13 @@
Despair not, however, as there are likely some people in your area who either
run a Go meetup or want to start one.
-The Go wiki lists [[https://golang.org/wiki/GoUserGroups][Go user groups]] around the world,
+The Go wiki lists [Go user groups](https://golang.org/wiki/GoUserGroups) around the world,
so if there's one nearby you should consider going along to the next event.
If not, why not start your own? To gauge interest,
-ask around in the [[https://plus.google.com/communities/114112804251407510571][Go+ Community]] and
-the [[http://groups.google.com/group/golang-nuts][golang-nuts mailing list]], and
-take a look at this [[http://golang.meetup.com/all/][list of people]] waiting
+ask around in the [Go+ Community](https://plus.google.com/communities/114112804251407510571) and
+the [golang-nuts mailing list](http://groups.google.com/group/golang-nuts), and
+take a look at this [list of people](http://golang.meetup.com/all/) waiting
for a Go meetup in their area.
Once you have a few people interested - and at least one person willing
to present something - pick a venue and set a date.
diff --git a/content/getting-to-know-go-community.article b/content/getting-to-know-go-community.article
index fc2db7a..b6e8b92 100644
--- a/content/getting-to-know-go-community.article
+++ b/content/getting-to-know-go-community.article
@@ -1,10 +1,11 @@
-Getting to know the Go community
+# Getting to know the Go community
21 Dec 2011
Tags: community
+Summary: Over the past couple of years Go has attracted a lot of users and contributors, and I've had a great time meeting and talking with many of you. However, for every Gopher I know there are dozens I know nothing about. In order to address this imbalance I've prepared a survey for Go users everywhere.
Andrew Gerrand
-* Introduction
+##
Over the past couple of years Go has attracted a lot of users and contributors,
and I've had a great time meeting and talking with many of you.
@@ -16,7 +17,7 @@
Among other things, this data will help myself and the rest of the Go team
plan future Go events and schedule conference appearances.
-Please take a minute to [[https://docs.google.com/spreadsheet/viewform?hl=en_US&formkey=dFdxOTU1Mm92VFA3eHdkekFPamJjUnc6MQ#gid=0][complete the survey now]].
+Please take a minute to [complete the survey now](https://docs.google.com/spreadsheet/viewform?hl=en_US&formkey=dFdxOTU1Mm92VFA3eHdkekFPamJjUnc6MQ#gid=0).
Thanks!
diff --git a/content/gif-decoder-exercise-in-go-interfaces.article b/content/gif-decoder-exercise-in-go-interfaces.article
index 9d58e57..12719c7 100644
--- a/content/gif-decoder-exercise-in-go-interfaces.article
+++ b/content/gif-decoder-exercise-in-go-interfaces.article
@@ -1,10 +1,11 @@
-A GIF decoder: an exercise in Go interfaces
+# A GIF decoder: an exercise in Go interfaces
25 May 2011
Tags: gif, gopher, image, interface, lagomorph, lzw, moustache, rodent, technical
+Summary: At the Google I/O conference in San Francisco on May 10, 2011, we announced that the Go language is now available on Google App Engine. Go is the first language to be made available on App Engine that compiles directly to machine code, which makes it a good choice for CPU-intensive tasks such as image manipulation.
Rob Pike
-* Introduction
+## Introduction
At the Google I/O conference in San Francisco on May 10,
2011, we announced that the Go language is now available on Google App Engine.
@@ -12,7 +13,7 @@
directly to machine code,
which makes it a good choice for CPU-intensive tasks such as image manipulation.
-In that vein, we demonstrated a program called [[http://moustach-io.appspot.com/][Moustachio]]
+In that vein, we demonstrated a program called [Moustachio](http://moustach-io.appspot.com/)
that makes it easy to improve a picture such as this one:
.image gif-decoder-exercise-in-go-interfaces_image00.jpg
@@ -23,7 +24,7 @@
All the graphical processing, including rendering the antialiased moustache,
is done by a Go program running on App Engine.
-(The source is available at [[http://code.google.com/p/appengine-go/source/browse/example/moustachio/][the appengine-go project]].)
+(The source is available at [the appengine-go project](http://code.google.com/p/appengine-go/source/browse/example/moustachio/).)
Although most images on the web—at least those likely to be moustachioed—are JPEGs,
there are countless other formats floating around,
@@ -35,7 +36,7 @@
make some problems easier to solve.
The rest of this blog post describes a couple of instances.
-* The GIF format
+## The GIF format
First, a quick tour of the GIF format. A GIF image file is _paletted_,
that is, each pixel value is an index into a fixed color map that is included in the file.
@@ -61,12 +62,12 @@
.image gif-decoder-exercise-in-go-interfaces_image03.gif
-* Deblocking the pixel data
+## Deblocking the pixel data
To decode GIF pixel data in Go, we can use the LZW decompressor from the
`compress/lzw` package.
It has a NewReader function that returns an object that,
-as [[https://golang.org/pkg/compress/lzw/#NewReader][the documentation]] says,
+as [the documentation](https://golang.org/pkg/compress/lzw/#NewReader) says,
"satisfies reads by decompressing the data read from r":
func NewReader(r io.Reader, order Order, litWidth int) io.ReadCloser
@@ -149,7 +150,7 @@
In this case, it means `blockReader` type's `Read` method never does any allocations.
It also means we don't need to keep a count around (it's implicit in the slice length),
and the built-in `copy` function guarantees we never copy more than we should.
-(For more about slices, see [[https://blog.golang.org/2011/01/go-slices-usage-and-internals.html][this post from the Go Blog]].)
+(For more about slices, see [this post from the Go Blog](https://blog.golang.org/2011/01/go-slices-usage-and-internals.html).)
Given the `blockReader` type, we can unblock the image data stream just
by wrapping the input reader,
@@ -160,7 +161,7 @@
This wrapping turns a block-delimited GIF image stream into a simple stream
of bytes accessible by calls to the `Read` method of the `blockReader`.
-* Connecting the pieces
+## Connecting the pieces
With `blockReader` implemented and the LZW compressor available from the library,
we have all the pieces we need to decode the image data stream.
@@ -192,7 +193,7 @@
just as we built the `blockReader` inside the call to `NewReader`,
but that might be packing too much into a single line of code.
-* Conclusion
+## Conclusion
Go's interfaces make it easy to construct software by assembling piece parts
like this to restructure data.
@@ -209,4 +210,4 @@
.image gif-decoder-exercise-in-go-interfaces_image01.gif
-The GIF format is defined at [[http://www.w3.org/Graphics/GIF/spec-gif89a.txt][http://www.w3.org/Graphics/GIF/spec-gif89a.txt]].
+The GIF format is defined at [http://www.w3.org/Graphics/GIF/spec-gif89a.txt](http://www.w3.org/Graphics/GIF/spec-gif89a.txt).
diff --git a/content/go-11-is-released.article b/content/go-11-is-released.article
index 7f55938..d16d1f3 100644
--- a/content/go-11-is-released.article
+++ b/content/go-11-is-released.article
@@ -1,10 +1,11 @@
-Go 1.1 is released
+# Go 1.1 is released
13 May 2013
Tags: release
+Summary: It is our great pleasure to announce the release of Go 1.1.
Andrew Gerrand
-* Introduction
+##
It is our great pleasure to announce the release of Go 1.1.
@@ -26,21 +27,21 @@
There are some minor changes to the language itself,
two of which are worth singling out here:
-the [[https://golang.org/doc/go1.1#return][changes to return requirements]] will
+the [changes to return requirements](https://golang.org/doc/go1.1#return) will
lead to more succinct and correct programs,
-and the introduction of [[https://golang.org/doc/go1.1#method_values][method values]] provides
+and the introduction of [method values](https://golang.org/doc/go1.1#method_values) provides
an expressive way to bind a method to its receiver as a function value.
Concurrent programming is safer in Go 1.1 with the addition of a race
detector for finding memory synchronization errors in your programs.
We will discuss the race detector more in an upcoming article,
-but for now [[https://golang.org/doc/articles/race_detector.html][the manual]] is
+but for now [the manual](https://golang.org/doc/articles/race_detector.html) is
a great place to get started.
The tools and standard library have been improved and expanded.
-You can read the full story in the [[https://golang.org/doc/go1.1][release notes]].
+You can read the full story in the [release notes](https://golang.org/doc/go1.1).
-As per our [[https://golang.org/doc/go1compat.html][compatibility guidelines]],
+As per our [compatibility guidelines](https://golang.org/doc/go1compat.html),
Go 1.1 remains compatible with Go 1.0 and we recommend all Go users upgrade to the new release.
All this would not have been possible without the help of our contributors from
@@ -51,6 +52,6 @@
Rémy Oudompheng, Dave Cheney, Mikio Hara,
Alex Brainman, Jan Ziak, and Daniel Morsing for their outstanding contributions.
-To grab the new release, follow the usual [[https://golang.org/doc/install][installation instructions]]. Happy hacking!
+To grab the new release, follow the usual [installation instructions](https://golang.org/doc/install). Happy hacking!
-_Thanks_to_Renée_French_for_the_gopher!_
+_Thanks to Renée French for the gopher!_
diff --git a/content/go-and-google-app-engine.article b/content/go-and-google-app-engine.article
index ec0f3ca..a1daad1 100644
--- a/content/go-and-google-app-engine.article
+++ b/content/go-and-google-app-engine.article
@@ -1,6 +1,7 @@
-Go and Google App Engine
+# Go and Google App Engine
10 May 2011
Tags: appengine, release
+Summary: Google’s App Engine provides a reliable, scalable, easy way to build and deploy applications for the web. Over a hundred thousand apps are hosted at appspot.com and custom domains using the App Engine infrastructure. Originally written for Python apps, in 2009 the system added a Java runtime. And today, at Google I/O, we’re thrilled to announce that Go will be next. It’s marked as an experimental App Engine feature for now, because it’s early days, but both the App Engine and Go teams are very excited about this milestone.
David Symonds
@@ -8,7 +9,7 @@
Andrew Gerrand
-* Introduction
+##
Google’s App Engine provides a reliable,
scalable, easy way to build and deploy applications for the web.
@@ -21,7 +22,7 @@
excited about this milestone.
By early days, we mean that it’s still rolling out.
-As of today, the App Engine SDK for Go is [[http://code.google.com/p/googleappengine/downloads/list][available for download]],
+As of today, the App Engine SDK for Go is [available for download](http://code.google.com/p/googleappengine/downloads/list),
and we will soon enable deployment of Go apps into the App Engine hosting infrastructure.
Today, through the SDK, you’ll be able to write web apps,
learn about the APIs (and the language, if it’s new to you),
@@ -44,8 +45,8 @@
The runtime provides the full Go language and almost all the standard libraries,
except for a few things that don’t make sense in the App Engine environment.
For instance, there is no `unsafe` package and the `syscall` package is trimmed.
-(The implementation uses an expanded version of the setup in the [[https://golang.org/doc/play/][Go Playground]]
-on [[https://golang.org/][golang.org]].)
+(The implementation uses an expanded version of the setup in the [Go Playground](https://golang.org/doc/play/)
+on [golang.org](https://golang.org/).)
Also, although goroutines and channels are present,
when a Go app runs on App Engine only one thread is run in a given instance.
@@ -59,15 +60,15 @@
Go on App Engine makes it possible to deploy efficient,
CPU-intensive web applications.
-If you want to know more, read the [[http://code.google.com/appengine/docs/go/][documentation]]
-(start with “[[http://code.google.com/appengine/docs/go/gettingstarted/][Getting Started]]”).
-The libraries and SDK are open source, hosted at [[http://code.google.com/p/appengine-go/][http://code.google.com/p/appengine-go/]].
-We’ve created a new [[http://groups.google.com/group/google-appengine-go][google-appengine-go]] mailing list;
+If you want to know more, read the [documentation](http://code.google.com/appengine/docs/go/)
+(start with “[Getting Started](http://code.google.com/appengine/docs/go/gettingstarted/)”).
+The libraries and SDK are open source, hosted at [http://code.google.com/p/appengine-go/](http://code.google.com/p/appengine-go/).
+We’ve created a new [google-appengine-go](http://groups.google.com/group/google-appengine-go) mailing list;
feel free to contact us there with App Engine-specific questions.
-The [[http://code.google.com/p/googleappengine/issues/list][issue tracker for App Engine]]
+The [issue tracker for App Engine](http://code.google.com/p/googleappengine/issues/list)
is the place for reporting issues related to the new Go SDK.
-The Go App Engine SDK is [[http://code.google.com/p/googleappengine/downloads/list][available]]
+The Go App Engine SDK is [available](http://code.google.com/p/googleappengine/downloads/list)
for Linux and Mac OS X (10.5 or greater);
we hope a Windows version will also be available soon.
diff --git a/content/go-and-google-cloud-platform.article b/content/go-and-google-cloud-platform.article
index 2da1591..9ab506d 100644
--- a/content/go-and-google-cloud-platform.article
+++ b/content/go-and-google-cloud-platform.article
@@ -1,42 +1,43 @@
-Go and the Google Cloud Platform
+# Go and the Google Cloud Platform
12 Jun 2013
+Summary: In 2011 we announced the [Go runtime for App Engine](https://developers.google.com/appengine/docs/go/overview). Since then, we have continued to improve the Go App Engine experience, and generally improved Go support for the Google Cloud Platform. For instance, the [google-api-go-client](http://code.google.com/p/google-api-go-client) provides a Go interface to a range of Google's public APis, including Compute Engine, Cloud Storage, BigQuery, Drive, and many more.
Andrew Gerrand
-* Introduction
+## Introduction
-In 2011 we announced the [[https://developers.google.com/appengine/docs/go/overview][Go runtime for App Engine]].
+In 2011 we announced the [Go runtime for App Engine](https://developers.google.com/appengine/docs/go/overview).
Since then, we have continued to improve the Go App Engine experience,
and generally improved Go support for the Google Cloud Platform.
-For instance, the [[http://code.google.com/p/google-api-go-client][google-api-go-client]] provides
+For instance, the [google-api-go-client](http://code.google.com/p/google-api-go-client) provides
a Go interface to a range of Google's public APis,
including Compute Engine, Cloud Storage, BigQuery,
Drive, and many more.
Learn more by watching these talks from Google I/O this year:
-* High Performance Apps with Go on App Engine
+## High Performance Apps with Go on App Engine
-_The_Go_runtime_for_App_Engine_is_a_high_performance_engine_for_
-_running_web_applications._It_produces_fast_responses,_
-_starts_instances_in_a_fraction_of_a_second,_makes_the_most_use_
-_of_instance_hours,_and_allows_your_app_to_do_serious_processing_
-_at_full_machine_speed._
-_Come_along_to_hear_how_to_fully_exploit_the_power_of_Go_on_App_
-_Engine_and_make_your_web_applications_the_best_they_can_be._
+_The Go runtime for App Engine is a high performance engine for_
+_running web applications. It produces fast responses,_
+_starts instances in a fraction of a second, makes the most use_
+_of instance hours, and allows your app to do serious processing_
+_at full machine speed._
+_Come along to hear how to fully exploit the power of Go on App_
+_Engine and make your web applications the best they can be._
.iframe //www.youtube.com/embed/fc25ihfXhbg 309 549
-* All the Ships in the World
+## All the Ships in the World
Visualizing Data with Google Cloud and Maps
-_Tens_of_thousands_of_ships_report_their_position_at_least_once_
-_every_5_minutes,_24_hours_a_day._
-_Visualizing_that_quantity_of_data_and_serving_it_out_to_large_
-_numbers_of_people_takes_lots_of_power_both_in_the_browser_and_on_the_server._
-_This_session_will_explore_the_use_of_Maps,_
-_App_Engine,_Go,_Compute_Engine,_BigQuery,_Cloud_Storage,_
-_and_WebGL_to_do_massive_data_visualization._
+_Tens of thousands of ships report their position at least once_
+_every 5 minutes, 24 hours a day._
+_Visualizing that quantity of data and serving it out to large_
+_numbers of people takes lots of power both in the browser and on the server._
+_This session will explore the use of Maps,_
+_App Engine, Go, Compute Engine, BigQuery, Cloud Storage,_
+_and WebGL to do massive data visualization._
.iframe //www.youtube.com/embed/MT7cd4M9vzs 309 549
diff --git a/content/go-app-engine-sdk-155-released.article b/content/go-app-engine-sdk-155-released.article
index 2666a77..8a60c9d 100644
--- a/content/go-app-engine-sdk-155-released.article
+++ b/content/go-app-engine-sdk-155-released.article
@@ -1,20 +1,21 @@
-Go App Engine SDK 1.5.5 released
+# Go App Engine SDK 1.5.5 released
11 Oct 2011
Tags: appengine, gofix, release
+Summary: Today we released version 1.5.5 the Go App Engine SDK. You can download it from the [App Engine downloads page](http://code.google.com/appengine/downloads.html).
Andrew Gerrand
-* Introduction
+##
Today we released version 1.5.5 the Go App Engine SDK.
-You can download it from the [[http://code.google.com/appengine/downloads.html][App Engine downloads page]].
+You can download it from the [App Engine downloads page](http://code.google.com/appengine/downloads.html).
This release includes changes and improvements to the App Engine APIs and
-brings the supporting Go tool chain to [[https://golang.org/doc/devel/release.html#r60][release.r60.2]]
+brings the supporting Go tool chain to [release.r60.2](https://golang.org/doc/devel/release.html#r60)
(the current stable release).
-Also included in this release are the [[https://golang.org/cmd/godoc/][godoc]],
-[[https://golang.org/cmd/gofmt/][gofmt]],
-and [[https://golang.org/cmd/gofix/][gofix]] tools from the Go tool chain.
+Also included in this release are the [godoc](https://golang.org/cmd/godoc/),
+[gofmt](https://golang.org/cmd/gofmt/),
+and [gofix](https://golang.org/cmd/gofix/) tools from the Go tool chain.
They can be found in the root directory of the SDK.
Some changes made in this release are backwards-incompatible,
@@ -26,17 +27,17 @@
packages and the updated Go standard library.
To update your apps, run:
- /path/to/sdk/gofix /path/to/your/app
+ /path/to/sdk/gofix /path/to/your/app
The SDK now includes the appengine package source code,
so you can use the local godoc to read App Engine API documentation:
- /path/to/sdk/godoc appengine/datastore Get
+ /path/to/sdk/godoc appengine/datastore Get
-*Important*note:* We have deprecated `api_version` 2.
+**Important note:** We have deprecated `api_version` 2.
Go apps that use `api_version` 2 will stop working after 16 December 2011.
Please update your apps to use `api_version` 3 before then.
-See the [[http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes][release notes]]
+See the [release notes](http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes)
for a full list of changes.
-Please direct any questions about the new SDK to the [[http://groups.google.com/group/google-appengine-go][Go App Engine discussion group]].
+Please direct any questions about the new SDK to the [Go App Engine discussion group](http://groups.google.com/group/google-appengine-go).
diff --git a/content/go-at-google-io-2011-videos.article b/content/go-at-google-io-2011-videos.article
index 909bfa9..6bd6168 100644
--- a/content/go-at-google-io-2011-videos.article
+++ b/content/go-at-google-io-2011-videos.article
@@ -1,10 +1,11 @@
-Go at Google I/O 2011: videos
+# Go at Google I/O 2011: videos
23 May 2011
Tags: appengine, gopher, talk, video
+Summary: The Go team had a great time at Google I/O 2011. It was a pleasure to meet so many programmers who share our enthusiasm for Go, and to share our work of the past few months. For those of you that couldn’t be there in person, you can now watch videos of our two Go presentations on YouTube.
Andrew Gerrand
-* Introduction
+## Introduction
The Go team had a great time at Google I/O 2011.
It was a pleasure to meet so many programmers who share our enthusiasm for Go,
@@ -12,21 +13,21 @@
For those of you that couldn’t be there in person,
you can now watch videos of our two Go presentations on YouTube.
-* Writing Web Apps in Go
+## Writing Web Apps in Go
-In “[[http://www.youtube.com/watch?v=-i0hat7pdpk][Writing Web Apps in Go]]”
-we announce the [[https://blog.golang.org/2011/05/go-and-google-app-engine.html][Go runtime for Google App Engine]]
-and walk through the development and deployment of [[http://moustach-io.appspot.com/][Moustachio]],
+In “[Writing Web Apps in Go](http://www.youtube.com/watch?v=-i0hat7pdpk)”
+we announce the [Go runtime for Google App Engine](https://blog.golang.org/2011/05/go-and-google-app-engine.html)
+and walk through the development and deployment of [Moustachio](http://moustach-io.appspot.com/),
the first Go App Engine app.
.iframe //www.youtube.com/embed/-i0hat7pdpk 349 560
-(See the [[https://golang.org/doc/talks/io2011/Writing_Web_Apps_in_Go.pdf][presentation slides]].)
+(See the [presentation slides](https://golang.org/doc/talks/io2011/Writing_Web_Apps_in_Go.pdf).)
-The [[https://code.google.com/p/appengine-go/source/browse/example/moustachio][source code]]
-for Moustachio is available as part of [[http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go][the SDK]]
+The [source code](https://code.google.com/p/appengine-go/source/browse/example/moustachio)
+for Moustachio is available as part of [the SDK](http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Go)
along with some other examples,
-such as this [[http://mandelbrot-tiles.appspot.com/][Mandelbrot demo]].
+such as this [Mandelbrot demo](http://mandelbrot-tiles.appspot.com/).
Most important, this talk features the debut of the plush gopher.
@@ -34,22 +35,22 @@
For those that didn’t get one at the conference, we hope to make him available for purchase online soon.
-* Real World Go
+## Real World Go
-“[[http://www.youtube.com/watch?v=7QDVRowyUQA][Real World Go]]”,
-presented at [[http://io-bootcamp.com][I/O Bootcamp]],
+“[Real World Go](http://www.youtube.com/watch?v=7QDVRowyUQA)”,
+presented at [I/O Bootcamp](http://io-bootcamp.com),
gives a brief introduction to Go and four case studies of its use in solving real problems:
-- [[http://heroku.com][Heroku]] with [[https://github.com/ha/doozerd][Doozer]],
+- [Heroku](http://heroku.com) with [Doozer](https://github.com/ha/doozerd),
a highly available consistent data store,
-- [[http://mroffice.org/telephony.html][MROffice Dialer]], a VOIP system for call centers,
+ - [MROffice Dialer](http://mroffice.org/telephony.html), a VOIP system for call centers,
-- [[http://www.atlassian.com][Atlassian]]’s virtual machine cluster management system,
+ - [Atlassian](http://www.atlassian.com)’s virtual machine cluster management system,
-- [[http://www.camlistore.org][Camlistore]], a content addressable storage system.
+ - [Camlistore](http://www.camlistore.org), a content addressable storage system.
.iframe //www.youtube.com/embed/7QDVRowyUQA 349 560
-(See the [[https://golang.org/doc/talks/io2011/Real_World_Go.pdf][presentation slides]].)
+(See the [presentation slides](https://golang.org/doc/talks/io2011/Real_World_Go.pdf).)
Thanks to everyone who attended our talks and workshops. We look forward to seeing you again soon!
diff --git a/content/go-at-heroku.article b/content/go-at-heroku.article
index 6663b6c..7fe67ef 100644
--- a/content/go-at-heroku.article
+++ b/content/go-at-heroku.article
@@ -1,17 +1,18 @@
-Go at Heroku
+# Go at Heroku
21 Apr 2011
Tags: guest
+Summary: _This week’s blog post is written by_ [_Keith Rarick_](http://xph.us/) _and_ [_Blake Mizerany_](http://itsbonus.heroku.com/), _systems engineers at_ [Heroku](http://www.heroku.com/). _In their own words, they "eat, drink, and sleep distributed systems." Here they discuss their experiences using Go._
Keith Rarick
Blake Mizerany
-* Introduction
+##
-_This_week’s_blog_post_is_written_by_ [[http://xph.us/][_Keith_Rarick_]]
-_and_ [[http://itsbonus.heroku.com/][_Blake_Mizerany_]],
-_systems_engineers_at_ [[http://www.heroku.com/][Heroku]].
-_In_their_own_words,_they_"eat,_drink,_and_sleep_distributed_systems."_Here_they_discuss_their_experiences_using_Go._
+_This week’s blog post is written by_ [_Keith Rarick_](http://xph.us/)
+_and_ [_Blake Mizerany_](http://itsbonus.heroku.com/),
+_systems engineers at_ [Heroku](http://www.heroku.com/).
+_In their own words, they "eat, drink, and sleep distributed systems." Here they discuss their experiences using Go._
A big problem that comes with building distributed systems is the coordination
of physical servers.
@@ -19,10 +20,10 @@
This critical data includes locks, configuration data,
and so on, and it must be consistent and available even during data store failures,
so we need a data store with solid consistency guarantees.
-Our solution to this problem is [[http://xph.us/2011/04/13/introducing-doozer.html][Doozer]],
+Our solution to this problem is [Doozer](http://xph.us/2011/04/13/introducing-doozer.html),
a new, consistent, highly-available data store written in Go.
-At Doozer's core is [[http://en.wikipedia.org/wiki/Paxos_(computer_science)][Paxos]],
+At Doozer's core is [Paxos](http://en.wikipedia.org/wiki/Paxos_(computer_science)),
a family of protocols for solving consensus in an unreliable network of unreliable nodes.
While Paxos is essential to running a fault-tolerant system,
it is notorious for being difficult to implement.
@@ -36,7 +37,7 @@
In Doozer, these processes are implemented as goroutines,
and their communications as channel operations.
In the same way that garbage collectors improve upon malloc and free,
-we found that [[https://blog.golang.org/2010/07/share-memory-by-communicating.html][goroutines and channels]]
+we found that [goroutines and channels](https://blog.golang.org/2010/07/share-memory-by-communicating.html)
improve upon the lock-based approach to concurrency.
These tools let us avoid complex bookkeeping and stay focused on the problem at hand.
We are still amazed at how few lines of code it took to achieve something
@@ -44,7 +45,7 @@
The standard packages in Go were another big win for Doozer.
The Go team is very pragmatic about what goes into them.
-For instance, a package we quickly found useful was [[https://golang.org/pkg/websocket/][websocket]].
+For instance, a package we quickly found useful was [websocket](https://golang.org/pkg/websocket/).
Once we had a working data store, we needed an easy way to introspect it
and visualize activity.
Using the websocket package, Keith was able to add the web viewer on his
@@ -52,7 +53,7 @@
This is a real testament to how well Go mixes systems and application programming.
One of our favorite productivity gains was provided by Go's source formatter:
-[[https://golang.org/cmd/gofmt/][gofmt]].
+[gofmt](https://golang.org/cmd/gofmt/).
We never argued over where to put a curly-brace,
tabs vs. spaces, or if we should align assignments.
We simply agreed that the buck stopped at the default output from gofmt.
diff --git a/content/go-at-io-frequently-asked-questions.article b/content/go-at-io-frequently-asked-questions.article
index 37a09c3..395d066 100644
--- a/content/go-at-io-frequently-asked-questions.article
+++ b/content/go-at-io-frequently-asked-questions.article
@@ -1,10 +1,11 @@
-Go at I/O: Frequently Asked Questions
+# Go at I/O: Frequently Asked Questions
27 May 2010
Tags: appengine
+Summary: Among the high-profile product launches at Google I/O last week, our small team gave presentations to packed rooms and met many present and future Go programmers. It was especially gratifying to meet with so many people who, after learning a bit about Go, were excited by the potential benefits (both immediate and long-term) they could gain from using it.
Andrew Gerrand
-* Introduction
+##
Among the high-profile product launches at Google I/O last week,
our small team gave presentations to packed rooms and met many present and
@@ -68,6 +69,6 @@
or came to talk with us at Office Hours.
We hope to see you again at future events.
-The video of [[http://code.google.com/events/io/2010/sessions/go-programming.html][Rob and Russ' talk]]
+The video of [Rob and Russ' talk](http://code.google.com/events/io/2010/sessions/go-programming.html)
will be uploaded to YouTube within the next week,
and will then be posted on this blog.
diff --git a/content/go-becomes-more-stable.article b/content/go-becomes-more-stable.article
index 011346b..a9f0dcf 100644
--- a/content/go-becomes-more-stable.article
+++ b/content/go-becomes-more-stable.article
@@ -1,10 +1,11 @@
-Go becomes more stable
+# Go becomes more stable
16 Mar 2011
Tags: release
+Summary: The Go project is moving fast. As we learn more about Go we are compelled to change our tools, libraries, and occasionally even the language itself. We permit backward-incompatible changes so that we can learn from, rather than immortalize, our mistakes. We believe flexibility at this stage of Go’s development is essential to the project’s development and, ultimately, its longevity.
Andrew Gerrand
-* Introduction
+##
The Go project is moving fast. As we learn more about Go we are compelled
to change our tools,
@@ -16,7 +17,7 @@
ultimately, its longevity.
Since Go's launch we have been making releases approximately once a week.
-Accompanying each release are [[https://golang.org/doc/devel/release.html][notes describing what changed]],
+Accompanying each release are [notes describing what changed](https://golang.org/doc/devel/release.html),
with any backwards-incompatible changes signposted.
Questions I hear often are "Is Go stable? How can I be sure that I won’t
have to update my Go code every week?" The answer to those questions are
@@ -37,13 +38,13 @@
The revision formerly tagged `release.2011-03-07.1` (now `weekly.2011-03-07.1`)
has been nominated our first stable release,
and has been given the tag `release.r56`.
-As we tag each stable release we will post an announcement to the new [[http://groups.google.com/group/golang-announce][golang-announce]] mailing list.
-(Why not [[http://groups.google.com/group/golang-announce/subscribe][subscribe now]]?)
+As we tag each stable release we will post an announcement to the new [golang-announce](http://groups.google.com/group/golang-announce) mailing list.
+(Why not [subscribe now](http://groups.google.com/group/golang-announce/subscribe)?)
What’s the upshot of all this? You can continue to keep your Go installation
-updated using `hg`update`release`,
+updated using `hg update release`,
but now you should only need to update when we tag a new stable release.
If you wish to stay at the leading edge, you should switch to the weekly
-tag with `hg`update`weekly`.
+tag with `hg update weekly`.
Happy coding!
diff --git a/content/go-brand.article b/content/go-brand.article
index ade49ff..0a7c2d6 100644
--- a/content/go-brand.article
+++ b/content/go-brand.article
@@ -1,10 +1,11 @@
-Go's New Brand
+# Go's New Brand
26 Apr 2018
Tags: brand
+Summary: I am delighted to announce the launch of Go’s new look and logo.
Steve Francia
-* Introduction
+## Introduction
I am delighted to announce the launch of Go’s new look and logo.
@@ -14,11 +15,11 @@
Go’s new brand is about our identity, our values, and our users. Over the past
several months we have worked with a brand agency to develop a brand guide for
-Go. Our agency, [[http://within.us/][Within]], coordinated with and built upon
+Go. Our agency, [Within](http://within.us/), coordinated with and built upon
the great foundation that Renee French established. Rest easy, our beloved
Gopher Mascot remains at the center of our brand.
-* New Logo
+## New Logo
Our logo follows the brand’s core philosophy of simplicity over complexity.
Using a modern, italicized sans-serif typeface combined with three simple motion
@@ -34,7 +35,7 @@
.html go-brand/video.html
-* New Brand Guide
+## New Brand Guide
The brand guide establishes the mission, values and voice for the Go project. In
general terms, a brand guide is a reference tool for establishing a consistent
@@ -46,7 +47,7 @@
.image go-brand/Go-BB_spread1.jpg
.image go-brand/Go-BB_spread2.jpg
-* New presentation themes
+## New presentation themes
In addition to our brand guide we have also developed a presentation theme. This
presentation theme will enable us to have a consistent representation of Go in
@@ -62,26 +63,26 @@
Like this blog and all our gopher images,
the slide themes are Creative Commons Attribution 3.0 licensed.
The photos in the slides are all from
-[[https://unsplash.com/][unsplash]] and are released under the unsplash license.
+[unsplash](https://unsplash.com/) and are released under the unsplash license.
Instructions to use slides:
-- Open the [[https://golang.org/s/presentation-theme][Go Slide Masters]] presentation on Google slides.
-- File > “Make a Copy” (you may need to login first)
-- Create new slides using the layouts provided in the layouts menu.
-- Use the included example slides to help guide the styling and creation of your presentation.
+ - Open the [Go Slide Masters](https://golang.org/s/presentation-theme) presentation on Google slides.
+ - File > “Make a Copy” (you may need to login first)
+ - Create new slides using the layouts provided in the layouts menu.
+ - Use the included example slides to help guide the styling and creation of your presentation.
-** Download
+### Download
The brand guide, logo and themes are copyrighted by the Go authors.
The brand guide contains the guidelines for acceptable logo use.
-- [[https://golang.org/s/brandbook][Brand Book (pdf)]]
-- [[https://golang.org/s/logos][Go Logos (zip)]]
-- [[https://golang.org/s/presentation-theme][Go Slide Masters (Google Slides)]]
+ - [Brand Book (pdf)](https://golang.org/s/brandbook)
+ - [Go Logos (zip)](https://golang.org/s/logos)
+ - [Go Slide Masters (Google Slides)](https://golang.org/s/presentation-theme)
-* What’s happening next
+## What’s happening next
The website will be getting a refresh based on the new design. Since we are
making significant changes, we are also taking this opportunity to update our
diff --git a/content/go-cloud.article b/content/go-cloud.article
index 6dff340..65fcce6 100644
--- a/content/go-cloud.article
+++ b/content/go-cloud.article
@@ -1,27 +1,28 @@
-Portable Cloud Programming with Go Cloud
+# Portable Cloud Programming with Go Cloud
24 Jul 2018
+Summary: Today, the Go team at Google is releasing a new open source project, [Go Cloud](https://github.com/google/go-cloud), a library and tools for developing on the [open cloud](https://cloud.google.com/open-cloud/). With this project, we aim to make Go the language of choice for developers building portable cloud applications.
Eno Compton
Cassandra Salisbury
-* Introduction
+## Introduction
Today, the Go team at Google is releasing a new open source project,
-[[https://github.com/google/go-cloud][Go Cloud]],
-a library and tools for developing on the [[https://cloud.google.com/open-cloud/][open cloud]].
+[Go Cloud](https://github.com/google/go-cloud),
+a library and tools for developing on the [open cloud](https://cloud.google.com/open-cloud/).
With this project, we aim to make Go the language of choice for developers
building portable cloud applications.
This post explains why we started this project, the details of how Go Cloud works, and how to get involved.
-* Why portable cloud programming? Why now?
+## Why portable cloud programming? Why now?
-We estimate there are now [[https://research.swtch.com/gophercount][over one million]]
+We estimate there are now [over one million](https://research.swtch.com/gophercount)
Go developers worldwide.
Go powers many of the most critical cloud infrastructure projects,
including Kubernetes, Istio, and Docker.
-Companies like Lyft, Capital One, Netflix and [[https://github.com/golang/go/wiki/GoUsers][many more]]
+Companies like Lyft, Capital One, Netflix and [many more](https://github.com/golang/go/wiki/GoUsers)
are depending on Go in production.
Over the years, we've found that developers love Go for cloud development
because of its efficiency,
@@ -31,8 +32,8 @@
we have been interviewing teams who work with Go to understand how they
use the language and how the Go ecosystem can improve further.
One common theme with many organizations is the need for portability across cloud providers.
-These teams want to deploy robust applications in [[https://en.wikipedia.org/wiki/Cloud_computing#Multicloud][multi-cloud]]
-and [[https://en.wikipedia.org/wiki/Cloud_computing#Hybrid_cloud][hybrid-cloud]] environments,
+These teams want to deploy robust applications in [multi-cloud](https://en.wikipedia.org/wiki/Cloud_computing#Multicloud)
+and [hybrid-cloud](https://en.wikipedia.org/wiki/Cloud_computing#Hybrid_cloud) environments,
and migrate their workloads between cloud providers without significant
changes to their code.
@@ -51,7 +52,7 @@
while also preserving the long-term flexibility for multi-cloud and hybrid-cloud architectures.
Go Cloud applications can also migrate to the cloud providers that best meet their needs.
-* What is Go Cloud?
+## What is Go Cloud?
We have identified common services used by cloud applications and have created
generic APIs to work across cloud providers.
@@ -70,13 +71,13 @@
Community feedback, from all types of developers at all levels,
will inform the priority of future APIs in Go Cloud.
-* How does it work?
+## How does it work?
At the core of Go Cloud is a collection of generic APIs for portable cloud programming.
Let's look at an example of using blob storage.
-You can use the generic type [[https://godoc.org/github.com/google/go-cloud/blob#Bucket][`*blob.Bucket`]]
+You can use the generic type [`*blob.Bucket`](https://godoc.org/github.com/google/go-cloud/blob#Bucket)
to copy a file from a local disk to a cloud provider.
-Let's start by opening an S3 bucket using the included [[https://godoc.org/github.com/google/go-cloud/blob/s3blob][s3blob package]]:
+Let's start by opening an S3 bucket using the included [s3blob package](https://godoc.org/github.com/google/go-cloud/blob/s3blob):
// setupBucket opens an AWS bucket.
func setupBucket(ctx context.Context) (*blob.Bucket, error) {
@@ -121,7 +122,7 @@
Go Cloud makes swapping out cloud storage a matter of changing the function
used to open the `*blob.Bucket`.
The application could instead use Google Cloud Storage by constructing a
-`*blob.Bucket` using [[https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket][`gcsblob.OpenBucket`]]
+`*blob.Bucket` using [`gcsblob.OpenBucket`](https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket)
without changing the code that copies the file:
// setupBucket opens a GCS bucket.
@@ -148,34 +149,34 @@
The setup code needed to access cloud services tends to follow a pattern:
higher abstractions are constructed from more basic abstractions.
-While you could write this code by hand, Go Cloud automates this with *Wire*,
+While you could write this code by hand, Go Cloud automates this with **Wire**,
a tool that generates cloud-specific setup code for you.
-The [[https://github.com/google/go-cloud/tree/master/wire][Wire documentation]]
-explains how to install and use the tool and the [[https://github.com/google/go-cloud/tree/master/samples/guestbook][Guestbook sample]]
+The [Wire documentation](https://github.com/google/go-cloud/tree/master/wire)
+explains how to install and use the tool and the [Guestbook sample](https://github.com/google/go-cloud/tree/master/samples/guestbook)
shows Wire in action.
-* How can I get involved and learn more?
+## How can I get involved and learn more?
-To get started, we recommend following [[https://github.com/google/go-cloud/tree/master/samples/tutorial][the tutorial]]
+To get started, we recommend following [the tutorial](https://github.com/google/go-cloud/tree/master/samples/tutorial)
and then trying to build an application yourself.
If you're already using AWS or GCP, you can try migrating parts of your
existing application to use Go Cloud.
If you're using a different cloud provider or an on-premise service,
you can extend Go Cloud to support it by implementing the driver interfaces
-(like [[https://godoc.org/github.com/google/go-cloud/blob/driver#Bucket][`driver.Bucket`]]).
+(like [`driver.Bucket`](https://godoc.org/github.com/google/go-cloud/blob/driver#Bucket)).
We appreciate any and all input you have about your experience.
-[[https://github.com/google/go-cloud][Go Cloud's]] development is conducted on GitHub.
+[Go Cloud's](https://github.com/google/go-cloud) development is conducted on GitHub.
We are looking forward to contributions, including pull requests.
-[[https://github.com/google/go-cloud/issues/new][File an issue]] to tell
+[File an issue](https://github.com/google/go-cloud/issues/new) to tell
us what could be better or what future APIs the project should support.
For updates and discussion about the project,
-join [[https://groups.google.com/forum/#!forum/go-cloud][the project's mailing list]].
+join [the project's mailing list](https://groups.google.com/forum/#!forum/go-cloud).
The project requires contributors to sign the same Contributor License Agreement
as that of the Go project.
-Read the [[https://github.com/google/go-cloud/blob/master/CONTRIBUTING.md][contribution guidelines]] for more details.
-Please note, Go Cloud is covered by the Go [[https://github.com/google/go-cloud/blob/master/CODE_OF_CONDUCT.md][Code of Conduct]].
+Read the [contribution guidelines](https://github.com/google/go-cloud/blob/master/CONTRIBUTING.md) for more details.
+Please note, Go Cloud is covered by the Go [Code of Conduct](https://github.com/google/go-cloud/blob/master/CODE_OF_CONDUCT.md).
Thank you for taking the time to learn about Go Cloud.
We are excited to work with you to make Go the language of choice for developers
diff --git a/content/go-concurrency-patterns-timing-out-and.article b/content/go-concurrency-patterns-timing-out-and.article
index 0789006..09d2502 100644
--- a/content/go-concurrency-patterns-timing-out-and.article
+++ b/content/go-concurrency-patterns-timing-out-and.article
@@ -1,10 +1,11 @@
-Go Concurrency Patterns: Timing out, moving on
+# Go Concurrency Patterns: Timing out, moving on
23 Sep 2010
Tags: concurrency, technical
+Summary: Concurrent programming has its own idioms. A good example is timeouts. Although Go's channels do not support them directly, they are easy to implement. Say we want to receive from the channel `ch`, but want to wait at most one second for the value to arrive. We would start by creating a signalling channel and launching a goroutine that sleeps before sending on the channel:
Andrew Gerrand
-* Introduction
+##
Concurrent programming has its own idioms.
A good example is timeouts. Although Go's channels do not support them directly,
@@ -14,22 +15,22 @@
We would start by creating a signalling channel and launching a goroutine
that sleeps before sending on the channel:
- timeout := make(chan bool, 1)
- go func() {
- time.Sleep(1 * time.Second)
- timeout <- true
- }()
+ timeout := make(chan bool, 1)
+ go func() {
+ time.Sleep(1 * time.Second)
+ timeout <- true
+ }()
We can then use a `select` statement to receive from either `ch` or `timeout`.
If nothing arrives on `ch` after one second,
the timeout case is selected and the attempt to read from ch is abandoned.
- select {
- case <-ch:
- // a read from ch has occurred
- case <-timeout:
- // the read from ch has timed out
- }
+ select {
+ case <-ch:
+ // a read from ch has occurred
+ case <-timeout:
+ // the read from ch has timed out
+ }
The `timeout` channel is buffered with space for 1 value,
allowing the timeout goroutine to send to the channel and then exit.
@@ -39,7 +40,7 @@
The `timeout` channel will eventually be deallocated by the garbage collector.
(In this example we used `time.Sleep` to demonstrate the mechanics of goroutines and channels.
-In real programs you should use ` [[https://golang.org/pkg/time/#After][time.After]]`,
+In real programs you should use ` [time.After](https://golang.org/pkg/time/#After)`,
a function that returns a channel and sends on that channel after the specified duration.)
Let's look at another variation of this pattern.
@@ -71,10 +72,10 @@
However, if the result arrives before the main function has made it to the receive,
the send could fail since no one is ready.
-This problem is a textbook example of what is known as a [[https://en.wikipedia.org/wiki/Race_condition][race condition]],
+This problem is a textbook example of what is known as a [race condition](https://en.wikipedia.org/wiki/Race_condition),
but the fix is trivial.
We just make sure to buffer the channel `ch` (by adding the buffer length
-as the second argument to [[https://golang.org/pkg/builtin/#make][make]]),
+as the second argument to [make](https://golang.org/pkg/builtin/#make)),
guaranteeing that the first send has a place to put the value.
This ensures the send will always succeed,
and the first value to arrive will be retrieved regardless of the order of execution.
diff --git a/content/go-developer-network.article b/content/go-developer-network.article
index 388cfef..a3c9658 100644
--- a/content/go-developer-network.article
+++ b/content/go-developer-network.article
@@ -1,10 +1,11 @@
-The New Go Developer Network
+# The New Go Developer Network
14 Mar 2019
Tags: Community
+Summary: A sense of community flourishes when we come together in person. As handles become names and avatars become faces, the smiles are real and true friendship can grow. There is joy in the sharing of knowledge and celebrating the accomplishments of our friends, colleagues, and neighbors. In our rapidly growing Go community this critical role is played by the Go user groups.
GoBridge Leadership Team
-* Introduction
+##
A sense of community flourishes when we come together in person. As handles become names
and avatars become faces, the smiles are real and true friendship can grow. There is joy
@@ -12,13 +13,13 @@
and neighbors. In our rapidly growing Go community this critical role is played by the
Go user groups.
-To better support our Go user groups worldwide, the Go community leaders at [[https://gobridge.org][GoBridge]]
+To better support our Go user groups worldwide, the Go community leaders at [GoBridge](https://gobridge.org)
and Google have joined forces to create a new program called the Go Developer Network
(GDN). The GDN is a collection of Go user groups working together with a shared mission
to empower developer communities with the knowledge, experience, and wisdom to build
the next generation of software in Go.
-We have partnered with Meetup to create our own [[https://meetup.com/pro/go][Pro Network of Go Developers]]
+We have partnered with Meetup to create our own [Pro Network of Go Developers](https://meetup.com/pro/go)
providing Go developers a single place to search for local user groups, events, and
see what other Gophers are doing around the world.
@@ -26,7 +27,7 @@
for that city and be provided with the latest news, information, conduct policies, and
procedures. GDN groups will have Meetup fees paid by the GDN and will have access to
special swag and other fun items. Each organizer of a GDN local group will continue to
-own the group and maintain full admin rights. *If*you*currently*run*a*user*group*,
-please fill out this [[https://j.mp/gdn-form][application]] to request to join the GDN.
+own the group and maintain full admin rights. **If you currently run a user group**,
+please fill out this [application](https://j.mp/gdn-form) to request to join the GDN.
We hope you are as excited about the GDN as we are.
diff --git a/content/go-fmt-your-code.article b/content/go-fmt-your-code.article
index 7b560d7..91d41f7 100644
--- a/content/go-fmt-your-code.article
+++ b/content/go-fmt-your-code.article
@@ -1,27 +1,28 @@
-go fmt your code
+# go fmt your code
23 Jan 2013
Tags: gofix, gofmt, technical
+Summary: [Gofmt](https://golang.org/cmd/gofmt/) is a tool that automatically formats Go source code.
Andrew Gerrand
-* Introduction
+## Introduction
-[[https://golang.org/cmd/gofmt/][Gofmt]] is a tool that automatically formats Go source code.
+[Gofmt](https://golang.org/cmd/gofmt/) is a tool that automatically formats Go source code.
Gofmt'd code is:
-- easier to *write*: never worry about minor formatting concerns while hacking away,
+ - easier to **write**: never worry about minor formatting concerns while hacking away,
-- easier to *read*: when all code looks the same you need not mentally convert
- others' formatting style into something you can understand.
+ - easier to **read**: when all code looks the same you need not mentally convert
+ others' formatting style into something you can understand.
-- easier to *maintain*: mechanical changes to the source don't cause unrelated
- changes to the file's formatting;
- diffs show only the real changes.
+ - easier to **maintain**: mechanical changes to the source don't cause unrelated
+ changes to the file's formatting;
+ diffs show only the real changes.
-- *uncontroversial*: never have a debate about spacing or brace position ever again!
+ - **uncontroversial**: never have a debate about spacing or brace position ever again!
-* Format your code
+## Format your code
We recently conducted a survey of Go packages in the wild and found that
about 70% of them are formatted according to gofmt's rules.
@@ -30,35 +31,35 @@
To format your code, you can use the gofmt tool directly:
- gofmt -w yourcode.go
+ gofmt -w yourcode.go
-Or you can use the "[[https://golang.org/cmd/go/#hdr-Run_gofmt_on_package_sources][go fmt]]" command:
+Or you can use the "[go fmt](https://golang.org/cmd/go/#hdr-Run_gofmt_on_package_sources)" command:
- go fmt path/to/your/package
+ go fmt path/to/your/package
To help keep your code in the canonical style,
the Go repository contains hooks for editors and version control systems
that make it easy to run gofmt on your code.
-For Vim users, the [[https://github.com/fatih/vim-go][Vim plugin for Go]]
+For Vim users, the [Vim plugin for Go](https://github.com/fatih/vim-go)
includes the :Fmt command that runs gofmt on the current buffer.
-For emacs users, [[https://github.com/dominikh/go-mode.el][go-mode.el]]
+For emacs users, [go-mode.el](https://github.com/dominikh/go-mode.el)
provides a gofmt-before-save hook that can be installed by adding this line
to your .emacs file:
- (add-hook 'before-save-hook #'gofmt-before-save)
+ (add-hook 'before-save-hook #'gofmt-before-save)
-For Eclipse or Sublime Text users, the [[https://github.com/GoClipse/goclipse][GoClipse]]
-and [[https://github.com/DisposaBoy/GoSublime][GoSublime]] projects add
+For Eclipse or Sublime Text users, the [GoClipse](https://github.com/GoClipse/goclipse)
+and [GoSublime](https://github.com/DisposaBoy/GoSublime) projects add
a gofmt facility to those editors.
-And for Git aficionados, the [[https://github.com/golang/go/blob/release-branch.go1.1/misc/git/pre-commit][misc/git/pre-commit script]]
+And for Git aficionados, the [misc/git/pre-commit script](https://github.com/golang/go/blob/release-branch.go1.1/misc/git/pre-commit)
is a pre-commit hook that prevents incorrectly-formatted Go code from being committed.
-If you use Mercurial, the [[https://bitbucket.org/fhs/hgstyle/overview][hgstyle plugin]]
+If you use Mercurial, the [hgstyle plugin](https://bitbucket.org/fhs/hgstyle/overview)
provides a gofmt pre-commit hook.
-* Mechanical source transformation
+## Mechanical source transformation
One of the greatest virtues of machine-formatted code is that it can be
transformed mechanically without generating unrelated formatting noise in the diffs.
@@ -70,32 +71,32 @@
The easiest way to mechanically manipulate Go code is with gofmt's -r flag.
The flag specifies a rewrite rule of the form
- pattern -> replacement
+ pattern -> replacement
where both pattern and replacement are valid Go expressions.
In the pattern, single-character lowercase identifiers serve as wildcards
matching arbitrary sub-expressions,
and those expressions are substituted for the same identifiers in the replacement.
-For example, this[[https://golang.org/cl/7038051][ recent change]] to the
-Go core rewrote some uses of [[https://golang.org/pkg/bytes/#Compare][bytes.Compare]]
-to use the more efficient [[https://golang.org/pkg/bytes/#Equal][bytes.Equal]].
+For example, this[ recent change](https://golang.org/cl/7038051) to the
+Go core rewrote some uses of [bytes.Compare](https://golang.org/pkg/bytes/#Compare)
+to use the more efficient [bytes.Equal](https://golang.org/pkg/bytes/#Equal).
The contributor made the change using just two gofmt invocations:
- gofmt -r 'bytes.Compare(a, b) == 0 -> bytes.Equal(a, b)'
- gofmt -r 'bytes.Compare(a, b) != 0 -> !bytes.Equal(a, b)'
+ gofmt -r 'bytes.Compare(a, b) == 0 -> bytes.Equal(a, b)'
+ gofmt -r 'bytes.Compare(a, b) != 0 -> !bytes.Equal(a, b)'
-Gofmt also enables [[https://golang.org/cmd/fix/][gofix]],
+Gofmt also enables [gofix](https://golang.org/cmd/fix/),
which can make arbitrarily complex source transformations.
Gofix was an invaluable tool during the early days when we regularly made
breaking changes to the language and libraries.
For example, before Go 1 the built-in error interface didn't exist and the
convention was to use the os.Error type.
-When we [[https://golang.org/doc/go1.html#errors][introduced error]],
+When we [introduced error](https://golang.org/doc/go1.html#errors),
we provided a gofix module that rewrote all references to os.Error and its
-associated helper functions to use error and the new [[https://golang.org/pkg/errors/][errors package]].
+associated helper functions to use error and the new [errors package](https://golang.org/pkg/errors/).
It would have been daunting to attempt by hand,
but with the code in a standard format it was relatively easy to prepare,
execute, and review this change which touched almost all Go code in existence.
-For more about gofix, see [[https://blog.golang.org/introducing-gofix][this article]].
+For more about gofix, see [this article](https://blog.golang.org/introducing-gofix).
diff --git a/content/go-fonts.article b/content/go-fonts.article
index f5e0aca..9af33a2 100644
--- a/content/go-fonts.article
+++ b/content/go-fonts.article
@@ -1,5 +1,6 @@
-Go fonts
+# Go fonts
16 Nov 2016
+Summary: The experimental user interface toolkit being built at [`golang.org/x/exp/shiny`](https://godoc.org/golang.org/x/exp/shiny) includes several text elements, but there is a problem with testing them: What font should be used? Answering this question led us to today's announcement, the release of a family of high-quality [WGL4](https://en.wikipedia.org/wiki/Windows_Glyph_List_4) TrueType fonts, created by the [Bigelow & Holmes](http://bigelowandholmes.typepad.com/) type foundry specifically for the Go project.
Nigel Tao
@@ -7,15 +8,15 @@
Rob Pike
-* An Announcement
+## An Announcement
The experimental user interface toolkit being built at
-[[https://godoc.org/golang.org/x/exp/shiny][`golang.org/x/exp/shiny`]]
+[`golang.org/x/exp/shiny`](https://godoc.org/golang.org/x/exp/shiny)
includes several text elements, but there is a problem with testing them:
What font should be used?
Answering this question led us to today's announcement,
-the release of a family of high-quality [[https://en.wikipedia.org/wiki/Windows_Glyph_List_4][WGL4]] TrueType fonts,
-created by the [[http://bigelowandholmes.typepad.com/][Bigelow & Holmes]] type foundry specifically for the Go project.
+the release of a family of high-quality [WGL4](https://en.wikipedia.org/wiki/Windows_Glyph_List_4) TrueType fonts,
+created by the [Bigelow & Holmes](http://bigelowandholmes.typepad.com/) type foundry specifically for the Go project.
The font family, called Go (naturally), includes proportional- and fixed-width faces in normal,
bold, and italic renderings.
@@ -37,7 +38,7 @@
.image go-fonts/go-mono.png _ 600
-* How to use them
+## How to use them
If you just want the TTF files, run
@@ -49,8 +50,8 @@
font, err := truetype.Parse(goregular.TTF)
-The [[https://godoc.org/github.com/golang/freetype/truetype][`github.com/golang/freetype/truetype`]]
-package provides the [[https://godoc.org/github.com/golang/freetype/truetype#Parse][`truetype.Parse`]] function today.
+The [`github.com/golang/freetype/truetype`](https://godoc.org/github.com/golang/freetype/truetype)
+package provides the [`truetype.Parse`](https://godoc.org/github.com/golang/freetype/truetype#Parse) function today.
There is also work underway to add a TrueType package under `golang.org/x`
again licensed under the same open source license as the rest of the Go project's software.
@@ -58,14 +59,14 @@
but for an overview of the fonts' design we asked Chuck Bigelow to provide some background.
The remainder of this blog post is his response.
-* Notes on the fonts, by Chuck Bigelow
+## Notes on the fonts, by Chuck Bigelow
The Go fonts are divided into two sets, Go proportional, which is
sans-serif, and Go Mono, which is slab-serif.
-* Go proportional fonts
+## Go proportional fonts
-** Sans-serif
+### Sans-serif
Go proportional fonts are sans-serif, like several popular fonts
for screen displays. There is some evidence that some sans-serif
@@ -75,7 +76,7 @@
seriffed faces, at least in the pair tested. [1] (The bracketed numbers
refer to the references listed at the end of this article.)
-** Style
+### Style
Go sans-serif fonts are "humanist" rather than "grotesque" in
style. This is an historical distinction, not an aesthetic judgment.
@@ -91,7 +92,7 @@
traces of pen-written calligraphy. There is some evidence that
humanist fonts are more legible than grotesque fonts. [2]
-** Italics
+### Italics
Go proportional italics have the same width metrics as the roman
fonts. Go italics are oblique versions of the romans, with one
@@ -105,7 +106,7 @@
.image go-fonts/abdgpq-proportional.png
-** The x-height
+### The x-height
The x-height of a typeface is the height of the lowercase 'x' relative
to the body size. The x-height of Go fonts is 53.0% of body size, a
@@ -116,7 +117,7 @@
(particularly x-height) and reading noted that types for reading on
screens and for small sizes tend to have large x-heights. [4]
-** DIN Legibility Standard
+### DIN Legibility Standard
The recent German DIN 1450 legibility standard recommends
several features for font legibility, including differentiation of
@@ -127,7 +128,7 @@
b d p q follow the natural asymmetries of legible Renaissance
handwriting, aiding differentiation to reduce confusion. [5]
-** Weights
+### Weights
The Go proportional fonts come in three weights: Normal, Medium,
and Bold. The Normal weight is strong enough that it maintains
@@ -145,7 +146,7 @@
bold weight of a normal font. More discussion of the relationship of
stem thicknesses, weight names, and CSS numbering is in [6].
-** WGL4 character set
+### WGL4 character set
The WGL4 character set, originally developed by Microsoft, is often
used as an informal standard character set. WGL4 includes Western
@@ -154,7 +155,7 @@
totalling more than 650 characters in all. The Go WGL4 fonts can
be used to compose a wide range of languages. [7]
-** Metric compatibility with Arial and Helvetica
+### Metric compatibility with Arial and Helvetica
The Go sans-serif fonts are nearly metrically compatible with
standard Helvetica or Arial characters. Texts set in Go occupy
@@ -164,9 +165,9 @@
wider than corresponding letters in Helvetica or Arial, so some
texts set in Go may take slightly more space.
-* Go Mono fonts
+## Go Mono fonts
-** Monospaced
+### Monospaced
Go Mono fonts are monospaced—each letter has the same width as
the other letters. Monospaced fonts have been used in programming
@@ -177,18 +178,18 @@
but they did have great mathematicians and a great sense of symmetry
and pattern that shaped their alphabet.)
-** Slab-serif
+### Slab-serif
The Go Mono fonts have slab-shaped serifs, giving them a sturdy
appearance.
-** Style
+### Style
The underlying letter shapes of Go Mono are, like the Go sans-serif fonts,
derived from humanist handwriting, but the monospacing and slab serifs
tend to obscure the historical and stylistic connections.
-** Italics
+### Italics
Go Mono Italics are oblique versions of the romans, with the exception
that the italic lowercase 'a' is redesigned as a cursive single-story form
@@ -199,7 +200,7 @@
.image go-fonts/abdgpq-mono.png
-** The x-height
+### The x-height
Go Mono fonts have the same x-height as Go sans-serif fonts, 53% of
the body size. Go Mono looks almost 18% bigger than Courier, which
@@ -207,7 +208,7 @@
as Courier, so the bigger look is gained with no loss of economy in
characters per line.
-** DIN Legibility Standard
+### DIN Legibility Standard
Go Mono fonts conform to the DIN 1450 standard by differentiating
zero from capital O; numeral 1 from capital I (eye) and lowercase l (ell);
@@ -215,7 +216,7 @@
bowls of b d p q follow the natural asymmetries of legible Renaissance
handwriting, aiding differentiation and reducing confusion.
-** Weights
+### Weights
Go Mono fonts have two weights: Normal and Bold. The normal weight
stem is the same as in Go Normal and thus maintains clarity on backlit
@@ -226,7 +227,7 @@
monospaced normal, the bold Mono appears slightly bolder than the
proportional Go Bold, as more black pixels are put into the same area.)
-** Metric compatibility with popular monospaced fonts
+### Metric compatibility with popular monospaced fonts
Go Mono is metrically compatible with Courier and other monospaced
fonts that match the "Pica" typewriter type widths of 10 characters per
@@ -234,7 +235,7 @@
per inch. The TrueType fonts are scalable, of course, so Go Mono can
be set at any size.
-** WGL4 character set
+### WGL4 character set
The Go Mono fonts offer the WGL4 character set often used as an
informal standard character set. WGL4 includes Western and Eastern
@@ -242,7 +243,7 @@
additional symbols, signs, and graphical characters. The 650+ characters
of the Go WGL4 sets can be used for a wide range of languages.
-* References
+## References
[1] Morris, R. A., Aquilante, K., Yager, D., & Bigelow, C.
(2002, May). P‐13: Serifs Slow RSVP Reading at Very Small Sizes,
@@ -286,12 +287,12 @@
Swiss German, Taita, Teso, Turkish, Turkmen, Upper Sorbian, Vunjo,
Walser, Welsh, Zulu
-* Jabberwocky in Go Regular
+## Jabberwocky in Go Regular
-From [[https://en.wikipedia.org/wiki/Jabberwocky]]:
+From [en.wikipedia.org/wiki/Jabberwocky](https://en.wikipedia.org/wiki/Jabberwocky):
.image go-fonts/go-font-jabberwocky.png _ 500
-There is no Greek version listed. Instead, a pangram from [[http://clagnut.com/blog/2380/#Greek]]:
+There is no Greek version listed. Instead, a pangram from [clagnut.com/blog/2380/#Greek](http://clagnut.com/blog/2380/#Greek):
.image go-fonts/go-font-greek.png _ 530
diff --git a/content/go-for-app-engine-is-now-generally.article b/content/go-for-app-engine-is-now-generally.article
index d1a2ac1..d4ba483 100644
--- a/content/go-for-app-engine-is-now-generally.article
+++ b/content/go-for-app-engine-is-now-generally.article
@@ -1,34 +1,35 @@
-Go for App Engine is now generally available
+# Go for App Engine is now generally available
21 Jul 2011
Tags: appengine, release
+Summary: The Go and App Engine teams are excited to announce that the Go runtime for App Engine is now generally available. This means you can take that Go app you've been working on (or meaning to work on) and deploy it to App Engine right now with the new [1.5.2 SDK](http://code.google.com/appengine/downloads.html).
Andrew Gerrand
-* Introduction
+##
The Go and App Engine teams are excited to announce that the Go runtime
for App Engine is now generally available.
This means you can take that Go app you've been working on (or meaning to
-work on) and deploy it to App Engine right now with the new [[http://code.google.com/appengine/downloads.html][1.5.2 SDK]].
+work on) and deploy it to App Engine right now with the new [1.5.2 SDK](http://code.google.com/appengine/downloads.html).
-Since we announced the Go runtime at Google I/O we have continued to [[http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes][improve and extend]]
+Since we announced the Go runtime at Google I/O we have continued to [improve and extend](http://code.google.com/p/googleappengine/wiki/SdkForGoReleaseNotes)
Go support for the App Engine APIs and have added the Channels API.
The Go Datastore API now supports transactions and ancestor queries, too.
-See the [[https://code.google.com/appengine/docs/go/][Go App Engine documentation]]
+See the [Go App Engine documentation](https://code.google.com/appengine/docs/go/)
for all the details.
For those who have been using the Go SDK already,
please note that the 1.5.2 release introduces `api_version` 2.
This is because the new SDK is based on Go `release.r58.1` (the current
stable version of Go) and is not backwards compatible with the previous release.
-Existing apps may require changes as per the [[https://golang.org/doc/devel/release.html#r58][r58 release notes]].
+Existing apps may require changes as per the [r58 release notes](https://golang.org/doc/devel/release.html#r58).
Once you've updated your code, you should redeploy your app with the line
-`api_version:`2` in its `app.yaml` file.
+`api_version: 2` in its `app.yaml` file.
Apps written against `api_version` 1 will stop working after the 18th of August.
Finally, we owe a huge thanks to our trusted testers and their many bug reports.
Their help was invaluable in reaching this important milestone.
-_The_fastest_way_to_get_started_with_Go_on_App_Engine_is_with_the_ [[http://code.google.com/appengine/docs/go/gettingstarted/][_Getting_Started_guide_]].
+_The fastest way to get started with Go on App Engine is with the_ [_Getting Started guide_](http://code.google.com/appengine/docs/go/gettingstarted/).
-_Note_that_the_Go_runtime_is_still_considered_experimental;_it_is_not_as_well-supported_as_the_Python_and_Java_runtimes._
+_Note that the Go runtime is still considered experimental; it is not as well-supported as the Python and Java runtimes._
diff --git a/content/go-image-package.article b/content/go-image-package.article
index 2626864..18eb920 100644
--- a/content/go-image-package.article
+++ b/content/go-image-package.article
@@ -1,22 +1,23 @@
-The Go image package
+# The Go image package
21 Sep 2011
Tags: image, libraries, technical
+Summary: The [image](https://golang.org/pkg/image/) and [image/color](https://golang.org/pkg/image/color/) packages define a number of types: `color.Color` and `color.Model` describe colors, `image.Point` and `image.Rectangle` describe basic 2-D geometry, and `image.Image` brings the two concepts together to represent a rectangular grid of colors. A [separate article](https://golang.org/doc/articles/image_draw.html) covers image composition with the [image/draw](https://golang.org/pkg/image/draw/) package.
Nigel Tao
-* Introduction
+## Introduction
-The [[https://golang.org/pkg/image/][image]] and [[https://golang.org/pkg/image/color/][image/color]]
+The [image](https://golang.org/pkg/image/) and [image/color](https://golang.org/pkg/image/color/)
packages define a number of types:
`color.Color` and `color.Model` describe colors,
`image.Point` and `image.Rectangle` describe basic 2-D geometry,
and `image.Image` brings the two concepts together to represent a rectangular grid of colors.
-A [[https://golang.org/doc/articles/image_draw.html][separate article]]
-covers image composition with the [[https://golang.org/pkg/image/draw/][image/draw]] package.
+A [separate article](https://golang.org/doc/articles/image_draw.html)
+covers image composition with the [image/draw](https://golang.org/pkg/image/draw/) package.
-* Colors and Color Models
+## Colors and Color Models
-[[https://golang.org/pkg/image/color/#Color][Color]] is an interface that
+[Color](https://golang.org/pkg/image/color/#Color) is an interface that
defines the minimal method set of any type that can be considered a color:
one that can be converted to red, green, blue and alpha values.
The conversion may be lossy, such as converting from CMYK or YCbCr color spaces.
@@ -39,7 +40,7 @@
to guarantee that multiplying two values together won't overflow.
Such multiplications occur when blending two colors according to an alpha
mask from a third color,
-in the style of [[https://en.wikipedia.org/wiki/Alpha_compositing][Porter and Duff's]] classic algebra:
+in the style of [Porter and Duff's](https://en.wikipedia.org/wiki/Alpha_compositing) classic algebra:
dstr, dstg, dstb, dsta := dst.RGBA()
srcr, srcg, srcb, srca := src.RGBA()
@@ -55,7 +56,7 @@
The image/color package also defines a number of concrete types that implement
the `Color` interface.
-For example, [[https://golang.org/pkg/image/color/#RGBA][`RGBA`]] is a struct
+For example, [`RGBA`](https://golang.org/pkg/image/color/#RGBA) is a struct
that represents the classic "8 bits per channel" color.
type RGBA struct {
@@ -66,16 +67,16 @@
in the range [0, 255].
`RGBA` satisfies the `Color` interface by multiplying that value by 0x101
to generate a 16-bit alpha-premultiplied color in the range [0, 65535].
-Similarly, the [[https://golang.org/pkg/image/color/#NRGBA][`NRGBA`]] struct
+Similarly, the [`NRGBA`](https://golang.org/pkg/image/color/#NRGBA) struct
type represents an 8-bit non-alpha-premultiplied color,
as used by the PNG image format.
When manipulating an `NRGBA`'s fields directly,
the values are non-alpha-premultiplied, but when calling the `RGBA` method,
the return values are alpha-premultiplied.
-A [[https://golang.org/pkg/image/color/#Model][`Model`]] is simply something
+A [`Model`](https://golang.org/pkg/image/color/#Model) is simply something
that can convert `Color`s to other `Color`s, possibly lossily.
-For example, the `GrayModel` can convert any `Color` to a desaturated [[https://golang.org/pkg/image/color/#Gray][`Gray`]].
+For example, the `GrayModel` can convert any `Color` to a desaturated [`Gray`](https://golang.org/pkg/image/color/#Gray).
A `Palette` can convert any `Color` to one from a limited palette.
type Model interface {
@@ -84,9 +85,9 @@
type Palette []Color
-* Points and Rectangles
+## Points and Rectangles
-A [[https://golang.org/pkg/image/#Point][`Point`]] is an (x,
+A [`Point`](https://golang.org/pkg/image/#Point) is an (x,
y) co-ordinate on the integer grid, with axes increasing right and down.
It is neither a pixel nor a grid square. A `Point` has no intrinsic width,
height or color, but the visualizations below use a small colored square.
@@ -97,9 +98,9 @@
.image go-image-package_image-package-01.png
- p := image.Point{2, 1}
+ p := image.Point{2, 1}
-A [[https://golang.org/pkg/image/#Rectangle][`Rectangle`]] is an axis-aligned
+A [`Rectangle`](https://golang.org/pkg/image/#Rectangle) is an axis-aligned
rectangle on the integer grid,
defined by its top-left and bottom-right `Point`.
A `Rectangle` also has no intrinsic color,
@@ -110,11 +111,11 @@
Min, Max Point
}
-For convenience, `image.Rect(x0,`y0,`x1,`y1)` is equivalent to `image.Rectangle{image.Point{x0,`y0},`image.Point{x1,`y1}}`,
+For convenience, `image.Rect(x0, y0, x1, y1)` is equivalent to `image.Rectangle{image.Point{x0, y0}, image.Point{x1, y1}}`,
but is much easier to type.
A `Rectangle` is inclusive at the top-left and exclusive at the bottom-right.
-For a `Point`p` and a `Rectangle`r`, `p.In(r)` if and only if `r.Min.X`<=`p.X`&&`p.X`<`r.Max.X`,
+For a `Point p` and a `Rectangle r`, `p.In(r)` if and only if `r.Min.X <= p.X && p.X < r.Max.X`,
and similarly for `Y`.
This is analogous to how a slice `s[i0:i1]` is inclusive at the low end
and exclusive at the high end.
@@ -122,34 +123,34 @@
.image go-image-package_image-package-02.png
- r := image.Rect(2, 1, 5, 5)
- // Dx and Dy return a rectangle's width and height.
- fmt.Println(r.Dx(), r.Dy(), image.Pt(0, 0).In(r)) // prints 3 4 false
+ r := image.Rect(2, 1, 5, 5)
+ // Dx and Dy return a rectangle's width and height.
+ fmt.Println(r.Dx(), r.Dy(), image.Pt(0, 0).In(r)) // prints 3 4 false
Adding a `Point` to a `Rectangle` translates the `Rectangle`.
Points and Rectangles are not restricted to be in the bottom-right quadrant.
.image go-image-package_image-package-03.png
- r := image.Rect(2, 1, 5, 5).Add(image.Pt(-4, -2))
- fmt.Println(r.Dx(), r.Dy(), image.Pt(0, 0).In(r)) // prints 3 4 true
+ r := image.Rect(2, 1, 5, 5).Add(image.Pt(-4, -2))
+ fmt.Println(r.Dx(), r.Dy(), image.Pt(0, 0).In(r)) // prints 3 4 true
Intersecting two Rectangles yields another Rectangle, which may be empty.
.image go-image-package_image-package-04.png
- r := image.Rect(0, 0, 4, 3).Intersect(image.Rect(2, 2, 5, 5))
- // Size returns a rectangle's width and height, as a Point.
- fmt.Printf("%#v\n", r.Size()) // prints image.Point{X:2, Y:1}
+ r := image.Rect(0, 0, 4, 3).Intersect(image.Rect(2, 2, 5, 5))
+ // Size returns a rectangle's width and height, as a Point.
+ fmt.Printf("%#v\n", r.Size()) // prints image.Point{X:2, Y:1}
Points and Rectangles are passed and returned by value.
A function that takes a `Rectangle` argument will be as efficient as a function
that takes two `Point` arguments,
or four `int` arguments.
-* Images
+## Images
-An [[https://golang.org/pkg/image/#Image][Image]] maps every grid square
+An [Image](https://golang.org/pkg/image/#Image) maps every grid square
in a `Rectangle` to a `Color` from a `Model`.
"The pixel at (x, y)" refers to the color of the grid square defined by the points (x,
y), (x+1, y), (x+1, y+1) and (x, y+1).
@@ -180,7 +181,7 @@
}
`Image` implementations do not have to be based on an in-memory slice of pixel data.
-For example, a [[https://golang.org/pkg/image/#Uniform][`Uniform`]] is an
+For example, a [`Uniform`](https://golang.org/pkg/image/#Uniform) is an
`Image` of enormous bounds and uniform color,
whose in-memory representation is simply that color.
@@ -189,7 +190,7 @@
}
Typically, though, programs will want an image based on a slice.
-Struct types like [[https://golang.org/pkg/image/#RGBA][`RGBA`]] and [[https://golang.org/pkg/image/#Gray][`Gray`]]
+Struct types like [`RGBA`](https://golang.org/pkg/image/#RGBA) and [`Gray`](https://golang.org/pkg/image/#Gray)
(which other packages refer to as `image.RGBA` and `image.Gray`) hold slices
of pixel data and implement the `Image` interface.
@@ -203,10 +204,10 @@
Rect Rectangle
}
-These types also provide a `Set(x,`y`int,`c`color.Color)` method that allows modifying the image one pixel at a time.
+These types also provide a `Set(x, y int, c color.Color)` method that allows modifying the image one pixel at a time.
- m := image.NewRGBA(image.Rect(0, 0, 640, 480))
- m.Set(5, 5, color.RGBA{255, 0, 0, 255})
+ m := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ m.Set(5, 5, color.RGBA{255, 0, 0, 255})
If you're reading or writing a lot of pixel data,
it can be more efficient, but more complicated,
@@ -220,23 +221,23 @@
.image go-image-package_image-package-05.png
- m0 := image.NewRGBA(image.Rect(0, 0, 8, 5))
- m1 := m0.SubImage(image.Rect(1, 2, 5, 5)).(*image.RGBA)
- fmt.Println(m0.Bounds().Dx(), m1.Bounds().Dx()) // prints 8, 4
- fmt.Println(m0.Stride == m1.Stride) // prints true
+ m0 := image.NewRGBA(image.Rect(0, 0, 8, 5))
+ m1 := m0.SubImage(image.Rect(1, 2, 5, 5)).(*image.RGBA)
+ fmt.Println(m0.Bounds().Dx(), m1.Bounds().Dx()) // prints 8, 4
+ fmt.Println(m0.Stride == m1.Stride) // prints true
For low-level code that works on an image's `Pix` field,
be aware that ranging over `Pix` can affect pixels outside an image's bounds.
In the example above, the pixels covered by `m1.Pix` are shaded in blue.
-Higher-level code, such as the `At` and `Set` methods or the [[https://golang.org/pkg/image/draw/][image/draw package]],
+Higher-level code, such as the `At` and `Set` methods or the [image/draw package](https://golang.org/pkg/image/draw/),
will clip their operations to the image's bounds.
-* Image Formats
+## Image Formats
The standard package library supports a number of common image formats,
such as GIF, JPEG and PNG.
If you know the format of a source image file,
-you can decode from an [[https://golang.org/pkg/io/#Reader][`io.Reader`]] directly.
+you can decode from an [`io.Reader`](https://golang.org/pkg/io/#Reader) directly.
import (
"image/jpeg"
@@ -254,7 +255,7 @@
}
If you have image data of unknown format,
-the [[https://golang.org/pkg/image/#Decode][`image.Decode`]] function can detect the format.
+the [`image.Decode`](https://golang.org/pkg/image/#Decode) function can detect the format.
The set of recognized formats is constructed at run time and is not limited
to those in the standard package library.
An image format package typically registers its format in an init function,
diff --git a/content/go-imagedraw-package.article b/content/go-imagedraw-package.article
index a28bc5d..9e24c14 100644
--- a/content/go-imagedraw-package.article
+++ b/content/go-imagedraw-package.article
@@ -1,12 +1,13 @@
-The Go image/draw package
+# The Go image/draw package
29 Sep 2011
Tags: draw, image, libraries, technical
+Summary: [Package image/draw](https://golang.org/pkg/image/draw/) defines only one operation: drawing a source image onto a destination image, through an optional mask image. This one operation is surprisingly versatile and can perform a number of common image manipulation tasks elegantly and efficiently.
Nigel Tao
-* Introduction
+## Introduction
-[[https://golang.org/pkg/image/draw/][Package image/draw]] defines only one operation:
+[Package image/draw](https://golang.org/pkg/image/draw/) defines only one operation:
drawing a source image onto a destination image,
through an optional mask image.
This one operation is surprisingly versatile and can perform a number of
@@ -16,12 +17,12 @@
library and the X Render extension.
The model is based on the classic "Compositing Digital Images" paper by Porter and Duff,
with an additional mask parameter:
-`dst`=`(src`IN`mask)`OP`dst`.
-For a fully opaque mask, this reduces to the original Porter-Duff formula: `dst`=`src`OP`dst`.
+`dst = (src IN mask) OP dst`.
+For a fully opaque mask, this reduces to the original Porter-Duff formula: `dst = src OP dst`.
In Go, a nil mask image is equivalent to an infinitely sized,
fully opaque mask image.
-The Porter-Duff paper presented [[http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png][12 different composition operators]],
+The Porter-Duff paper presented [12 different composition operators](http://www.w3.org/TR/SVGCompositing/examples/compop-porterduff-examples.png),
but with an explicit mask, only 2 of these are needed in practice:
source-over-destination and source.
In Go, these operators are represented by the `Over` and `Src` constants.
@@ -34,7 +35,7 @@
For fully opaque source and mask images, the two operators produce the same output,
but the `Src` operator is usually faster.
-* Geometric Alignment
+## Geometric Alignment
Composition requires associating destination pixels with source and mask pixels.
Obviously, this requires destination, source and mask images,
@@ -59,10 +60,10 @@
.image go-imagedraw-package_20.png
-The [[https://golang.org/pkg/image/draw/#DrawMask][`DrawMask`]] function
+The [`DrawMask`](https://golang.org/pkg/image/draw/#DrawMask) function
takes seven arguments,
but an explicit mask and mask-point are usually unnecessary,
-so the [[https://golang.org/pkg/image/draw/#Draw][`Draw`]] function takes five:
+so the [`Draw`](https://golang.org/pkg/image/draw/#Draw) function takes five:
// Draw calls DrawMask with a nil mask.
func Draw(dst Image, r image.Rectangle, src image.Image, sp image.Point, op Op)
@@ -70,14 +71,14 @@
mask image.Image, mp image.Point, op Op)
The destination image must be mutable, so the image/draw package defines
-a [[https://golang.org/pkg/image/draw/#Image][`draw.Image`]] interface which has a `Set` method.
+a [`draw.Image`](https://golang.org/pkg/image/draw/#Image) interface which has a `Set` method.
type Image interface {
image.Image
Set(x, y int, c color.Color)
}
-* Filling a Rectangle
+## Filling a Rectangle
To fill a rectangle with a solid color, use an `image.Uniform` source.
The `ColorImage` type re-interprets a `Color` as a practically infinite-sized
@@ -86,42 +87,42 @@
there is no need for an explicit "repeat bit" in Go's slice-based image types;
the concept is subsumed by `Uniform`.
- // image.ZP is the zero point -- the origin.
- draw.Draw(dst, r, &image.Uniform{c}, image.ZP, draw.Src)
+ // image.ZP is the zero point -- the origin.
+ draw.Draw(dst, r, &image.Uniform{c}, image.ZP, draw.Src)
To initialize a new image to all-blue:
- m := image.NewRGBA(image.Rect(0, 0, 640, 480))
- blue := color.RGBA{0, 0, 255, 255}
- draw.Draw(m, m.Bounds(), &image.Uniform{blue}, image.ZP, draw.Src)
+ m := image.NewRGBA(image.Rect(0, 0, 640, 480))
+ blue := color.RGBA{0, 0, 255, 255}
+ draw.Draw(m, m.Bounds(), &image.Uniform{blue}, image.ZP, draw.Src)
To reset an image to transparent (or black,
if the destination image's color model cannot represent transparency),
use `image.Transparent`, which is an `image.Uniform`:
- draw.Draw(m, m.Bounds(), image.Transparent, image.ZP, draw.Src)
+ draw.Draw(m, m.Bounds(), image.Transparent, image.ZP, draw.Src)
.image go-imagedraw-package_2a.png
-* Copying an Image
+## Copying an Image
To copy from a rectangle `sr` in the source image to a rectangle starting
at a point `dp` in the destination,
convert the source rectangle into the destination image's co-ordinate space:
- r := image.Rectangle{dp, dp.Add(sr.Size())}
- draw.Draw(dst, r, src, sr.Min, draw.Src)
+ r := image.Rectangle{dp, dp.Add(sr.Size())}
+ draw.Draw(dst, r, src, sr.Min, draw.Src)
Alternatively:
- r := sr.Sub(sr.Min).Add(dp)
- draw.Draw(dst, r, src, sr.Min, draw.Src)
+ r := sr.Sub(sr.Min).Add(dp)
+ draw.Draw(dst, r, src, sr.Min, draw.Src)
-To copy the entire source image, use `sr`=`src.Bounds()`.
+To copy the entire source image, use `sr = src.Bounds()`.
.image go-imagedraw-package_2b.png
-* Scrolling an Image
+## Scrolling an Image
Scrolling an image is just copying an image to itself,
with different destination and source rectangles.
@@ -129,16 +130,16 @@
just as Go's built-in copy function can handle overlapping destination and source slices.
To scroll an image m by 20 pixels:
- b := m.Bounds()
- p := image.Pt(0, 20)
- // Note that even though the second argument is b,
- // the effective rectangle is smaller due to clipping.
- draw.Draw(m, b, m, b.Min.Add(p), draw.Src)
- dirtyRect := b.Intersect(image.Rect(b.Min.X, b.Max.Y-20, b.Max.X, b.Max.Y))
+ b := m.Bounds()
+ p := image.Pt(0, 20)
+ // Note that even though the second argument is b,
+ // the effective rectangle is smaller due to clipping.
+ draw.Draw(m, b, m, b.Min.Add(p), draw.Src)
+ dirtyRect := b.Intersect(image.Rect(b.Min.X, b.Max.Y-20, b.Max.X, b.Max.Y))
.image go-imagedraw-package_2c.png
-* Converting an Image to RGBA
+## Converting an Image to RGBA
The result of decoding an image format might not be an `image.RGBA`:
decoding a GIF results in an `image.Paletted`,
@@ -146,13 +147,13 @@
and the result of decoding a PNG depends on the image data.
To convert any image to an `image.RGBA`:
- b := src.Bounds()
- m := image.NewRGBA(image.Rect(0, 0, b.Dx(), b.Dy()))
- draw.Draw(m, m.Bounds(), src, b.Min, draw.Src)
+ b := src.Bounds()
+ m := image.NewRGBA(image.Rect(0, 0, b.Dx(), b.Dy()))
+ draw.Draw(m, m.Bounds(), src, b.Min, draw.Src)
.image go-imagedraw-package_2d.png
-* Drawing Through a Mask
+## Drawing Through a Mask
To draw an image through a circular mask with center `p` and radius `r`:
@@ -181,21 +182,21 @@
.image go-imagedraw-package_2e.png
-* Drawing Font Glyphs
+## Drawing Font Glyphs
To draw a font glyph in blue starting from a point `p`,
-draw with an `image.ColorImage` source and an `image.Alpha`mask`.
+draw with an `image.ColorImage` source and an `image.Alpha mask`.
For simplicity, we aren't performing any sub-pixel positioning or rendering,
or correcting for a font's height above a baseline.
- src := &image.Uniform{color.RGBA{0, 0, 255, 255}}
- mask := theGlyphImageForAFont()
- mr := theBoundsFor(glyphIndex)
- draw.DrawMask(dst, mr.Sub(mr.Min).Add(p), src, image.ZP, mask, mr.Min, draw.Over)
+ src := &image.Uniform{color.RGBA{0, 0, 255, 255}}
+ mask := theGlyphImageForAFont()
+ mr := theBoundsFor(glyphIndex)
+ draw.DrawMask(dst, mr.Sub(mr.Min).Add(p), src, image.ZP, mask, mr.Min, draw.Over)
.image go-imagedraw-package_2f.png
-* Performance
+## Performance
The image/draw package implementation demonstrates how to provide an image
manipulation function that is both general purpose,
diff --git a/content/go-maps-in-action.article b/content/go-maps-in-action.article
index 9298c0d..42aaa47 100644
--- a/content/go-maps-in-action.article
+++ b/content/go-maps-in-action.article
@@ -1,23 +1,24 @@
-Go maps in action
+# Go maps in action
6 Feb 2013
Tags: map, technical
+Summary: One of the most useful data structures in computer science is the hash table. Many hash table implementations exist with varying properties, but in general they offer fast lookups, adds, and deletes. Go provides a built-in map type that implements a hash table.
Andrew Gerrand
-* Introduction
+## Introduction
One of the most useful data structures in computer science is the hash table.
Many hash table implementations exist with varying properties,
but in general they offer fast lookups, adds, and deletes.
Go provides a built-in map type that implements a hash table.
-* Declaration and initialization
+## Declaration and initialization
A Go map type looks like this:
map[KeyType]ValueType
-where `KeyType` may be any type that is [[https://golang.org/ref/spec#Comparison_operators][comparable]]
+where `KeyType` may be any type that is [comparable](https://golang.org/ref/spec#Comparison_operators)
(more on this later),
and `ValueType` may be any type at all, including another map!
@@ -41,7 +42,7 @@
In this article we will focus on the _use_ of maps,
not their implementation.
-* Working with maps
+## Working with maps
Go provides a familiar syntax for working with maps. This statement sets the key `"route"` to the value `66`:
@@ -51,7 +52,7 @@
i := m["route"]
-If the requested key doesn't exist, we get the value type's _zero_value_.
+If the requested key doesn't exist, we get the value type's _zero value_.
In this case the value type is `int`, so the zero value is `0`:
j := m["root"]
@@ -99,7 +100,7 @@
m = map[string]int{}
-* Exploiting zero values
+## Exploiting zero values
It can be convenient that a map retrieval yields a zero value when the key is not present.
@@ -137,10 +138,10 @@
these last two examples will work even if nobody likes cheese or bacon (however
unlikely that may be).
-* Key types
+## Key types
As mentioned earlier, map keys may be of any type that is comparable.
-The [[https://golang.org/ref/spec#Comparison_operators][language spec]]
+The [language spec](https://golang.org/ref/spec#Comparison_operators)
defines this precisely,
but in short, comparable types are boolean,
numeric, string, pointer, channel, and interface types,
@@ -193,13 +194,13 @@
n := hits[Key{"/ref/spec", "ch"}]
-* Concurrency
+## Concurrency
-[[https://golang.org/doc/faq#atomic_maps][Maps are not safe for concurrent use]]:
+[Maps are not safe for concurrent use](https://golang.org/doc/faq#atomic_maps):
it's not defined what happens when you read and write to them simultaneously.
If you need to read from and write to a map from concurrently executing goroutines,
the accesses must be mediated by some kind of synchronization mechanism.
-One common way to protect maps is with [[https://golang.org/pkg/sync/#RWMutex][sync.RWMutex]].
+One common way to protect maps is with [sync.RWMutex](https://golang.org/pkg/sync/#RWMutex).
This statement declares a `counter` variable that is an anonymous struct
containing a map and an embedded `sync.RWMutex`.
@@ -222,7 +223,7 @@
counter.m["some_key"]++
counter.Unlock()
-* Iteration order
+## Iteration order
When iterating over a map with a range loop,
the iteration order is not specified and is not guaranteed to be the same
diff --git a/content/go-one-year-ago-today.article b/content/go-one-year-ago-today.article
index 5282a5c..777bf12 100644
--- a/content/go-one-year-ago-today.article
+++ b/content/go-one-year-ago-today.article
@@ -1,10 +1,11 @@
-Go: one year ago today
+# Go: one year ago today
10 Nov 2010
Tags: birthday
+Summary: On the 10th of November 2009 we launched the Go project: an open-source programming language with a focus on simplicity and efficiency. The intervening year has seen a great many developments both in the Go project itself and in its community.
Andrew Gerrand
-* Introduction
+##
On the 10th of November 2009 we launched the Go project:
an open-source programming language with a focus on simplicity and efficiency.
@@ -22,14 +23,14 @@
a chord with a broad cross-section of the programming community.
That cross-section grew to become a dedicated community of enthusiastic Go coders.
-Our [[http://groups.google.com/group/golang-nuts][mailing list]] has over 3,800 members,
+Our [mailing list](http://groups.google.com/group/golang-nuts) has over 3,800 members,
with around 1,500 posts each month.
-The project has over 130 [[https://golang.org/CONTRIBUTORS][contributors]]
+The project has over 130 [contributors](https://golang.org/CONTRIBUTORS)
(people who have submitted code or documentation),
and of the 2,800 commits since launch almost one third were contributed
by programmers outside the core team.
To get all that code into shape, nearly 14,000 emails were exchanged on
-our [[http://groups.google.com/group/golang-dev][development mailing list]].
+our [development mailing list](http://groups.google.com/group/golang-dev).
Those numbers reflect a labor whose fruits are evident in the project’s code base.
The compilers have improved substantially,
@@ -42,27 +43,27 @@
recently reaching the milestone of passing all tests.
The Go tool set has been expanded and improved.
-The Go documentation tool, [[https://golang.org/cmd/godoc/][godoc]],
+The Go documentation tool, [godoc](https://golang.org/cmd/godoc/),
now supports the documentation of other source trees (you can browse and
-search your own code) and provides a [[https://golang.org/doc/codewalk/]["code walk"]]
+search your own code) and provides a ["code walk"](https://golang.org/doc/codewalk/)
interface for presenting tutorial materials (among many more improvements).
-[[https://golang.org/cmd/goinstall/][Goinstall]] ,
+[Goinstall](https://golang.org/cmd/goinstall/) ,
a new package management tool, allows users to install and update external
packages with a single command.
-[[https://golang.org/cmd/gofmt/][Gofmt]],
+[Gofmt](https://golang.org/cmd/gofmt/),
the Go pretty-printer, now makes syntactic simplifications where possible.
-[[https://golang.org/misc/goplay/][Goplay]],
+[Goplay](https://golang.org/misc/goplay/),
a web-based “compile-as-you-type” tool,
is a convenient way to experiment with Go for those times when you don’t
-have access to the [[https://golang.org/doc/play/][Go Playground]].
+have access to the [Go Playground](https://golang.org/doc/play/).
The standard library has grown by over 42,000 lines of code and includes
-20 new [[https://golang.org/pkg/][packages]].
-Among the additions are the [[https://golang.org/pkg/image/jpeg/][jpeg]],
-[[https://golang.org/pkg/rpc/jsonrpc/][jsonrpc]],
-[[https://golang.org/pkg/mime/][mime]], [[https://golang.org/pkg/netchan/][netchan]],
-and [[https://golang.org/pkg/smtp/][smtp]] packages,
-as well as a slew of new [[https://golang.org/pkg/crypto/][cryptography]] packages.
+20 new [packages](https://golang.org/pkg/).
+Among the additions are the [jpeg](https://golang.org/pkg/image/jpeg/),
+[jsonrpc](https://golang.org/pkg/rpc/jsonrpc/),
+[mime](https://golang.org/pkg/mime/), [netchan](https://golang.org/pkg/netchan/),
+and [smtp](https://golang.org/pkg/smtp/) packages,
+as well as a slew of new [cryptography](https://golang.org/pkg/crypto/) packages.
More generally, the standard library has been continuously refined and revised
as our understanding of Go’s idioms deepens.
@@ -70,29 +71,29 @@
Recent improvements to the DWARF output of the gc compilers make the GNU debugger,
GDB, useful for Go binaries, and we’re actively working on making that
debugging information more complete.
-(See the [[https://blog.golang.org/2010/11/debugging-go-code-status-report.html][ recent blog post]] for details.)
+(See the [ recent blog post](https://blog.golang.org/2010/11/debugging-go-code-status-report.html) for details.)
It’s now easier than ever to link against existing libraries written in
languages other than Go.
-Go support is in the most recent [[http://www.swig.org/][SWIG]] release,
+Go support is in the most recent [SWIG](http://www.swig.org/) release,
version 2.0.1, making it easier to link against C and C++ code,
-and our [[https://golang.org/cmd/cgo/][cgo]] tool has seen many fixes and improvements.
+and our [cgo](https://golang.org/cmd/cgo/) tool has seen many fixes and improvements.
-[[https://golang.org/doc/gccgo_install.html][Gccgo]],
+[Gccgo](https://golang.org/doc/gccgo_install.html),
the Go front end for the GNU C Compiler, has kept pace with the gc compiler
as a parallel Go implementation.
It now has a working garbage collector, and has been accepted into the GCC core.
-We’re now working toward making [[http://code.google.com/p/gofrontend/][gofrontend]]
+We’re now working toward making [gofrontend](http://code.google.com/p/gofrontend/)
available as a BSD-licensed Go compiler front end,
fully decoupled from GCC.
Outside the Go project itself Go is starting to be used to build real software.
-There are more than 200 Go programs and libraries listed on our [[http://godashboard.appspot.com/project][Project dashboard]],
-and hundreds more on [[http://code.google.com/hosting/search?q=label:Go][Google Code]]
-and [[https://github.com/search?q=language:Go][Github]].
+There are more than 200 Go programs and libraries listed on our [Project dashboard](http://godashboard.appspot.com/project),
+and hundreds more on [Google Code](http://code.google.com/hosting/search?q=label:Go)
+and [Github](https://github.com/search?q=language:Go).
On our mailing list and IRC channel you can find coders from around the
world who use Go for their programming projects.
-(See our [[https://blog.golang.org/2010/10/real-go-projects-smarttwitter-and-webgo.html][guest blog post]]
+(See our [guest blog post](https://blog.golang.org/2010/10/real-go-projects-smarttwitter-and-webgo.html)
from last month for a real-world example.) Internally at Google there are
several teams that choose Go for building production software,
and we have received reports from other companies that are developing sizable systems in Go.
@@ -105,30 +106,30 @@
Since the launch we have made a number of language changes,
many of which were driven by feedback from the community.
-- Semicolons are now optional in almost all instances. [[https://golang.org/doc/go_spec.html#Semicolons][spec]]
-- The new built-in functions `copy` and `append` make management of slices
- more efficient and straightforward.
- [[https://golang.org/doc/go_spec.html#Appending_and_copying_slices][spec]]
-- The upper and lower bounds may be omitted when making a sub-slice.
- This means that `s[:]` is shorthand for `s[0:len(s)]`.
- [[https://golang.org/doc/go_spec.html#Slices][spec]]
-- The new built-in function `recover` complements `panic` and `defer` as
- an error handling mechanism.
- [[https://blog.golang.org/2010/08/defer-panic-and-recover.html][blog]],
- [[https://golang.org/doc/go_spec.html#Handling_panics][spec]]
-- The new complex number types (`complex`,
- `complex64`, and `complex128`) simplify certain mathematical operations.
- [[https://golang.org/doc/go_spec.html#Complex_numbers][spec]],
- [[https://golang.org/doc/go_spec.html#Imaginary_literals][spec]]
-- The composite literal syntax permits the omission of redundant type information
- (when specifying two-dimensional arrays, for example).
- [[https://golang.org/doc/devel/release.html#2010-10-27][release.2010-10-27]],
- [[https://golang.org/doc/go_spec.html#Composite_literals][spec]]
-- A general syntax for variable function arguments (`...T`) and their propagation
- (`v...`) is now specified.
- [[https://golang.org/doc/go_spec.html#Function_Types][spec]],
- [[https://golang.org/doc/go_spec.html#Passing_arguments_to_..._parameters][ spec]],
- [[https://golang.org/doc/devel/release.html#2010-09-29][release.2010-09-29]]
+ - Semicolons are now optional in almost all instances. [spec](https://golang.org/doc/go_spec.html#Semicolons)
+ - The new built-in functions `copy` and `append` make management of slices
+ more efficient and straightforward.
+ [spec](https://golang.org/doc/go_spec.html#Appending_and_copying_slices)
+ - The upper and lower bounds may be omitted when making a sub-slice.
+ This means that `s[:]` is shorthand for `s[0:len(s)]`.
+ [spec](https://golang.org/doc/go_spec.html#Slices)
+ - The new built-in function `recover` complements `panic` and `defer` as
+ an error handling mechanism.
+ [blog](https://blog.golang.org/2010/08/defer-panic-and-recover.html),
+ [spec](https://golang.org/doc/go_spec.html#Handling_panics)
+ - The new complex number types (`complex`,
+ `complex64`, and `complex128`) simplify certain mathematical operations.
+ [spec](https://golang.org/doc/go_spec.html#Complex_numbers),
+ [spec](https://golang.org/doc/go_spec.html#Imaginary_literals)
+ - The composite literal syntax permits the omission of redundant type information
+ (when specifying two-dimensional arrays, for example).
+ [release.2010-10-27](https://golang.org/doc/devel/release.html#2010-10-27),
+ [spec](https://golang.org/doc/go_spec.html#Composite_literals)
+ - A general syntax for variable function arguments (`...T`) and their propagation
+ (`v...`) is now specified.
+ [spec](https://golang.org/doc/go_spec.html#Function_Types),
+ [ spec](https://golang.org/doc/go_spec.html#Passing_arguments_to_..._parameters),
+ [release.2010-09-29](https://golang.org/doc/devel/release.html#2010-09-29)
Go is certainly ready for production use,
but there is still room for improvement.
@@ -141,6 +142,6 @@
A lot has happened in a year; it’s been both thrilling and satisfying.
We hope that this coming year will be even more fruitful than the last.
-_If_you’ve_been_meaning_to_get_[back]_into_Go,_now_is_a_great_time_to_do_so!_Check_out_the_
-[[https://golang.org/doc/docs.html][_Documentation_]] _and_ [[https://golang.org/doc/install.html][_Getting_Started_]]
-_pages_for_more_information,_or_just_go_nuts_in_the_ [[https://golang.org/doc/play/][_Go_Playground_]].
+_If you’ve been meaning to get [back] into Go, now is a great time to do so! Check out the_
+[_Documentation_](https://golang.org/doc/docs.html) _and_ [_Getting Started_](https://golang.org/doc/install.html)
+_pages for more information, or just go nuts in the_ [_Go Playground_](https://golang.org/doc/play/).
diff --git a/content/go-programming-language-turns-two.article b/content/go-programming-language-turns-two.article
index 5b20144..3abba3b 100644
--- a/content/go-programming-language-turns-two.article
+++ b/content/go-programming-language-turns-two.article
@@ -1,10 +1,11 @@
-The Go Programming Language turns two
+# The Go Programming Language turns two
10 Nov 2011
Tags: appengine, community, gopher
+Summary: Two years ago a small team at Google went public with their fledgling project - the Go Programming Language. They presented a language spec, two compilers, a modest standard library, some novel tools, and plenty of accurate (albeit succinct) documentation. They watched with excitement as programmers around the world began to play with Go. The team continued to iterate and improve on what they had built, and were gradually joined by dozens - and then hundreds - of programmers from the open source community. The Go Authors went on to produce lots of libraries, new tools, and reams of [documentation](https://golang.org/doc/docs.html). They celebrated a successful year in the public eye with a [blog post](https://blog.golang.org/2010/11/go-one-year-ago-today.html) last November that concluded "Go is certainly ready for production use, but there is still room for improvement. Our focus for the immediate future is making Go programs faster and more efficient in the context of high performance systems."
Andrew Gerrand
-* Introduction
+##
Two years ago a small team at Google went public with their fledgling project -
the Go Programming Language.
@@ -16,8 +17,8 @@
and were gradually joined by dozens - and then hundreds - of programmers
from the open source community.
The Go Authors went on to produce lots of libraries,
-new tools, and reams of [[https://golang.org/doc/docs.html][documentation]].
-They celebrated a successful year in the public eye with a [[https://blog.golang.org/2010/11/go-one-year-ago-today.html][blog post]]
+new tools, and reams of [documentation](https://golang.org/doc/docs.html).
+They celebrated a successful year in the public eye with a [blog post](https://blog.golang.org/2010/11/go-one-year-ago-today.html)
last November that concluded "Go is certainly ready for production use,
but there is still room for improvement.
Our focus for the immediate future is making Go programs faster and more
@@ -27,35 +28,35 @@
and Go is faster and more stable than ever.
Careful tuning of Go's code generators, concurrency primitives,
garbage collector, and core libraries have increased the performance of Go programs,
-and native support for [[https://blog.golang.org/2011/06/profiling-go-programs.html][profiling]]
-and [[http://blog.golang.org/2011/10/debugging-go-programs-with-gnu-debugger.html][debugging]]
+and native support for [profiling](https://blog.golang.org/2011/06/profiling-go-programs.html)
+and [debugging](http://blog.golang.org/2011/10/debugging-go-programs-with-gnu-debugger.html)
makes it easier to detect and remove performance issues in user code.
-Go is also now easier to learn with [[http://tour.golang.org/][A Tour of Go]],
+Go is also now easier to learn with [A Tour of Go](http://tour.golang.org/),
an interactive tutorial you can take from the comfort of your web browser.
-This year we introduced the experimental [[http://code.google.com/appengine/docs/go/][Go runtime]]
+This year we introduced the experimental [Go runtime](http://code.google.com/appengine/docs/go/)
for Google's App Engine platform,
and we have been steadily increasing the Go runtime's support for App Engine's APIs.
-Just this week we released [[http://code.google.com/appengine/downloads.html][version 1.6.0]]
+Just this week we released [version 1.6.0](http://code.google.com/appengine/downloads.html)
of the Go App Engine SDK,
-which includes support for [[http://code.google.com/appengine/docs/go/backends/overview.html][backends]]
+which includes support for [backends](http://code.google.com/appengine/docs/go/backends/overview.html)
(long-running processes),
finer control over datastore indexes, and various other improvements.
Today, the Go runtime is near feature parity with - and is a viable alternative
to - the Python and Java runtimes.
-In fact, we now serve [[https://golang.org/][golang.org]] by running a version
-of [[https://golang.org/cmd/godoc/][godoc]] on the App Engine service.
+In fact, we now serve [golang.org](https://golang.org/) by running a version
+of [godoc](https://golang.org/cmd/godoc/) on the App Engine service.
While 2010 was a year of discovery and experimentation,
2011 was a year of fine tuning and planning for the future.
-This year we issued several "[[https://golang.org/doc/devel/release.html][release]]"
+This year we issued several "[release](https://golang.org/doc/devel/release.html)"
versions of Go that were more reliable and better supported than weekly snapshots.
-We also introduced [[https://golang.org/cmd/gofix/][gofix]] to take the
+We also introduced [gofix](https://golang.org/cmd/gofix/) to take the
pain out of migrating to newer releases.
-Furthermore, last month we announced a [[https://blog.golang.org/2011/10/preview-of-go-version-1.html][plan for Go version 1]] -
+Furthermore, last month we announced a [plan for Go version 1](https://blog.golang.org/2011/10/preview-of-go-version-1.html) -
a release that will be supported for years to come.
Work toward Go 1 is already underway and you can observe our progress by
-the latest weekly snapshot at [[http://weekly.golang.org/pkg/][weekly.golang.org]].
+the latest weekly snapshot at [weekly.golang.org](http://weekly.golang.org/pkg/).
The plan is to launch Go 1 in early 2012.
We hope to bring the Go App Engine runtime out of "experimental" status at the same time.
@@ -63,7 +64,7 @@
But that's not all. 2011 was an exciting year for the gopher, too.
He has manifested himself as a plush toy (a highly prized gift at Google
I/O and other Go talks) and in vinyl form (received by every attendee at
-OSCON and now available at the [[http://www.googlestore.com/Fun/Go+Gopher+Figurine.axd][Google Store]]).
+OSCON and now available at the [Google Store](http://www.googlestore.com/Fun/Go+Gopher+Figurine.axd)).
.image go-programming-language-turns-two_gophers.jpg
@@ -71,4 +72,4 @@
.image go-programming-language-turns-two_costume.jpg
-Photograph by [[https://plus.google.com/106640494112897458359/posts][Chris Nokleberg]].
+Photograph by [Chris Nokleberg](https://plus.google.com/106640494112897458359/posts).
diff --git a/content/go-programming-session-video-from.article b/content/go-programming-session-video-from.article
index 1b3e505..8f3799e 100644
--- a/content/go-programming-session-video-from.article
+++ b/content/go-programming-session-video-from.article
@@ -1,10 +1,11 @@
-Go Programming session video from Google I/O
+# Go Programming session video from Google I/O
6 Jun 2010
Tags: video, talk
+Summary: Below is the video of the talk given by Rob Pike and Russ Cox at Google I/O 2010.
Andrew Gerrand
-* Introduction
+##
Below is the video of the talk given by Rob Pike and Russ Cox at Google I/O 2010.
diff --git a/content/go-slices-usage-and-internals.article b/content/go-slices-usage-and-internals.article
index f200f54..1c37b7f 100644
--- a/content/go-slices-usage-and-internals.article
+++ b/content/go-slices-usage-and-internals.article
@@ -1,10 +1,11 @@
-Go Slices: usage and internals
+# Go Slices: usage and internals
5 Jan 2011
Tags: slice, technical
+Summary: Go's slice type provides a convenient and efficient means of working with sequences of typed data. Slices are analogous to arrays in other languages, but have some unusual properties. This article will look at what slices are and how they are used.
Andrew Gerrand
-* Introduction
+## Introduction
Go's slice type provides a convenient and efficient means of working with
sequences of typed data.
@@ -12,7 +13,7 @@
but have some unusual properties.
This article will look at what slices are and how they are used.
-* Arrays
+## Arrays
The slice type is an abstraction built on top of Go's array type,
and so to understand slices we must first understand arrays.
@@ -57,7 +58,7 @@
In both cases, the type of `b` is `[2]string`.
-* Slices
+## Slices
Arrays have their place, but they're a bit inflexible,
so you don't see them too often in Go code.
@@ -117,7 +118,7 @@
x := [3]string{"Лайка", "Белка", "Стрелка"}
s := x[:] // a slice referencing the storage of x
-* Slice internals
+## Slice internals
A slice is a descriptor of an array segment.
It consists of a pointer to the array, the length of the segment,
@@ -125,7 +126,7 @@
.image go-slices-usage-and-internals_slice-struct.png
-Our variable `s`, created earlier by `make([]byte,`5)`, is structured like this:
+Our variable `s`, created earlier by `make([]byte, 5)`, is structured like this:
.image go-slices-usage-and-internals_slice-1.png
@@ -165,7 +166,7 @@
just as when indexing outside the bounds of a slice or array.
Similarly, slices cannot be re-sliced below zero to access earlier elements in the array.
-* Growing slices (the copy and append functions)
+## Growing slices (the copy and append functions)
To increase the capacity of a slice one must create a new,
larger slice and copy the contents of the original slice into it.
@@ -265,7 +266,7 @@
return p
}
-* A possible "gotcha"
+## A possible "gotcha"
As mentioned earlier, re-slicing a slice doesn't make a copy of the underlying array.
The full array will be kept in memory until it is no longer referenced.
@@ -302,13 +303,13 @@
A more concise version of this function could be constructed by using `append`.
This is left as an exercise for the reader.
-* Further Reading
+## Further Reading
-[[https://golang.org/doc/effective_go.html][Effective Go]] contains an in-depth
-treatment of [[https://golang.org/doc/effective_go.html#slices][slices]]
-and [[https://golang.org/doc/effective_go.html#arrays][arrays]],
-and the Go [[https://golang.org/doc/go_spec.html][language specification]]
-defines [[https://golang.org/doc/go_spec.html#Slice_types][slices]] and
-their [[https://golang.org/doc/go_spec.html#Length_and_capacity][associated]]
-[[https://golang.org/doc/go_spec.html#Making_slices_maps_and_channels][helper]]
-[[https://golang.org/doc/go_spec.html#Appending_and_copying_slices][functions]].
+[Effective Go](https://golang.org/doc/effective_go.html) contains an in-depth
+treatment of [slices](https://golang.org/doc/effective_go.html#slices)
+and [arrays](https://golang.org/doc/effective_go.html#arrays),
+and the Go [language specification](https://golang.org/doc/go_spec.html)
+defines [slices](https://golang.org/doc/go_spec.html#Slice_types) and
+their [associated](https://golang.org/doc/go_spec.html#Length_and_capacity)
+[helper](https://golang.org/doc/go_spec.html#Making_slices_maps_and_channels)
+[functions](https://golang.org/doc/go_spec.html#Appending_and_copying_slices).
diff --git a/content/go-turns-three.article b/content/go-turns-three.article
index be3cd2f..53d15b9 100644
--- a/content/go-turns-three.article
+++ b/content/go-turns-three.article
@@ -1,13 +1,14 @@
-Go turns three
+# Go turns three
10 Nov 2012
Tags: community, birthday
+Summary: The Go open source project is [three years old today](http://google-opensource.blogspot.com/2009/11/hey-ho-lets-go.html).
Russ Cox
-* Introduction
+##
The Go open source project is
-[[http://google-opensource.blogspot.com/2009/11/hey-ho-lets-go.html][three years old today]].
+[three years old today](http://google-opensource.blogspot.com/2009/11/hey-ho-lets-go.html).
It's great to look at how far Go has come in those three years.
When we launched, Go was an idea backed by two implementations that worked on Linux and OS X.
@@ -16,26 +17,26 @@
Since the open source launch,
we've been joined by
-[[https://tip.golang.org/CONTRIBUTORS][hundreds of external contributors]],
+[hundreds of external contributors](https://tip.golang.org/CONTRIBUTORS),
who have extended and improved Go in myriad ways,
including writing a Windows port from scratch.
We added a package management system
-[[https://groups.google.com/d/msg/golang-nuts/8JFwR3ESjjI/cy7qZzN7Lw4J][goinstall]],
+[goinstall](https://groups.google.com/d/msg/golang-nuts/8JFwR3ESjjI/cy7qZzN7Lw4J),
which eventually became the
-[[https://golang.org/cmd/go/][go command]].
+[go command](https://golang.org/cmd/go/).
We also added
-[[https://blog.golang.org/2011/07/go-for-app-engine-is-now-generally.html][support for Go on App Engine]].
-Over the past year we've also given [[https://golang.org/doc/#talks][many talks]], created an [[http://tour.golang.org/][interactive introductory tour]]
-and recently we added support for [[https://golang.org/pkg/strings/#pkg-examples][executable examples in package documentation]].
+[support for Go on App Engine](https://blog.golang.org/2011/07/go-for-app-engine-is-now-generally.html).
+Over the past year we've also given [many talks](https://golang.org/doc/#talks), created an [interactive introductory tour](http://tour.golang.org/)
+and recently we added support for [executable examples in package documentation](https://golang.org/pkg/strings/#pkg-examples).
Perhaps the most important development in the past year
was the launch of the first stable version,
-[[https://blog.golang.org/2012/03/go-version-1-is-released.html][Go 1]].
+[Go 1](https://blog.golang.org/2012/03/go-version-1-is-released.html).
People who write Go 1 programs can now be confident that their programs will
continue to compile and run without change, in many environments,
on a time scale of years.
As part of the Go 1 launch we spent months cleaning up the
-[[https://golang.org/doc/go1.html][language and libraries]]
+[language and libraries](https://golang.org/doc/go1.html)
to make it something that will age well.
We're working now toward the release of Go 1.1 in 2013. There will be some
@@ -49,28 +50,28 @@
We use Go at Google in a variety of ways, many of them invisible to the outside world.
A few visible ones include
-[[https://groups.google.com/d/msg/golang-nuts/BNUNbKSypE0/E4qSfpx9qI8J][serving Chrome and other downloads]],
-[[http://code.google.com/p/vitess/][scaling MySQL database at YouTube]],
+[serving Chrome and other downloads](https://groups.google.com/d/msg/golang-nuts/BNUNbKSypE0/E4qSfpx9qI8J),
+[scaling MySQL database at YouTube](http://code.google.com/p/vitess/),
and of course running the
-[[https://golang.org/][Go home page]]
-on [[https://developers.google.com/appengine/docs/go/overview][App Engine]].
+[Go home page](https://golang.org/)
+on [App Engine](https://developers.google.com/appengine/docs/go/overview).
Last year's
-[[https://blog.golang.org/2011/12/from-zero-to-go-launching-on-google.html][Thanksgiving Doodle]]
+[Thanksgiving Doodle](https://blog.golang.org/2011/12/from-zero-to-go-launching-on-google.html)
and the recent
-[[http://www.jamwithchrome.com/technology][Jam with Chrome]]
+[Jam with Chrome](http://www.jamwithchrome.com/technology)
site are also served by Go programs.
Other companies and projects are using Go too, including
-[[http://www.quora.com/Go-programming-language/Is-Google-Go-ready-for-production-use/answer/Kunal-Anand][BBC Worldwide]],
-[[http://dave.cheney.net/wp-content/uploads/2012/08/august-go-meetup.pdf][Canonical]],
-[[http://blog.cloudflare.com/go-at-cloudflare][CloudFlare]],
-[[https://blog.golang.org/2011/04/go-at-heroku.html][Heroku]],
-[[https://plus.google.com/114945221884326152379/posts/d1SVaqkRyTL][Novartis]],
-[[http://backstage.soundcloud.com/2012/07/go-at-soundcloud/][SoundCloud]],
-[[http://sorcery.smugmug.com/2012/04/06/deriving-json-types-in-go/][SmugMug]],
-[[https://blog.golang.org/2011/12/building-stathat-with-go.html][StatHat]],
-[[https://tinkercad.com/about/jobs][Tinkercad]],
+[BBC Worldwide](http://www.quora.com/Go-programming-language/Is-Google-Go-ready-for-production-use/answer/Kunal-Anand),
+[Canonical](http://dave.cheney.net/wp-content/uploads/2012/08/august-go-meetup.pdf),
+[CloudFlare](http://blog.cloudflare.com/go-at-cloudflare),
+[Heroku](https://blog.golang.org/2011/04/go-at-heroku.html),
+[Novartis](https://plus.google.com/114945221884326152379/posts/d1SVaqkRyTL),
+[SoundCloud](http://backstage.soundcloud.com/2012/07/go-at-soundcloud/),
+[SmugMug](http://sorcery.smugmug.com/2012/04/06/deriving-json-types-in-go/),
+[StatHat](https://blog.golang.org/2011/12/building-stathat-with-go.html),
+[Tinkercad](https://tinkercad.com/about/jobs),
and
-[[https://golang.org/wiki/GoUsers][many others]].
+[many others](https://golang.org/wiki/GoUsers).
Here's to many more years of productive programming in Go.
diff --git a/content/go-updates-in-app-engine-171.article b/content/go-updates-in-app-engine-171.article
index c51a026..20f9de4 100644
--- a/content/go-updates-in-app-engine-171.article
+++ b/content/go-updates-in-app-engine-171.article
@@ -1,43 +1,44 @@
-Go updates in App Engine 1.7.1
+# Go updates in App Engine 1.7.1
22 Aug 2012
Tags: appengine, release
+Summary: This week we released version 1.7.1 of the App Engine SDK. It includes some significant updates specific to the App Engine runtime for Go.
Andrew Gerrand
-* Introduction
+##
This week we released version 1.7.1 of the App Engine SDK.
It includes some significant updates specific to the App Engine runtime for Go.
-The [[https://developers.google.com/appengine/docs/go/memcache/reference][memcache package]] has
-had some additions to its [[https://developers.google.com/appengine/docs/go/memcache/reference#Codec][Codec]] convenience type.
+The [memcache package](https://developers.google.com/appengine/docs/go/memcache/reference) has
+had some additions to its [Codec](https://developers.google.com/appengine/docs/go/memcache/reference#Codec) convenience type.
The SetMulti, AddMulti, CompareAndSwap, and CompareAndSwapMulti methods
-make it easier to store and update encoded data in the [[https://developers.google.com/appengine/docs/go/memcache/overview][Memcache Service]].
+make it easier to store and update encoded data in the [Memcache Service](https://developers.google.com/appengine/docs/go/memcache/overview).
-The [[https://developers.google.com/appengine/docs/go/tools/uploadingdata][bulkloader tool]] can
+The [bulkloader tool](https://developers.google.com/appengine/docs/go/tools/uploadingdata) can
now be used with Go apps,
allowing users to upload and download datastore records in bulk.
This is useful for backups and offline processing,
and a great help when migrating Python or Java apps to the Go runtime.
-The [[https://developers.google.com/appengine/docs/go/images/overview][Images Service]] is
+The [Images Service](https://developers.google.com/appengine/docs/go/images/overview) is
now available to Go users.
-The new [[https://developers.google.com/appengine/docs/go/images/reference][appengine/image package]] supports serving
+The new [appengine/image package](https://developers.google.com/appengine/docs/go/images/reference) supports serving
images directly from Blobstore and resizing or cropping those images on the fly.
Note that this is not the full image service as provided by the Python and Java SDKs,
-as much of the equivalent functionality is available in the [[https://golang.org/pkg/image/][standard Go image package]] and
-external packages such as [[http://code.google.com/p/graphics-go/][graphics-go]].
+as much of the equivalent functionality is available in the [standard Go image package](https://golang.org/pkg/image/) and
+external packages such as [graphics-go](http://code.google.com/p/graphics-go/).
-The new [[https://developers.google.com/appengine/docs/go/backends/runtime#RunInBackground][runtime.RunInBackground]] function
+The new [runtime.RunInBackground](https://developers.google.com/appengine/docs/go/backends/runtime#RunInBackground) function
allows backend requests to spawn a new request independent of the initial request.
These can run in the background as long as the backend stays alive.
Finally, we have filled in some missing functionality:
-the [[https://developers.google.com/appengine/docs/go/xmpp/reference][xmpp package]] now
+the [xmpp package](https://developers.google.com/appengine/docs/go/xmpp/reference) now
supports sending presence updates and chat invitations and retrieving the
presence state of another user,
-and the [[https://developers.google.com/appengine/docs/go/users/reference][user package]] supports
+and the [user package](https://developers.google.com/appengine/docs/go/users/reference) supports
authenticating clients with OAuth.
-You can grab the new SDK from the [[https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_for_Go][App Engine downloads page]] and
-browse the [[https://developers.google.com/appengine/docs/go][updated documentation]].
+You can grab the new SDK from the [App Engine downloads page](https://developers.google.com/appengine/downloads#Google_App_Engine_SDK_for_Go) and
+browse the [updated documentation](https://developers.google.com/appengine/docs/go).
diff --git a/content/go-version-1-is-released.article b/content/go-version-1-is-released.article
index 7267bf3..354db2d 100644
--- a/content/go-version-1-is-released.article
+++ b/content/go-version-1-is-released.article
@@ -1,10 +1,11 @@
-Go version 1 is released
+# Go version 1 is released
28 Mar 2012
Tags: release, go1
+Summary: Today marks a major milestone in the development of the Go programming language. We're announcing Go version 1, or Go 1 for short, which defines a language and a set of core libraries to provide a stable foundation for creating reliable products, projects, and publications.
Andrew Gerrand
-* Introduction
+##
.image go-version-1-is-released_gophermega.jpg
@@ -29,7 +30,7 @@
Code that compiles in Go 1 should, with few exceptions,
continue to compile and run throughout the lifetime of that version,
even as we issue updates and bug fixes such as Go version 1.1, 1.2, and so on.
-The [[https://golang.org/doc/go1compat.html][Go 1 compatibility document]]
+The [Go 1 compatibility document](https://golang.org/doc/go1compat.html)
explains the compatibility guidelines in more detail.
Go 1 is a representation of Go as it is used today,
@@ -40,28 +41,28 @@
but not released because they were backwards-incompatible.
Go 1 incorporates these changes, which provide significant improvements
to the language and libraries but sometimes introduce incompatibilities for old programs.
-Fortunately, the [[https://golang.org/cmd/go/#Run_go_tool_fix_on_packages][go fix]]
+Fortunately, the [go fix](https://golang.org/cmd/go/#Run_go_tool_fix_on_packages)
tool can automate much of the work needed to bring programs up to the Go 1 standard.
-Go 1 introduces changes to the language (such as new types for [[https://golang.org/doc/go1.html#rune][Unicode characters]]
-and [[https://golang.org/doc/go1.html#errors][errors]]) and the standard
-library (such as the new [[https://golang.org/doc/go1.html#time][time package]]
-and renamings in the [[https://golang.org/doc/go1.html#strconv][strconv package]]).
+Go 1 introduces changes to the language (such as new types for [Unicode characters](https://golang.org/doc/go1.html#rune)
+and [errors](https://golang.org/doc/go1.html#errors)) and the standard
+library (such as the new [time package](https://golang.org/doc/go1.html#time)
+and renamings in the [strconv package](https://golang.org/doc/go1.html#strconv)).
Also, the package hierarchy has been rearranged to group related items together,
such as moving the networking facilities,
-for instance the [[https://golang.org/pkg/net/rpc/][rpc package]],
+for instance the [rpc package](https://golang.org/pkg/net/rpc/),
into subdirectories of net.
-A complete list of changes is documented in the [[https://golang.org/doc/go1.html][Go 1 release notes]].
+A complete list of changes is documented in the [Go 1 release notes](https://golang.org/doc/go1.html).
That document is an essential reference for programmers migrating code from
earlier versions of Go.
-We also restructured the Go tool suite around the new [[https://golang.org/doc/go1.html#cmd_go][go command]],
+We also restructured the Go tool suite around the new [go command](https://golang.org/doc/go1.html#cmd_go),
a program for fetching, building, installing and maintaining Go code.
The go command eliminates the need for Makefiles to write Go code because
it uses the Go program source itself to derive the build instructions.
No more build scripts!
-Finally, the release of Go 1 triggers a new release of the [[https://developers.google.com/appengine/docs/go][Google App Engine SDK]].
+Finally, the release of Go 1 triggers a new release of the [Google App Engine SDK](https://developers.google.com/appengine/docs/go).
A similar process of revision and stabilization has been applied to the
App Engine libraries,
providing a base for developers to build programs for App Engine that will run for years.
@@ -71,4 +72,4 @@
We thank everyone who helped make this happen.
There has never been a better time to be a Go programmer.
-Everything you need to get started is at [[https://golang.org/][golang.org]].
+Everything you need to get started is at [golang.org](https://golang.org/).
diff --git a/content/go-videos-from-google-io-2012.article b/content/go-videos-from-google-io-2012.article
index e9c17f9..d42a55d 100644
--- a/content/go-videos-from-google-io-2012.article
+++ b/content/go-videos-from-google-io-2012.article
@@ -1,35 +1,36 @@
-Go videos from Google I/O 2012
+# Go videos from Google I/O 2012
2 Jul 2012
Tags: talk, video, concurrency, appengine, ethos
+Summary: Phew! Google I/O is over for another year, and what an event it was. Thanks to our guest speakers and everyone who attended the four Go sessions. It was a lot of fun.
Andrew Gerrand
-* Introduction
+## Introduction
Phew! Google I/O is over for another year, and what an event it was. Thanks to our guest speakers and everyone who attended the four Go sessions. It was a lot of fun.
Here are the session videos:
-*Go*concurrency*patterns* by Rob Pike
+**Go concurrency patterns** by Rob Pike
-_Concurrency_is_the_key_to_designing_high_performance_network_services._Go's_concurrency_primitives_(goroutines_and_channels)_provide_a_simple_and_efficient_means_of_expressing_concurrent_execution._In_this_talk_we_see_how_tricky_concurrency_problems_can_be_solved_gracefully_with_simple_Go_code._
+_Concurrency is the key to designing high performance network services. Go's concurrency primitives (goroutines and channels) provide a simple and efficient means of expressing concurrent execution. In this talk we see how tricky concurrency problems can be solved gracefully with simple Go code._
.iframe //www.youtube.com/embed/f6kdp27TYZs 304 540
-* Go in production
+## Go in production
-_Since_Go's_release_in_2009_many_companies_(besides_Google,_of_course)_have_used_the_language_to_build_cool_stuff._In_this_session_Gustavo_Niemeyer_(Canonical),_Keith_Rarick_(Heroku),_Evan_Shaw_(Iron.io),_and_Patrick_Crosby_(StatHat)_share_their_first-hand_experience_using_Go_in_production_environments._
+_Since Go's release in 2009 many companies (besides Google, of course) have used the language to build cool stuff. In this session Gustavo Niemeyer (Canonical), Keith Rarick (Heroku), Evan Shaw (Iron.io), and Patrick Crosby (StatHat) share their first-hand experience using Go in production environments._
.iframe //www.youtube.com/embed/kKQLhGZVN4A 304 540
-* Meet the Go team
+## Meet the Go team
-_A_panel_discussion_with_David_Symonds,_Robert_Griesemer,_Rob_Pike,_Ken_Thompson,_Andrew_Gerrand,_and_Brad_Fitzpatrick._
+_A panel discussion with David Symonds, Robert Griesemer, Rob Pike, Ken Thompson, Andrew Gerrand, and Brad Fitzpatrick._
.iframe //www.youtube.com/embed/sln-gJaURzk 304 540
-*Computing*Map*Tiles*with*Go*on*App*Engine* by Chris Broadfoot and Andrew Gerrand
+**Computing Map Tiles with Go on App Engine** by Chris Broadfoot and Andrew Gerrand
-_In_this_talk_we_use_the_Maps_API_and_Go_on_App_Engine_to_build_an_app_to_build_custom_tile_sets_for_Google_Maps._The_app_demonstrates_using_Go's_suitability_for_computation_in_the_cloud_and_App_Engine's_key_scalability_features,_such_as_Task_Queues_and_Backends._
+_In this talk we use the Maps API and Go on App Engine to build an app to build custom tile sets for Google Maps. The app demonstrates using Go's suitability for computation in the cloud and App Engine's key scalability features, such as Task Queues and Backends._
.iframe //www.youtube.com/embed/sPagpg0b7no 304 540
diff --git a/content/go-whats-new-in-march-2010.article b/content/go-whats-new-in-march-2010.article
index ad019e5..1de4c7d 100644
--- a/content/go-whats-new-in-march-2010.article
+++ b/content/go-whats-new-in-march-2010.article
@@ -1,9 +1,10 @@
-Go: What's New in March 2010
+# Go: What's New in March 2010
18 Mar 2010
+Summary: Welcome to the official Go Blog. We, the Go team, hope to use this blog to keep the world up-to-date on the development of the Go programming language and the growing ecosystem of libraries and applications surrounding it.
Andrew Gerrand
-* Introduction
+##
Welcome to the official Go Blog. We, the Go team,
hope to use this blog to keep the world up-to-date on the development of
@@ -16,47 +17,47 @@
compilers, packages, tools, and documentation.
The compilers now produce code that is in some cases between 2x and an order
of magnitude faster than at release.
-We have put together some graphs of a selection of [[http://godashboard.appspot.com/benchmarks][Benchmarks]],
-and the [[http://godashboard.appspot.com/][Build Status]] page tracks the
+We have put together some graphs of a selection of [Benchmarks](http://godashboard.appspot.com/benchmarks),
+and the [Build Status](http://godashboard.appspot.com/) page tracks the
reliability of each changeset submitted to the repository.
We have made syntax changes to make the language more concise,
regular, and flexible.
-Semicolons have been [[http://groups.google.com/group/golang-nuts/t/5ee32b588d10f2e9][almost entirely removed]] from the language.
-The [[https://golang.org/doc/go_spec.html#Function_types][...T syntax]]
+Semicolons have been [almost entirely removed](http://groups.google.com/group/golang-nuts/t/5ee32b588d10f2e9) from the language.
+The [...T syntax](https://golang.org/doc/go_spec.html#Function_types)
makes it simpler to handle an arbitrary number of typed function parameters.
The syntax x[lo:] is now shorthand for x[lo:len(x)].
Go also now natively supports complex numbers.
-See the [[https://golang.org/doc/devel/release.html][release notes]] for more.
+See the [release notes](https://golang.org/doc/devel/release.html) for more.
-[[https://golang.org/cmd/godoc/][Godoc]] now provides better support for
+[Godoc](https://golang.org/cmd/godoc/) now provides better support for
third-party libraries,
-and a new tool - [[https://golang.org/cmd/goinstall][goinstall]] - has been
+and a new tool - [goinstall](https://golang.org/cmd/goinstall) - has been
released to make it easy to install them.
Additionally, we've started working on a package tracking system to make
it easier to find what you need.
-You can view the beginnings of this on the [[http://godashboard.appspot.com/package][Packages page]].
+You can view the beginnings of this on the [Packages page](http://godashboard.appspot.com/package).
-More than 40,000 lines of code have been added to [[https://golang.org/pkg/][the standard library]],
+More than 40,000 lines of code have been added to [the standard library](https://golang.org/pkg/),
including many entirely new packages, a sizable portion written by external contributors.
Speaking of third parties, since launch a vibrant community has flourished
-on our [[http://groups.google.com/group/golang-nuts/][mailing list]] and
+on our [mailing list](http://groups.google.com/group/golang-nuts/) and
irc channel (#go-nuts on freenode).
-We have officially added [[https://golang.org/CONTRIBUTORS][more than 50 people]] to the project.
+We have officially added [more than 50 people](https://golang.org/CONTRIBUTORS) to the project.
Their contributions range from bug fixes and documentation corrections to
core packages and support for additional operating systems (Go is now supported under FreeBSD,
-and a [[http://code.google.com/p/go/wiki/WindowsPort][Windows port]] is underway).
+and a [Windows port](http://code.google.com/p/go/wiki/WindowsPort) is underway).
We regard these community contributions our greatest success so far.
-We've received some good reviews, too. This [[http://www.pcworld.idg.com.au/article/337773/google_go_captures_developers_imaginations/][recent article in PC World]]
+We've received some good reviews, too. This [recent article in PC World](http://www.pcworld.idg.com.au/article/337773/google_go_captures_developers_imaginations/)
summarized the enthusiasm surrounding the project.
Several bloggers have begun documenting their experiences in the language
-(see [[http://golang.tumblr.com/][here]],
-[[http://www.infi.nl/blog/view/id/47][here]],
-and [[http://freecella.blogspot.com/2010/01/gospecify-basic-setup-of-projects.html][here]]
+(see [here](http://golang.tumblr.com/),
+[here](http://www.infi.nl/blog/view/id/47),
+and [here](http://freecella.blogspot.com/2010/01/gospecify-basic-setup-of-projects.html)
for example) The general reaction of our users has been very positive;
-one first-timer remarked [[https://groups.google.com/group/golang-nuts/browse_thread/thread/5fabdd59f8562ed2]["I came away extremely impressed. Go walks an elegant line between simplicity and power."]]
+one first-timer remarked ["I came away extremely impressed. Go walks an elegant line between simplicity and power."](https://groups.google.com/group/golang-nuts/browse_thread/thread/5fabdd59f8562ed2)
As to the future: we have listened to the myriad voices telling us what they need,
and are now focused on getting Go ready for the prime time.
diff --git a/content/go-wins-2010-bossie-award.article b/content/go-wins-2010-bossie-award.article
index fa79e54..0ca4067 100644
--- a/content/go-wins-2010-bossie-award.article
+++ b/content/go-wins-2010-bossie-award.article
@@ -1,13 +1,14 @@
-Go Wins 2010 Bossie Award
+# Go Wins 2010 Bossie Award
6 Sep 2010
+Summary: The Go project has been awarded a [Bossie Award](http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-application-development-software-140¤t=2&last=1) for "best open source application development software." The [Bossie Awards](http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-software-the-year-115) have been given each year since 2007 by [InfoWorld](http://infoworld.com/) to recognize the best Open Source projects. Their citation reads:
Andrew Gerrand
-* Introduction
+##
-The Go project has been awarded a [[http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-application-development-software-140¤t=2&last=1][Bossie Award]]
-for "best open source application development software." The [[http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-software-the-year-115][Bossie Awards]]
-have been given each year since 2007 by [[http://infoworld.com/][InfoWorld]]
+The Go project has been awarded a [Bossie Award](http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-application-development-software-140¤t=2&last=1)
+for "best open source application development software." The [Bossie Awards](http://www.infoworld.com/d/open-source/bossie-awards-2010-the-best-open-source-software-the-year-115)
+have been given each year since 2007 by [InfoWorld](http://infoworld.com/)
to recognize the best Open Source projects.
Their citation reads:
diff --git a/content/go.dev.article b/content/go.dev.article
index 8dc0cd1..3e5d1fd 100644
--- a/content/go.dev.article
+++ b/content/go.dev.article
@@ -1,10 +1,11 @@
-Go.dev: a new hub for Go developers
+# Go.dev: a new hub for Go developers
13 Nov 2019
+Summary: Over the last two years, as we’ve spoken with users at companies of all sizes, we’ve heard three questions repeatedly: who else is using Go, what do they use it for, and how can I find useful Go packages?
Steve Francia and Julie Qiu
julieqiu@golang.org
-* Introduction
+##
Over the last two years,
as we’ve spoken with users at companies of all sizes,
@@ -13,26 +14,26 @@
what do they use it for,
and how can I find useful Go packages?
-Today we are launching [[https://go.dev][go.dev]], a new hub for Go developers,
+Today we are launching [go.dev](https://go.dev), a new hub for Go developers,
to help answer those questions.
There you will find a wealth of learning resources to get started with the language,
featured use cases, and case studies of companies using Go.
.image go.dev/home.png _ 850
-(Note that [[https://golang.org/][golang.org]] is still the home for the
+(Note that [golang.org](https://golang.org/) is still the home for the
open source Go project and the Go distribution.
Go.dev is a companion site to provide these supporting resources.)
-Clicking on Explore brings you to [[https://pkg.go.dev/][pkg.go.dev]],
+Clicking on Explore brings you to [pkg.go.dev](https://pkg.go.dev/),
a central source of information about Go packages and modules.
-Like [[https://godoc.org/][godoc.org]], pkg.go.dev serves Go documentation.
+Like [godoc.org](https://godoc.org/), pkg.go.dev serves Go documentation.
However, it also understands modules and has information
about all versions of a package, including
-[[https://pkg.go.dev/std?tab=versions][all releases of the standard library]]!
+[all releases of the standard library](https://pkg.go.dev/std?tab=versions)!
And it detects and displays licenses and has a better search algorithm.
You can follow
-[[https://golang.org/issue/33654][Go issue 33654]] for future developments.
+[Go issue 33654](https://golang.org/issue/33654) for future developments.
.image go.dev/http.png _ 850
@@ -42,4 +43,4 @@
If you have any ideas, suggestions or issues,
please let us know via the “Share Feedback” and “Report an Issue” links at the bottom of every page.
Or you can send your bugs, ideas, feature requests, and questions to
-[[mailto:go-discovery-feedback@google.com][go-discovery-feedback@google.com]].
+[go-discovery-feedback@google.com](mailto:go-discovery-feedback@google.com).
diff --git a/content/go1.10.article b/content/go1.10.article
index 8bcf044..e0e9ce0 100644
--- a/content/go1.10.article
+++ b/content/go1.10.article
@@ -1,34 +1,35 @@
-Go 1.10 is released
+# Go 1.10 is released
16 Feb 2018
+Summary: Happy Friday, happy weekend! Today the Go team is happy to announce the release of Go 1.10. You can get it from the [download page](https://golang.org/dl/).
Brad Fitzpatrick
bradfitz@golang.org
-* Introduction
+##
Happy Friday, happy weekend! Today the Go team is happy to announce the release of Go 1.10.
-You can get it from the [[https://golang.org/dl/][download page]].
+You can get it from the [download page](https://golang.org/dl/).
-See the [[https://golang.org/doc/go1.10][Go 1.10 release notes]] for all the details.
+See the [Go 1.10 release notes](https://golang.org/doc/go1.10) for all the details.
The most exciting part of this release for many people will probably
be that the `go` tool now does
-[[https://golang.org/doc/go1.10#build][automatic caching of build & test results]].
-Of course, one of the hundreds of smaller changes may be *your* favorite.
+[automatic caching of build & test results](https://golang.org/doc/go1.10#build).
+Of course, one of the hundreds of smaller changes may be **your** favorite.
To celebrate the release, Go User Groups around the world are holding
-[[https://github.com/golang/go/wiki/Go-1.10-Release-Party][release parties]].
+[release parties](https://github.com/golang/go/wiki/Go-1.10-Release-Party).
See if there's one in your area, or feel free to organize one!
Thanks to everyone who contributed to this release and everyone who
helped test the Go 1.10 betas and release candidates to ensure a perfect,
bug-free final release. However, if you do notice any bugs or unexpected
changes not noted in the release notes, be sure to
-[[https://golang.org/issues/new][file a bug]].
+[file a bug](https://golang.org/issues/new).
Enjoy the weekend, and enjoy the new release!
P.S. Many of this year's Go conferences are accepting talk proposals
this month. We always love to see new speakers and encourage you to
think about proposing a talk. For more information, see
-[[https://golang.org/wiki/NewSpeakers][golang.org/wiki/NewSpeakers]].
+[golang.org/wiki/NewSpeakers](https://golang.org/wiki/NewSpeakers).
diff --git a/content/go1.11.article b/content/go1.11.article
index 558d7cf..e9af576 100644
--- a/content/go1.11.article
+++ b/content/go1.11.article
@@ -1,38 +1,39 @@
-Go 1.11 is released
+# Go 1.11 is released
24 Aug 2018
+Summary: Who says releasing on Friday is a bad idea?
Andrew Bonventre
andybons@golang.org
-* Introduction
+##
Who says releasing on Friday is a bad idea?
Today the Go team is happy to announce the release of Go 1.11.
-You can get it from the [[https://golang.org/dl/][download page]].
+You can get it from the [download page](https://golang.org/dl/).
There are many changes and improvements to the toolchain,
runtime, and libraries, but two features stand out as being especially exciting:
modules and WebAssembly support.
-This release adds preliminary support for a [[https://golang.org/doc/go1.11#modules][new concept called “modules,”]]
+This release adds preliminary support for a [new concept called “modules,”](https://golang.org/doc/go1.11#modules)
an alternative to GOPATH with integrated support for versioning and package distribution.
Module support is considered experimental,
and there are still a few rough edges to smooth out,
-so please make liberal use of the [[https://golang.org/issue/new][issue tracker]].
+so please make liberal use of the [issue tracker](https://golang.org/issue/new).
-Go 1.11 also adds an experimental port to [[https://golang.org/doc/go1.11#wasm][WebAssembly]] (`js/wasm`).
+Go 1.11 also adds an experimental port to [WebAssembly](https://golang.org/doc/go1.11#wasm) (`js/wasm`).
This allows programmers to compile Go programs to a binary format compatible with four major web browsers.
-You can read more about WebAssembly (abbreviated “Wasm”) at [[https://webassembly.org/][webassembly.org]]
-and see [[https://golang.org/wiki/WebAssembly][this wiki page]] on how to
+You can read more about WebAssembly (abbreviated “Wasm”) at [webassembly.org](https://webassembly.org/)
+and see [this wiki page](https://golang.org/wiki/WebAssembly) on how to
get started with using Wasm with Go.
-Special thanks to [[https://github.com/neelance][Richard Musiol]] for contributing the WebAssembly port!
+Special thanks to [Richard Musiol](https://github.com/neelance) for contributing the WebAssembly port!
We also want to thank everyone who contributed to this release by writing code,
filing bugs, providing feedback, and/or testing the betas and release candidates.
Your contributions and diligence helped to ensure that Go 1.11 is as bug-free as possible.
-That said, if you do notice any problems, please [[https://golang.org/issues/new][file an issue]].
+That said, if you do notice any problems, please [file an issue](https://golang.org/issues/new).
-For more detail about the changes in Go 1.11, see the [[https://golang.org/doc/go1.11][release notes]].
+For more detail about the changes in Go 1.11, see the [release notes](https://golang.org/doc/go1.11).
Have a wonderful weekend and enjoy the release!
diff --git a/content/go1.12.article b/content/go1.12.article
index 70e45ed..549c25e 100644
--- a/content/go1.12.article
+++ b/content/go1.12.article
@@ -1,20 +1,21 @@
-Go 1.12 is released
+# Go 1.12 is released
25 Feb 2019
+Summary: Today the Go team is happy to announce the release of Go 1.12. You can get it from the [download page](https://golang.org/dl/).
Andrew Bonventre
andybons@golang.org
-* Introduction
+##
Today the Go team is happy to announce the release of Go 1.12.
-You can get it from the [[https://golang.org/dl/][download page]].
+You can get it from the [download page](https://golang.org/dl/).
-For details about the changes in Go 1.12, see the [[https://golang.org/doc/go1.12][*Go*1.12*release*notes*]].
+For details about the changes in Go 1.12, see the [**Go 1.12 release notes**](https://golang.org/doc/go1.12).
-Some of the highlights include [[https://golang.org/doc/go1.12#tls_1_3][opt-in support for TLS 1.3]], [[https://golang.org/doc/go1.12#modules][improved modules support]] (in preparation [[/modules2019][for being the default in Go 1.13]]), support for `windows/arm`, and [[https://golang.org/doc/go1.12#darwin][improved macOS & iOS forwards compatibility.]]
+Some of the highlights include [opt-in support for TLS 1.3](https://golang.org/doc/go1.12#tls_1_3), [improved modules support](https://golang.org/doc/go1.12#modules) (in preparation [for being the default in Go 1.13](/modules2019)), support for `windows/arm`, and [improved macOS & iOS forwards compatibility.](https://golang.org/doc/go1.12#darwin)
As always, we also want to thank everyone who contributed to this release by writing code, filing bugs, providing feedback, and/or testing the betas and release candidates.
Your contributions and diligence helped to ensure that Go 1.12 is as stable as possible.
-That said, if you do notice any problems, please [[https://golang.org/issues/new][file an issue]].
+That said, if you do notice any problems, please [file an issue](https://golang.org/issues/new).
Enjoy the new release!
diff --git a/content/go1.13-errors.article b/content/go1.13-errors.article
index a3aa755..9935d06 100644
--- a/content/go1.13-errors.article
+++ b/content/go1.13-errors.article
@@ -1,12 +1,13 @@
-Working with Errors in Go 1.13
+# Working with Errors in Go 1.13
17 Oct 2019
Tags: errors, technical
+Summary: Go’s treatment of [errors as values](https://blog.golang.org/errors-are-values) has served us well over the last decade. Although the standard library’s support for errors has been minimal—just the `errors.New` and `fmt.Errorf` functions, which produce errors that contain only a message—the built-in `error` interface allows Go programmers to add whatever information they desire. All it requires is a type that implements an `Error` method:
Damien Neil and Jonathan Amsterdam
-* Introduction
+## Introduction
-Go’s treatment of [[https://blog.golang.org/errors-are-values][errors as values]]
+Go’s treatment of [errors as values](https://blog.golang.org/errors-are-values)
has served us well over the last decade. Although the standard library’s support
for errors has been minimal—just the `errors.New` and `fmt.Errorf` functions,
which produce errors that contain only a message—the built-in `error` interface
@@ -25,7 +26,7 @@
information includes another, lower-level error to provide additional context.
The pattern of one error containing another is so pervasive in Go code that,
-after [[https://golang.org/issue/29934][extensive discussion]], Go 1.13 added
+after [extensive discussion](https://golang.org/issue/29934), Go 1.13 added
explicit support for it. This post describes the additions to the standard
library that provide that support: three new functions in the `errors` package,
and a new formatting verb for `fmt.Errorf`.
@@ -33,9 +34,9 @@
Before describing the changes in detail, let's review how errors are examined
and constructed in previous versions of the language.
-* Errors before Go 1.13
+## Errors before Go 1.13
-** Examining errors
+### Examining errors
Go errors are values. Programs make decisions based on those values in a few
ways. The most common is to compare an error to `nil` to see if an operation
@@ -67,7 +68,7 @@
// e.Name wasn't found
}
-** Adding information
+### Adding information
Frequently a function passes an error up the call stack while adding information
to it, like a brief description of what was happening when the error occurred. A
@@ -98,9 +99,9 @@
The `os.PathError` type in the standard library is another example of one error which contains another.
-* Errors in Go 1.13
+## Errors in Go 1.13
-** The Unwrap method
+### The Unwrap method
Go 1.13 introduces new features to the `errors` and `fmt` standard library
packages to simplify working with errors that contain other errors. The most
@@ -115,9 +116,9 @@
func (e *QueryError) Unwrap() error { return e.Err }
The result of unwrapping an error may itself have an `Unwrap` method; we call
-the sequence of errors produced by repeated unwrapping the _error_chain_.
+the sequence of errors produced by repeated unwrapping the _error chain_.
-** Examining errors with Is and As
+### Examining errors with Is and As
The Go 1.13 `errors` package includes two new functions for examining errors: `Is` and `As`.
@@ -159,7 +160,7 @@
`Unwrap` method. It is usually better to use `errors.Is` or `errors.As`,
however, since these functions will examine the entire chain in a single call.
-** Wrapping errors with %w
+### Wrapping errors with %w
As mentioned earlier, it is common to use the `fmt.Errorf` function to add additional information to an error.
@@ -183,7 +184,7 @@
...
if errors.Is(err, ErrPermission) ...
-** Whether to Wrap
+### Whether to Wrap
When adding additional context to an error, either with `fmt.Errorf` or by
implementing a custom type, you need to decide whether the new error should wrap
@@ -204,9 +205,9 @@
errors is a violation of abstraction. For example, if the `LookupUser` function
of your package `pkg` uses Go's `database/sql` package, then it may encounter a
`sql.ErrNoRows` error. If you return that error with
-`fmt.Errorf("accessing`DB:`%v",`err)`
+`fmt.Errorf("accessing DB: %v", err)`
then a caller cannot look inside to find the `sql.ErrNoRows`. But if
-the function instead returns `fmt.Errorf("accessing`DB:`%w",`err)`, then a
+the function instead returns `fmt.Errorf("accessing DB: %w", err)`, then a
caller could reasonably write
err := pkg.LookupUser(...)
@@ -224,7 +225,7 @@
information so they can make more informed decisions, or to withhold that
information to preserve an abstraction layer.
-* Customizing error tests with Is and As methods
+## Customizing error tests with Is and As methods
The `errors.Is` function examines each error in a chain for a match with a
target value. By default, an error matches the target if the two are equal. In
@@ -232,7 +233,7 @@
implementing an `Is` _method_.
As an example, consider this error inspired by the
-[[https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html][Upspin error package]]
+[Upspin error package](https://commandcenter.blogspot.com/2017/12/error-handling-in-upspin.html)
which compares an error against a template, considering only fields which are
non-zero in the template:
@@ -256,7 +257,7 @@
The `errors.As` function similarly consults an `As` method when present.
-* Errors and package APIs
+## Errors and package APIs
A package which returns errors (and most do) should describe what properties of
those errors programmers may rely on. A well-designed package will also avoid
@@ -326,7 +327,7 @@
// ...
}
-* Conclusion
+## Conclusion
Although the changes we’ve discussed amount to just three functions and a
formatting verb, we hope they will go a long way toward improving how errors are
@@ -334,6 +335,6 @@
will become commonplace, helping programs to make better decisions and helping
programmers to find bugs more quickly.
-As Russ Cox said in his [[https://blog.golang.org/experiment][GopherCon 2019 keynote]],
+As Russ Cox said in his [GopherCon 2019 keynote](https://blog.golang.org/experiment),
on the path to Go 2 we experiment, simplify and ship. Now that we’ve
shipped these changes, we look forward to the experiments that will follow.
diff --git a/content/go1.13.article b/content/go1.13.article
index 231dda2..1e7f56b 100644
--- a/content/go1.13.article
+++ b/content/go1.13.article
@@ -1,24 +1,25 @@
-Go 1.13 is released
-03 Sep 2019
+# Go 1.13 is released
+3 Sep 2019
+Summary: Today the Go team is very happy to announce the release of Go 1.13. You can get it from the [download page](https://golang.org/dl).
Andrew Bonventre
-* Introduction
+##
-Today the Go team is very happy to announce the release of Go 1.13. You can get it from the [[https://golang.org/dl][download page]].
+Today the Go team is very happy to announce the release of Go 1.13. You can get it from the [download page](https://golang.org/dl).
Some of the highlights include:
-- The `go` command now downloads and authenticates modules [[https://golang.org/doc/go1.13#introduction][using the Go module mirror and Go checksum database by default]]
-- [[https://golang.org/doc/go1.13#language][Improvements to number literals]]
-- [[https://golang.org/doc/go1.13#error_wrapping][Error wrapping]]
-- [[https://golang.org/doc/go1.13#tls_1_3][TLS 1.3 on by default]]
-- [[https://golang.org/doc/go1.13#modules][Improved modules support]]
+ - The `go` command now downloads and authenticates modules [using the Go module mirror and Go checksum database by default](https://golang.org/doc/go1.13#introduction)
+ - [Improvements to number literals](https://golang.org/doc/go1.13#language)
+ - [Error wrapping](https://golang.org/doc/go1.13#error_wrapping)
+ - [TLS 1.3 on by default](https://golang.org/doc/go1.13#tls_1_3)
+ - [Improved modules support](https://golang.org/doc/go1.13#modules)
-For the complete list of changes and more information about the improvements above, see the [[https://golang.org/doc/go1.13][*Go*1.13*release*notes*]].
+For the complete list of changes and more information about the improvements above, see the [**Go 1.13 release notes**](https://golang.org/doc/go1.13).
We want to thank everyone who contributed to this release by writing code, filing bugs, providing feedback, and/or testing the beta and release candidates.
Your contributions and diligence helped to ensure that Go 1.13 is as stable as possible.
-That said, if you notice any problems, please [[https://golang.org/issue/new][file an issue]].
+That said, if you notice any problems, please [file an issue](https://golang.org/issue/new).
We hope you enjoy the new release!
diff --git a/content/go1.14.article b/content/go1.14.article
index 1e5f448..93c28c1 100644
--- a/content/go1.14.article
+++ b/content/go1.14.article
@@ -1,25 +1,26 @@
-Go 1.14 is released
+# Go 1.14 is released
25 Feb 2020
+Summary: Today the Go team is very happy to announce the release of Go 1.14. You can get it from the [download page](https://golang.org/dl).
Alex Rakoczy
-* Introduction
+##
-Today the Go team is very happy to announce the release of Go 1.14. You can get it from the [[https://golang.org/dl][download page]].
+Today the Go team is very happy to announce the release of Go 1.14. You can get it from the [download page](https://golang.org/dl).
Some of the highlights include:
-- Module support in the `go` command is now ready for production use. We encourage all users to [[https://golang.org/doc/go1.14#introduction][migrate to `go` modules for dependency management]].
-- [[https://golang.org/doc/go1.14#language][Embedding interfaces with overlapping method sets]]
-- [[https://golang.org/doc/go1.14#runtime][Improved defer performance]]
-- [[https://golang.org/doc/go1.14#runtime][Goroutines are asynchronously preemptible]]
-- [[https://golang.org/doc/go1.14#runtime][The page allocator is more efficient]]
-- [[https://golang.org/doc/go1.14#runtime][Internal timers are more efficient]]
+ - Module support in the `go` command is now ready for production use. We encourage all users to [migrate to `go` modules for dependency management](https://golang.org/doc/go1.14#introduction).
+ - [Embedding interfaces with overlapping method sets](https://golang.org/doc/go1.14#language)
+ - [Improved defer performance](https://golang.org/doc/go1.14#runtime)
+ - [Goroutines are asynchronously preemptible](https://golang.org/doc/go1.14#runtime)
+ - [The page allocator is more efficient](https://golang.org/doc/go1.14#runtime)
+ - [Internal timers are more efficient](https://golang.org/doc/go1.14#runtime)
-For the complete list of changes and more information about the improvements above, see the [[https://golang.org/doc/go1.14][*Go*1.14*release*notes*]].
+For the complete list of changes and more information about the improvements above, see the [**Go 1.14 release notes**](https://golang.org/doc/go1.14).
We want to thank everyone who contributed to this release by writing code, filing bugs, providing feedback, and/or testing the beta and release candidate.
Your contributions and diligence helped to ensure that Go 1.14 is as stable as possible.
-That said, if you notice any problems, please [[https://golang.org/issue/new][file an issue]].
+That said, if you notice any problems, please [file an issue](https://golang.org/issue/new).
We hope you enjoy the new release!
diff --git a/content/go1.15-proposals.article b/content/go1.15-proposals.article
index 367bc7b..288e648 100644
--- a/content/go1.15-proposals.article
+++ b/content/go1.15-proposals.article
@@ -1,15 +1,16 @@
-Proposals for Go 1.15
+# Proposals for Go 1.15
28 Jan 2020
Tags: go1.15, proposals, community, language, vet
+Summary: We are close to the Go 1.14 release, planned for February assuming all goes well, with an RC1 candidate almost ready. Per the process outlined in the [Go 2, here we come!](https://blog.golang.org/go2-here-we-come) blog post, it is again the time in our development and release cycle to consider if and what language or library changes we might want to include for our next release, Go 1.15, scheduled for August of this year.
Robert Griesemer, for the Go team
gri@golang.org
-* Status
+## Status
We are close to the Go 1.14 release, planned for February assuming all goes
well, with an RC1 candidate almost ready. Per the process outlined in the
-[[https://blog.golang.org/go2-here-we-come][Go 2, here we come!]] blog post,
+[Go 2, here we come!](https://blog.golang.org/go2-here-we-come) blog post,
it is again the time in our development and release cycle to consider if and
what language or library changes we might want to include for our next release,
Go 1.15, scheduled for August of this year.
@@ -19,7 +20,7 @@
better with each day, and we are also making progress on the generics front
(more on that later this year). Our attempt seven months ago at providing a
better error handling mechanism, the
-[[https://golang.org/issue/32437][`try` proposal]], met good support
+[`try` proposal](https://golang.org/issue/32437), met good support
but also strong opposition and we decided to abandon it. In its aftermath there
were many follow-up proposals, but none of them seemed convincing enough,
clearly superior to the `try` proposal, or less likely to cause similar
@@ -27,7 +28,7 @@
for now. Perhaps some future insight will help us to improve upon the status
quo.
-* Proposals
+## Proposals
Given that modules and generics are actively being worked on, and with error
handling changes out of the way for the time being, what other changes should
@@ -42,19 +43,19 @@
we concentrate on a couple of new `vet` checks and a minor adjustment to the
language. We have selected the following three proposals:
-[[https://golang.org/issue/32479][#32479]].
-Diagnose `string(int)` conversion in `go`vet`.
+[\#32479](https://golang.org/issue/32479).
+Diagnose `string(int)` conversion in `go vet`.
We were planning to get this done for the upcoming Go 1.14 release but we didn’t
get around to it, so here it is again. The `string(int)` conversion was introduced
early in Go for convenience, but it is confusing to newcomers (`string(10)` is
`"\n"` not `"10"`) and not justified anymore now that the conversion is available
in the `unicode/utf8` package.
-Since [[https://golang.org/issue/3939][removing this conversion]] is
+Since [removing this conversion](https://golang.org/issue/3939) is
not a backwards-compatible change, we propose to start with a `vet` error instead.
-[[https://golang.org/issue/4483][#4483]].
-Diagnose impossible interface-interface type assertions in `go`vet`.
+[\#4483](https://golang.org/issue/4483).
+Diagnose impossible interface-interface type assertions in `go vet`.
Currently, Go permits any type assertion `x.(T)` (and corresponding type switch case)
where the type of `x` and `T` are interfaces. Yet, if both `x` and `T` have a method
@@ -65,7 +66,7 @@
backwards-compatible change, thus we also propose to start with a `vet` error
instead.
-[[https://golang.org/issue/28591][#28591]].
+[\#28591](https://golang.org/issue/28591).
Constant-evaluate index and slice expressions with constant strings and indices.
Currently, indexing or slicing a constant string with a constant index, or indices,
@@ -75,23 +76,23 @@
and we propose to make the necessary adjustments to the spec and compilers.
(Correction: We found out after posting that this change is not backward-compatible;
-see [[https://golang.org/issue/28591#issuecomment-579993684][comment]] for details.)
+see [comment](https://golang.org/issue/28591#issuecomment-579993684) for details.)
-* Timeline
+## Timeline
We believe that none of these three proposals are controversial but there’s
always a chance that we missed something important. For that reason we plan
to have the proposals implemented at the beginning of the Go 1.15 release cycle
(at or shortly after the Go 1.14 release) so that there is plenty of time to
gather experience and provide feedback. Per the
-[[https://blog.golang.org/go2-here-we-come][proposal evaluation process]],
+[proposal evaluation process](https://blog.golang.org/go2-here-we-come),
the final decision will be made at the end of the development cycle, at the
beginning of May, 2020.
-* And one more thing...
+## And one more thing...
We receive many more language change proposals
-([[https://github.com/golang/go/labels/LanguageChange][issues labeled LanguageChange]])
+([issues labeled LanguageChange](https://github.com/golang/go/labels/LanguageChange))
than we can review thoroughly. For instance, just for error handling alone,
there are 57 issues, of which five are currently still open. Since the cost
of making a language change, no matter how small, is high and the benefits
@@ -100,11 +101,11 @@
feedback. This is unsatisfactory for all parties involved. If you have spent a
lot of time and effort outlining your idea in detail, it would be nice to not
have it immediately rejected. On the flip side, because the general
-[[https://github.com/golang/proposal/blob/master/README.md][proposal process]]
+[proposal process](https://github.com/golang/proposal/blob/master/README.md)
is deliberately simple, it is very easy to create language change proposals
that are only marginally explored, causing the review committee significant
amounts of work. To improve this experience for everybody we are adding a new
-[[https://github.com/golang/proposal/blob/master/go2-language-changes.md][questionnaire]]
+[questionnaire](https://github.com/golang/proposal/blob/master/go2-language-changes.md)
for language changes: filling out that template will help reviewers evaluate
proposals more efficiently because they don’t need to try to answer those
questions themselves. And hopefully it will also provide better guidance for
diff --git a/content/go1.3.article b/content/go1.3.article
index af191aa..ea5c012 100644
--- a/content/go1.3.article
+++ b/content/go1.3.article
@@ -1,57 +1,58 @@
-Go 1.3 is released
+# Go 1.3 is released
18 Jun 2014
+Summary: Today we are happy to announce the release of [Go 1.3](https://golang.org/doc/go1.3). This release comes six months after our last major release and provides better performance, improved tools, support for running Go in new environments, and more. All Go users should upgrade to Go 1.3. You can grab the release from our [downloads page](https://golang.org/dl/) and find the full list of improvements and fixes in the [release notes](https://golang.org/doc/go1.3). What follows are some highlights.
Andrew Gerrand
-* Go 1.3 is released
+##
-Today we are happy to announce the release of [[https://golang.org/doc/go1.3][Go 1.3]].
+Today we are happy to announce the release of [Go 1.3](https://golang.org/doc/go1.3).
This release comes six months after our last major release and provides better
performance, improved tools, support for running Go in new environments, and more.
All Go users should upgrade to Go 1.3.
-You can grab the release from our [[https://golang.org/dl/][downloads page]] and
+You can grab the release from our [downloads page](https://golang.org/dl/) and
find the full list of improvements and fixes in the
-[[https://golang.org/doc/go1.3][release notes]].
+[release notes](https://golang.org/doc/go1.3).
What follows are some highlights.
-[[https://godoc.org/code.google.com/p/go.tools/cmd/godoc][Godoc]],
+[Godoc](https://godoc.org/code.google.com/p/go.tools/cmd/godoc),
the Go documentation server, now performs static analysis.
When enabled with the -analysis flag, analysis results are presented
in both the source and package documentation views, making it easier
than ever to navigate and understand Go programs.
-See [[https://golang.org/lib/godoc/analysis/help.html][the documentation]] for the details.
+See [the documentation](https://golang.org/lib/godoc/analysis/help.html) for the details.
The gc toolchain now supports the Native Client (NaCl) execution sandbox on the
32- and 64-bit Intel architectures.
This permits the safe execution of untrusted code, useful in environments such as the
-[[https://blog.golang.org/playground][Playground]].
-To set up NaCl on your system see the [[https://golang.org/wiki/NativeClient][NativeClient wiki page]].
+[Playground](https://blog.golang.org/playground).
+To set up NaCl on your system see the [NativeClient wiki page](https://golang.org/wiki/NativeClient).
Also included in this release is experimental support for the DragonFly BSD,
Plan 9, and Solaris operating systems. To use Go on these systems you must
-[[https://golang.org/doc/install/source][install from source]].
+[install from source](https://golang.org/doc/install/source).
Changes to the runtime have improved the
-[[https://golang.org/doc/go1.3#performance][performance]] of Go binaries,
+[performance](https://golang.org/doc/go1.3#performance) of Go binaries,
with an improved garbage collector, a new
-[[https://golang.org/s/contigstacks]["contiguous" goroutine stack management strategy]],
+["contiguous" goroutine stack management strategy](https://golang.org/s/contigstacks),
a faster race detector, and improvements to the regular expression engine.
-As part of the general [[https://golang.org/s/go13linker][overhaul]] of the Go
+As part of the general [overhaul](https://golang.org/s/go13linker) of the Go
linker, the compilers and linkers have been refactored. The instruction
selection phase that was part of the linker has been moved to the compiler.
This can speed up incremental builds for large projects.
-The [[https://golang.org/doc/go1.3#garbage_collector][garbage collector]] is now
+The [garbage collector](https://golang.org/doc/go1.3#garbage_collector) is now
precise when examining stacks (collection of the heap has been precise since Go
1.1), meaning that a non-pointer value such as an integer will never be
mistaken for a pointer and prevent unused memory from being reclaimed. This
change affects code that uses package unsafe; if you have unsafe code you
-should read the [[https://golang.org/doc/go1.3#garbage_collector][release notes]]
+should read the [release notes](https://golang.org/doc/go1.3#garbage_collector)
carefully to see if your code needs updating.
We would like to thank the many people who contributed to this release;
it would not have been possible without your help.
So, what are you waiting for?
-Head on over to the [[https://golang.org/dl/][downloads page]] and start hacking.
+Head on over to the [downloads page](https://golang.org/dl/) and start hacking.
diff --git a/content/go1.4.article b/content/go1.4.article
index d106b35..ac5fbc0 100644
--- a/content/go1.4.article
+++ b/content/go1.4.article
@@ -1,22 +1,23 @@
-Go 1.4 is released
+# Go 1.4 is released
10 Dec 2014
+Summary: Today we announce Go 1.4, the fifth major stable release of Go, arriving six months after our previous major release [Go 1.3](https://blog.golang.org/go1.3). It contains a small language change, support for more operating systems and processor architectures, and improvements to the tool chain and libraries. As always, Go 1.4 keeps the promise of compatibility, and almost everything will continue to compile and run without change when moved to 1.4. For the full details, see the [Go 1.4 release notes](https://golang.org/doc/go1.4).
Andrew Gerrand
adg@golang.org
-* Introduction
+##
Today we announce Go 1.4, the fifth major stable release of Go, arriving six
-months after our previous major release [[https://blog.golang.org/go1.3][Go 1.3]].
+months after our previous major release [Go 1.3](https://blog.golang.org/go1.3).
It contains a small language change, support for more operating systems
and processor architectures, and improvements to the tool chain and libraries.
As always, Go 1.4 keeps the promise of compatibility, and almost everything
will continue to compile and run without change when moved to 1.4.
-For the full details, see the [[https://golang.org/doc/go1.4][Go 1.4 release notes]].
+For the full details, see the [Go 1.4 release notes](https://golang.org/doc/go1.4).
The most notable new feature in this release is official support for Android.
Using the support in the core and the libraries in the
-[[https://godoc.org/golang.org/x/mobile][golang.org/x/mobile]] repository,
+[golang.org/x/mobile](https://godoc.org/golang.org/x/mobile) repository,
it is now possible to write simple Android apps using only Go code.
At this stage, the support libraries are still nascent and under heavy development.
Early adopters should expect a bumpy ride, but we welcome the community to get involved.
@@ -24,41 +25,41 @@
The language change is a tweak to the syntax of for-range loops.
You may now write "for range s {" to loop over each item from s,
without having to assign the value, loop index, or map key.
-See the [[https://golang.org/doc/go1.4#forrange][release notes]] for details.
+See the [release notes](https://golang.org/doc/go1.4#forrange) for details.
The go command has a new subcommand, go generate, to automate the running of
tools to generate source code before compilation.
For example, it can be used to automate the generation of String methods for
typed constants using the
-[[https://godoc.org/golang.org/x/tools/cmd/stringer/][new stringer tool]].
-For more information, see the [[https://golang.org/s/go1.4-generate][design document]].
+[new stringer tool](https://godoc.org/golang.org/x/tools/cmd/stringer/).
+For more information, see the [design document](https://golang.org/s/go1.4-generate).
Most programs will run about the same speed or slightly faster in 1.4 than in
1.3; some will be slightly slower.
There are many changes, making it hard to be precise about what to expect.
-See the [[https://golang.org/doc/go1.4#performance][release notes]] for more discussion.
+See the [release notes](https://golang.org/doc/go1.4#performance) for more discussion.
And, of course, there are many more improvements and bug fixes.
In case you missed it, a few weeks ago the sub-repositories were moved to new locations.
For example, the go.tools packages are now imported from "golang.org/x/tools".
-See the [[https://groups.google.com/d/msg/golang-announce/eD8dh3T9yyA/HDOEU_ZSmvAJ][announcement post]] for details.
+See the [announcement post](https://groups.google.com/d/msg/golang-announce/eD8dh3T9yyA/HDOEU_ZSmvAJ) for details.
This release also coincides with the project's move from Mercurial to Git (for
source control), Rietveld to Gerrit (for code review), and Google Code to
Github (for issue tracking and wiki).
The move affects the core Go repository and its sub-repositories.
You can find the canonical Git repositories at
-[[https://go.googlesource.com][go.googlesource.com]],
+[go.googlesource.com](https://go.googlesource.com),
and the issue tracker and wiki at the
-[[https://github.com/golang/go][golang/go GitHub repo]].
+[golang/go GitHub repo](https://github.com/golang/go).
While development has already moved over to the new infrastructure,
for the 1.4 release we still recommend that users who
-[[https://golang.org/doc/install/source][install from source]]
+[install from source](https://golang.org/doc/install/source)
use the Mercurial repositories.
For App Engine users, Go 1.4 is now available for beta testing.
-See [[https://groups.google.com/d/msg/google-appengine-go/ndtQokV3oFo/25wV1W9JtywJ][the announcement]] for details.
+See [the announcement](https://groups.google.com/d/msg/google-appengine-go/ndtQokV3oFo/25wV1W9JtywJ) for details.
From all of us on the Go team, please enjoy Go 1.4, and have a happy holiday season.
diff --git a/content/go1.5.article b/content/go1.5.article
index 4abff05..a3e2fcd 100644
--- a/content/go1.5.article
+++ b/content/go1.5.article
@@ -1,42 +1,43 @@
-Go 1.5 is released
+# Go 1.5 is released
19 Aug 2015
+Summary: Today the Go project is proud to release Go 1.5, the sixth major stable release of Go.
Andrew Gerrand
adg@golang.org
-* Introduction
+##
Today the Go project is proud to release Go 1.5,
the sixth major stable release of Go.
This release includes significant changes to the implementation.
-The compiler tool chain was [[https://golang.org/doc/go1.5#c][translated from C to Go]],
+The compiler tool chain was [translated from C to Go](https://golang.org/doc/go1.5#c),
removing the last vestiges of C code from the Go code base.
-The garbage collector was [[https://golang.org/doc/go1.5#gc][completely redesigned]],
-yielding a [[https://talks.golang.org/2015/go-gc.pdf][dramatic reduction]]
+The garbage collector was [completely redesigned](https://golang.org/doc/go1.5#gc),
+yielding a [dramatic reduction](https://talks.golang.org/2015/go-gc.pdf)
in garbage collection pause times.
Related improvements to the scheduler allowed us to change the default
-[[https://golang.org/pkg/runtime/#GOMAXPROCS][GOMAXPROCS]] value
+[GOMAXPROCS](https://golang.org/pkg/runtime/#GOMAXPROCS) value
(the number of concurrently executing goroutines)
from 1 to the number of logical CPUs.
Changes to the linker enable distributing Go packages as shared libraries to
link into Go programs, and building Go packages into archives or shared
libraries that may be linked into or loaded by C programs
-([[https://golang.org/s/execmodes][design doc]]).
+([design doc](https://golang.org/s/execmodes)).
-The release also includes [[https://golang.org/doc/go1.5#go_command][improvements to the developer tools]].
-Support for [[https://golang.org/s/go14internal]["internal" packages]]
+The release also includes [improvements to the developer tools](https://golang.org/doc/go1.5#go_command).
+Support for ["internal" packages](https://golang.org/s/go14internal)
permits sharing implementation details between packages.
-[[https://golang.org/s/go15vendor][Experimental support]] for "vendoring"
+[Experimental support](https://golang.org/s/go15vendor) for "vendoring"
external dependencies is a step toward a standard mechanism for managing
dependencies in Go programs.
-The new "[[https://golang.org/cmd/trace/][go tool trace]]" command enables the
+The new "[go tool trace](https://golang.org/cmd/trace/)" command enables the
visualisation of program traces generated by new tracing infrastructure in the
runtime.
-The new "[[https://golang.org/cmd/go/#hdr-Show_documentation_for_package_or_symbol][go doc]]"
+The new "[go doc](https://golang.org/cmd/go/#hdr-Show_documentation_for_package_or_symbol)"
command provides an improved command-line interface for viewing Go package documentation.
-There are also several [[https://golang.org/doc/go1.5#ports][new operating system and architecture ports]].
+There are also several [new operating system and architecture ports](https://golang.org/doc/go1.5#ports).
The more mature new ports are darwin/arm,
darwin/arm64 (Apple's iPhone and iPad devices),
and linux/arm64.
@@ -44,34 +45,34 @@
(IBM 64-bit PowerPC, big and little endian).
The new darwin/arm64 port and external linking features fuel the
-[[https://godoc.org/golang.org/x/mobile][Go mobile project]], an experiment to
+[Go mobile project](https://godoc.org/golang.org/x/mobile), an experiment to
see how Go might be used for building apps on Android and iOS devices.
(The Go mobile work itself is not part of this release.)
The only language change is very minor,
-[[https://golang.org/doc/go1.5#language][the lifting of a restriction in the map literal syntax]]
+[the lifting of a restriction in the map literal syntax](https://golang.org/doc/go1.5#language)
to make them more succinct and consistent with slice literals.
The standard library saw many additions and improvements, too.
-The flag package now shows [[https://golang.org/doc/go1.5#flag][cleaner usage messages]].
-The math/big package now provides a [[https://golang.org/pkg/math/big/#Float][Float]]
+The flag package now shows [cleaner usage messages](https://golang.org/doc/go1.5#flag).
+The math/big package now provides a [Float](https://golang.org/pkg/math/big/#Float)
type for computing with arbitrary-precision floating point numbers.
-An [[https://golang.org/doc/go1.5#net][improvement]] to the DNS resolver on
+An [improvement](https://golang.org/doc/go1.5#net) to the DNS resolver on
Linux and BSD systems has removed the cgo requirement for programs that do name
lookups.
-The [[https://golang.org/pkg/go/types/][go/types]] package has been
-[[https://golang.org/doc/go1.5#go_types][moved]] to the standard library from
-the [[https://godoc.org/golang.org/x/tools][golang.org/x/tools]] repository.
-(The new [[https://golang.org/pkg/go/constant/][go/constant]] and
-[[https://golang.org/pkg/go/importer/][go/importer]] packages are also a result
+The [go/types](https://golang.org/pkg/go/types/) package has been
+[moved](https://golang.org/doc/go1.5#go_types) to the standard library from
+the [golang.org/x/tools](https://godoc.org/golang.org/x/tools) repository.
+(The new [go/constant](https://golang.org/pkg/go/constant/) and
+[go/importer](https://golang.org/pkg/go/importer/) packages are also a result
of this move.)
The reflect package has added the
-[[https://golang.org/pkg/reflect/#ArrayOf][ArrayOf]] and
-[[https://golang.org/pkg/reflect/#FuncOf][FuncOf]] functions, analogous to the
-existing [[https://golang.org/pkg/reflect/#SliceOf][SliceOf]] function.
+[ArrayOf](https://golang.org/pkg/reflect/#ArrayOf) and
+[FuncOf](https://golang.org/pkg/reflect/#FuncOf) functions, analogous to the
+existing [SliceOf](https://golang.org/pkg/reflect/#SliceOf) function.
And, of course, there is the usual
-[[https://golang.org/doc/go1.5#minor_library_changes][list of smaller fixes and improvements]].
+[list of smaller fixes and improvements](https://golang.org/doc/go1.5#minor_library_changes).
-For the full story, see the [[https://golang.org/doc/go1.5][detailed release notes]].
+For the full story, see the [detailed release notes](https://golang.org/doc/go1.5).
Or if you just can't wait to get started,
-head over to the [[https://golang.org/dl/][downloads page]] to get Go 1.5 now.
+head over to the [downloads page](https://golang.org/dl/) to get Go 1.5 now.
diff --git a/content/go1.6.article b/content/go1.6.article
index a9fd603..4ecd9f8 100644
--- a/content/go1.6.article
+++ b/content/go1.6.article
@@ -1,38 +1,39 @@
-Go 1.6 is released
+# Go 1.6 is released
17 Feb 2016
+Summary: Today we release [Go version 1.6](https://golang.org/doc/go1.6), the seventh major stable release of Go. You can grab it right now from the [download page](https://golang.org/dl/). Although [the release of Go 1.5](https://blog.golang.org/go1.5) six months ago contained dramatic implementation changes, this release is more incremental.
Andrew Gerrand
adg@golang.org
-* Introduction
+##
-Today we release [[https://golang.org/doc/go1.6][Go version 1.6]],
+Today we release [Go version 1.6](https://golang.org/doc/go1.6),
the seventh major stable release of Go.
-You can grab it right now from the [[https://golang.org/dl/][download page]].
-Although [[https://blog.golang.org/go1.5][the release of Go 1.5]] six months ago
+You can grab it right now from the [download page](https://golang.org/dl/).
+Although [the release of Go 1.5](https://blog.golang.org/go1.5) six months ago
contained dramatic implementation changes,
this release is more incremental.
-The most significant change is support for [[https://http2.github.io/][HTTP/2]]
-in the [[https://golang.org/pkg/net/http/][net/http package]].
+The most significant change is support for [HTTP/2](https://http2.github.io/)
+in the [net/http package](https://golang.org/pkg/net/http/).
HTTP/2 is a new protocol, a follow-on to HTTP that has already seen
widespread adoption by browser vendors and major websites.
-In Go 1.6, support for HTTP/2 is [[https://golang.org/doc/go1.6#http2][enabled by default]]
+In Go 1.6, support for HTTP/2 is [enabled by default](https://golang.org/doc/go1.6#http2)
for both servers and clients when using HTTPS,
-bringing [[https://http2.github.io/faq/][the benefits]] of the new protocol
+bringing [the benefits](https://http2.github.io/faq/) of the new protocol
to a wide range of Go projects,
-such as the popular [[https://caddyserver.com/download][Caddy web server]].
+such as the popular [Caddy web server](https://caddyserver.com/download).
The template packages have learned some new tricks,
-with support for [[https://golang.org/pkg/text/template/#hdr-Text_and_spaces][trimming spaces around template actions]]
+with support for [trimming spaces around template actions](https://golang.org/pkg/text/template/#hdr-Text_and_spaces)
to produce cleaner template output,
-and the introduction of the [[https://golang.org/pkg/text/template/#hdr-Actions][`{{block}}` action]]
+and the introduction of the [`{{block}}` action](https://golang.org/pkg/text/template/#hdr-Actions)
that can be used to create templates that build on other templates.
-A [[https://github.com/golang/example/tree/master#template-godoc][new template example program]] demonstrates these new features.
+A [new template example program](https://github.com/golang/example/tree/master#template-godoc) demonstrates these new features.
-Go 1.5 introduced [[https://golang.org/s/go15vendor][experimental support]]
+Go 1.5 introduced [experimental support](https://golang.org/s/go15vendor)
for a “vendor” directory that was enabled by an environment variable.
-In Go 1.6, the feature is now [[https://golang.org/doc/go1.6#go_command][enabled by default]].
+In Go 1.6, the feature is now [enabled by default](https://golang.org/doc/go1.6#go_command).
Source trees that contain a directory named “vendor” that is not used in accordance with the new feature
will require changes to avoid broken builds (the simplest fix is to rename the directory).
@@ -40,25 +41,25 @@
As always, if one goroutine is writing to a map, no other goroutine should be reading or writing the map concurrently.
If the runtime detects this condition, it prints a diagnosis and crashes the program.
The best way to find out more about the problem is to run it under the
-[[https://blog.golang.org/race-detector][race detector]],
+[race detector](https://blog.golang.org/race-detector),
which will more reliably identify the race and give more detail.
The runtime has also changed how it prints program-ending panics.
It now prints only the stack of the panicking goroutine, rather than all existing goroutines.
This behavior can be configured using the
-[[https://golang.org/pkg/runtime/#hdr-Environment_Variables][GOTRACEBACK]] environment variable
-or by calling the [[https://golang.org/pkg/runtime/debug/#SetTraceback][debug.SetTraceback]] function.
+[GOTRACEBACK](https://golang.org/pkg/runtime/#hdr-Environment_Variables) environment variable
+or by calling the [debug.SetTraceback](https://golang.org/pkg/runtime/debug/#SetTraceback) function.
Users of cgo should be aware of major changes to the rules for sharing pointers between Go and C code.
The rules are designed to ensure that such C code can coexist with Go's garbage collector
and are checked during program execution, so code may require changes to avoid crashes.
-See the [[https://golang.org/doc/go1.6#cgo][release notes]] and
-[[https://golang.org/cmd/cgo/#hdr-Passing_pointers][cgo documentation]] for the details.
+See the [release notes](https://golang.org/doc/go1.6#cgo) and
+[cgo documentation](https://golang.org/cmd/cgo/#hdr-Passing_pointers) for the details.
The compiler, linker, and go command have a new `-msan` flag
analogous to `-race` and only available on linux/amd64,
that enables interoperation with the
-[[http://clang.llvm.org/docs/MemorySanitizer.html][Clang MemorySanitizer]].
+[Clang MemorySanitizer](http://clang.llvm.org/docs/MemorySanitizer.html).
This is useful for testing a program containing suspect C or C++ code.
You might like to try it while testing your cgo code with the new pointer rules.
@@ -68,24 +69,24 @@
With regard to the performance of the compiler tool chain,
build times should be similar to those of Go 1.5.
-The algorithm inside [[https://golang.org/pkg/sort/#Sort][sort.Sort]]
+The algorithm inside [sort.Sort](https://golang.org/pkg/sort/#Sort)
was improved to run about 10% faster,
but the change may break programs that expect a specific ordering
of equal but distinguishable elements.
Such programs should refine their `Less` methods to indicate the desired ordering
-or use [[https://golang.org/pkg/sort/#Stable][sort.Stable]]
+or use [sort.Stable](https://golang.org/pkg/sort/#Stable)
to preserve the input order for equal values.
And, of course, there are many more additions, improvements, and fixes.
-You can find them all in the comprehensive [[https://golang.org/doc/go1.6][release notes]].
+You can find them all in the comprehensive [release notes](https://golang.org/doc/go1.6).
To celebrate the release,
-[[https://github.com/golang/go/wiki/Go-1.6-release-party][Go User Groups around the world]]
+[Go User Groups around the world](https://github.com/golang/go/wiki/Go-1.6-release-party)
are holding release parties on the 17th of February.
Online, the Go contributors are hosting a question and answer session
-on the [[https://reddit.com/r/golang][golang subreddit]] for the next 24 hours.
+on the [golang subreddit](https://reddit.com/r/golang) for the next 24 hours.
If you have questions about the project, the release, or just Go in general,
-then please [[https://www.reddit.com/r/golang/comments/46bd5h/ama_we_are_the_go_contributors_ask_us_anything/][join the discussion]].
+then please [join the discussion](https://www.reddit.com/r/golang/comments/46bd5h/ama_we_are_the_go_contributors_ask_us_anything/).
Thanks to everyone that contributed to the release.
Happy hacking.
diff --git a/content/go1.7-binary-size.article b/content/go1.7-binary-size.article
index 8b7c2fc..6c1dae1 100644
--- a/content/go1.7-binary-size.article
+++ b/content/go1.7-binary-size.article
@@ -1,10 +1,11 @@
-Smaller Go 1.7 binaries
+# Smaller Go 1.7 binaries
18 Aug 2016
+Summary: Go was designed for writing servers. That is how it is most widely used today, and as a result a lot of work on the runtime and compiler is focused on issues that matter to servers: latency, ease of deployment, precise garbage collection, fast startup time, performance.
David Crawshaw
crawshaw@golang.org
-* Introduction
+## Introduction
Go was designed for writing servers.
That is how it is most widely used today, and as a result a lot of
@@ -15,13 +16,13 @@
As Go gets used for a wider variety of programs, there are new issues that must be considered.
One of these is binary size.
It has been on the radar for a long time
-(issue [[https://golang.org/issue/6853][#6853]] was filed over two
+(issue [\#6853](https://golang.org/issue/6853) was filed over two
years ago), but the growing interest in using Go for
deploying binaries on smaller devices — such as the Raspberry Pi or
mobile devices — means it received some attention for the Go 1.7
release.
-* Work done in Go 1.7
+## Work done in Go 1.7
Three significant changes in Go 1.7 affect binary size.
@@ -41,7 +42,7 @@
interface.
Similarly the linker can discard other exported methods, those that are only
accessible through reflection, if the corresponding
-[[https://golang.org/pkg/reflect/#Value.Call][reflection features]]
+[reflection features](https://golang.org/pkg/reflect/#Value.Call)
are not used anywhere in the program.
That change shrinks binaries by 5–20%.
@@ -61,9 +62,9 @@
dependencies. For example, the HTTP client no longer links in the entire HTTP
server.
The full list of changes can be found in issue
-[[https://golang.org/issue/6853][#6853]].
+[\#6853](https://golang.org/issue/6853).
-* Results
+## Results
Typical programs, ranging from tiny toys to large production programs,
are about 30% smaller when built with Go 1.7.
@@ -99,7 +100,7 @@
Big downloads make for a poor user experience, so the reduction here
is good news.
-* Future Work
+## Future Work
Several changes to the run-time type information were too late for the
Go 1.7 freeze, but will hopefully make it into 1.8, further shrinking
@@ -108,7 +109,7 @@
These changes are all conservative, reducing binary size without increasing
build time, startup time, overall execution time, or memory usage.
We could take more radical steps to reduce binary size: the
-[[http://upx.sourceforge.net/][upx]] tool for compressing executables
+[upx](http://upx.sourceforge.net/) tool for compressing executables
shrinks binaries by another 50% at the cost of increased startup time
and potentially increased memory use.
For extremely small systems (the kind that might live on a keychain)
diff --git a/content/go1.7.article b/content/go1.7.article
index 251dd8e..f976c10 100644
--- a/content/go1.7.article
+++ b/content/go1.7.article
@@ -1,63 +1,64 @@
-Go 1.7 is released
+# Go 1.7 is released
15 Aug 2016
+Summary: Today we are happy to announce the release of Go 1.7. You can get it from the [download page](https://golang.org/dl/). There are several significant changes in this release: a port for [Linux on IBM z Systems](https://en.wikipedia.org/wiki/IBM_System_z) (s390x), compiler improvements, the addition of the [context](https://golang.org/pkg/context/) package, and support for [hierarchical tests and benchmarks](https://golang.org/pkg/testing/#hdr-Subtests_and_Sub_benchmarks).
Chris Broadfoot
cbro@golang.org
-* Introduction
+##
Today we are happy to announce the release of Go 1.7.
-You can get it from the [[https://golang.org/dl/][download page]].
+You can get it from the [download page](https://golang.org/dl/).
There are several significant changes in this release: a port for
-[[https://en.wikipedia.org/wiki/IBM_System_z][Linux on IBM z Systems]] (s390x),
-compiler improvements, the addition of the [[https://golang.org/pkg/context/][context]] package,
-and support for [[https://golang.org/pkg/testing/#hdr-Subtests_and_Sub_benchmarks][hierarchical tests and benchmarks]].
+[Linux on IBM z Systems](https://en.wikipedia.org/wiki/IBM_System_z) (s390x),
+compiler improvements, the addition of the [context](https://golang.org/pkg/context/) package,
+and support for [hierarchical tests and benchmarks](https://golang.org/pkg/testing/#hdr-Subtests_and_Sub_benchmarks).
-A new compiler back end, based on [[https://en.wikipedia.org/wiki/Static_single_assignment_form][static single-assignment]] form (SSA),
+A new compiler back end, based on [static single-assignment](https://en.wikipedia.org/wiki/Static_single_assignment_form) form (SSA),
has been under development for the past year.
By representing a program in SSA form, a compiler may perform advanced optimizations more easily.
This new back end generates more compact, more efficient code that includes
optimizations like
-[[https://en.wikipedia.org/wiki/Bounds-checking_elimination][bounds check elimination]] and
-[[https://en.wikipedia.org/wiki/Common_subexpression_elimination][common subexpression elimination]].
-We observed a 5–35% speedup across our [[https://golang.org/test/bench/go1/][benchmarks]].
+[bounds check elimination](https://en.wikipedia.org/wiki/Bounds-checking_elimination) and
+[common subexpression elimination](https://en.wikipedia.org/wiki/Common_subexpression_elimination).
+We observed a 5–35% speedup across our [benchmarks](https://golang.org/test/bench/go1/).
For now, the new backend is only available for the 64-bit x86 platform ("amd64"),
but we’re planning to convert more architecture backends to SSA in future releases.
The compiler front end uses a new, more compact export data format, and
processes import declarations more efficiently.
-While these [[https://golang.org/doc/go1.7#compiler][changes across the compiler toolchain]] are mostly invisible,
-users have [[http://dave.cheney.net/2016/04/02/go-1-7-toolchain-improvements][observed]]
+While these [changes across the compiler toolchain](https://golang.org/doc/go1.7#compiler) are mostly invisible,
+users have [observed](http://dave.cheney.net/2016/04/02/go-1-7-toolchain-improvements)
a significant speedup in compile time and a reduction in binary size by as much as 20–30%.
Programs should run a bit faster due to speedups in the garbage collector and optimizations in the standard library.
Programs with many idle goroutines will experience much shorter garbage collection pauses than in Go 1.6.
-Over the past few years, the [[https://godoc.org/golang.org/x/net/context/][golang.org/x/net/context]]
+Over the past few years, the [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context/)
package has proven to be essential to many Go applications.
Contexts are used to great effect in applications related to networking, infrastructure, and microservices
-(such as [[http://kubernetes.io/][Kubernetes]] and [[https://www.docker.com/][Docker]]).
+(such as [Kubernetes](http://kubernetes.io/) and [Docker](https://www.docker.com/)).
They make it easy to enable cancelation, timeouts, and passing request-scoped data.
To make use of contexts within the standard library and to encourage more extensive use,
-the package has been moved from the [[https://godoc.org/golang.org/x/net/context/][x/net]] repository
-to the standard library as the [[https://golang.org/pkg/context/][context]] package.
+the package has been moved from the [x/net](https://godoc.org/golang.org/x/net/context/) repository
+to the standard library as the [context](https://golang.org/pkg/context/) package.
Support for contexts has been added to the
-[[https://golang.org/pkg/net/][net]],
-[[https://golang.org/pkg/net/http/][net/http]], and
-[[https://golang.org/pkg/os/exec/][os/exec]] packages.
-For more information about contexts, see the [[https://golang.org/pkg/context][package documentation]]
-and the Go blog post [[https://blog.golang.org/context][_Go_Concurrency_Patterns:_Context_]].
+[net](https://golang.org/pkg/net/),
+[net/http](https://golang.org/pkg/net/http/), and
+[os/exec](https://golang.org/pkg/os/exec/) packages.
+For more information about contexts, see the [package documentation](https://golang.org/pkg/context)
+and the Go blog post [_Go Concurrency Patterns: Context_](https://blog.golang.org/context).
-Go 1.5 introduced experimental support for a [[https://golang.org/cmd/go/#hdr-Vendor_Directories]["vendor" directory]],
+Go 1.5 introduced experimental support for a ["vendor" directory](https://golang.org/cmd/go/#hdr-Vendor_Directories),
enabled by the `GO15VENDOREXPERIMENT` environment variable.
Go 1.6 enabled this behavior by default, and in Go 1.7, this switch has been removed and the "vendor" behavior is always enabled.
Go 1.7 includes many more additions, improvements, and fixes.
Find the complete set of changes, and details of the points above, in the
-[[https://golang.org/doc/go1.7.html][Go 1.7 release notes]].
+[Go 1.7 release notes](https://golang.org/doc/go1.7.html).
Finally, the Go team would like thank everyone who contributed to the release.
170 people contributed to this release, including 140 from the Go community.
These contributions ranged from changes to the compiler and linker, to the standard library, to documentation, and code reviews.
We welcome contributions; if you'd like to get involved, check out the
-[[https://golang.org/doc/contribute.html][contribution guidelines]].
+[contribution guidelines](https://golang.org/doc/contribute.html).
diff --git a/content/go1.8.article b/content/go1.8.article
index 58ab44e..6608417 100644
--- a/content/go1.8.article
+++ b/content/go1.8.article
@@ -1,48 +1,49 @@
-Go 1.8 is released
+# Go 1.8 is released
16 Feb 2017
+Summary: Today the Go team is happy to announce the release of Go 1.8. You can get it from the [download page](https://golang.org/dl/). There are significant performance improvements and changes across the standard library.
Chris Broadfoot
cbro@golang.org
-* Introduction
+##
Today the Go team is happy to announce the release of Go 1.8.
-You can get it from the [[https://golang.org/dl/][download page]].
+You can get it from the [download page](https://golang.org/dl/).
There are significant performance improvements and changes across the standard library.
-The compiler back end introduced in [[https://blog.golang.org/go1.7][Go 1.7]] for 64-bit x86 is now used
-on all architectures, and those architectures should see significant [[https://golang.org/doc/go1.8#compiler][performance improvements]].
+The compiler back end introduced in [Go 1.7](https://blog.golang.org/go1.7) for 64-bit x86 is now used
+on all architectures, and those architectures should see significant [performance improvements](https://golang.org/doc/go1.8#compiler).
For instance, the CPU time required by our benchmark programs was reduced by 20-30% on 32-bit ARM systems.
There are also some modest performance improvements in this release for 64-bit x86 systems.
The compiler and linker have been made faster.
Compile times should be improved by about 15% over Go 1.7.
There is still more work to be done in this area: expect faster compilation speeds in future releases.
-Garbage collection pauses should be [[https://golang.org/doc/go1.8#gc][significantly shorter]],
+Garbage collection pauses should be [significantly shorter](https://golang.org/doc/go1.8#gc),
usually under 100 microseconds and often as low as 10 microseconds.
-The HTTP server adds support for [[https://golang.org/doc/go1.8#h2push][HTTP/2 Push]],
+The HTTP server adds support for [HTTP/2 Push](https://golang.org/doc/go1.8#h2push),
allowing servers to preemptively send responses to a client.
This is useful for minimizing network latency by eliminating roundtrips.
-The HTTP server also adds support for [[https://golang.org/doc/go1.8#http_shutdown][graceful shutdown]],
+The HTTP server also adds support for [graceful shutdown](https://golang.org/doc/go1.8#http_shutdown),
allowing servers to minimize downtime by shutting down only after serving all requests that are in flight.
-[[https://golang.org/pkg/context/][Contexts]] (added to the standard library in Go 1.7)
+[Contexts](https://golang.org/pkg/context/) (added to the standard library in Go 1.7)
provide a cancelation and timeout mechanism.
-Go 1.8 [[https://golang.org/doc/go1.8#more_context][adds]] support for contexts in more parts of the standard library,
-including the [[https://golang.org/pkg/database/sql][`database/sql`]] and [[https://golang.org/pkg/net][`net`]] packages
-and [[http://beta.golang.org/pkg/net/http/#Server.Shutdown][`Server.Shutdown`]] in the `net/http` package.
+Go 1.8 [adds](https://golang.org/doc/go1.8#more_context) support for contexts in more parts of the standard library,
+including the [`database/sql`](https://golang.org/pkg/database/sql) and [`net`](https://golang.org/pkg/net) packages
+and [`Server.Shutdown`](http://beta.golang.org/pkg/net/http/#Server.Shutdown) in the `net/http` package.
-It's now much simpler to sort slices using the newly added [[https://golang.org/pkg/sort/#Slice][`Slice`]]
+It's now much simpler to sort slices using the newly added [`Slice`](https://golang.org/pkg/sort/#Slice)
function in the `sort` package. For example, to sort a slice of structs by their `Name` field:
sort.Slice(s, func(i, j int) bool { return s[i].Name < s[j].Name })
Go 1.8 includes many more additions, improvements, and fixes.
Find the complete set of changes, and more information about the improvements listed above, in the
-[[https://golang.org/doc/go1.8.html][Go 1.8 release notes]].
+[Go 1.8 release notes](https://golang.org/doc/go1.8.html).
-To celebrate the release, Go User Groups around the world are holding [[https://github.com/golang/go/wiki/Go-1.8-release-party][release parties]] this week.
+To celebrate the release, Go User Groups around the world are holding [release parties](https://github.com/golang/go/wiki/Go-1.8-release-party) this week.
Release parties have become a tradition in the Go community, so if you missed out this time, keep an eye out when 1.9 nears.
Thank you to over 200 contributors who helped with this release.
diff --git a/content/go1.9.article b/content/go1.9.article
index 8cf8ab4..ec6f176 100644
--- a/content/go1.9.article
+++ b/content/go1.9.article
@@ -1,13 +1,14 @@
-Go 1.9 is released
+# Go 1.9 is released
24 Aug 2017
+Summary: Today the Go team is happy to announce the release of Go 1.9. You can get it from the [download page](https://golang.org/dl/). There are many changes to the language, standard library, runtime, and tooling. This post covers the most significant visible ones. Most of the engineering effort put into this release went to improvements of the runtime and tooling, which makes for a less exciting announcement, but nonetheless a great release.
Francesc Campoy
campoy@golang.org
-* Introduction
+##
Today the Go team is happy to announce the release of Go 1.9.
-You can get it from the [[https://golang.org/dl/][download page]].
+You can get it from the [download page](https://golang.org/dl/).
There are many changes to the language, standard library, runtime, and tooling.
This post covers the most significant visible ones.
Most of the engineering effort put into this release went to improvements of the runtime and tooling,
@@ -20,22 +21,22 @@
This declaration introduces an alias name `T1` for the type `T2`, in the same way that `byte` has
always been an alias for `uint8`.
-The [[https://golang.org/design/18130-type-alias][type alias design document]] and
-[[https://talks.golang.org/2016/refactor.article][an article on refactoring]] cover this addition in more detail.
+The [type alias design document](https://golang.org/design/18130-type-alias) and
+[an article on refactoring](https://talks.golang.org/2016/refactor.article) cover this addition in more detail.
-The new [[https://golang.org/pkg/math/bits][math/bits]] package provides bit counting and manipulation functions
+The new [math/bits](https://golang.org/pkg/math/bits) package provides bit counting and manipulation functions
for unsigned integers, implemented by special CPU instructions when possible.
For example, on x86-64 systems, `bits.TrailingZeros(x)` uses the
-[[https://pdos.csail.mit.edu/6.828/2010/readings/i386/BSF.htm][BSF]] instruction.
+[BSF](https://pdos.csail.mit.edu/6.828/2010/readings/i386/BSF.htm) instruction.
-The `sync` package has added a new [[https://golang.org/pkg/sync#Map][Map]] type, safe for concurrent access.
+The `sync` package has added a new [Map](https://golang.org/pkg/sync#Map) type, safe for concurrent access.
You can read more about it from its documentation and learn more about why it was created from this
-[[https://www.youtube.com/watch?v=C1EtfDnsdDs][GopherCon 2017 lightning talk]]
-([[https://github.com/gophercon/2017-talks/blob/master/lightningtalks/BryanCMills-AnOverviewOfSyncMap/An%20Overview%20of%20sync.Map.pdf][slides]]).
+[GopherCon 2017 lightning talk](https://www.youtube.com/watch?v=C1EtfDnsdDs)
+([slides](https://github.com/gophercon/2017-talks/blob/master/lightningtalks/BryanCMills-AnOverviewOfSyncMap/An%20Overview%20of%20sync.Map.pdf)).
It is not a general replacement for Go's map type; please see the documentation to learn when it should be used.
The `testing` package also has an addition. The new `Helper` method, added to both
-[[https://golang.org/pkg/testing#T.Helper][testing.T]] and [[https://golang.org/pkg/testing#B.Helper][testing.B]],
+[testing.T](https://golang.org/pkg/testing#T.Helper) and [testing.B](https://golang.org/pkg/testing#B.Helper),
marks the calling function as a test helper function.
When the testing package prints file and line information, it shows the location of the call to a helper function
instead of a line in the helper function itself.
@@ -55,14 +56,14 @@
f()
elapsed := time.Since(start)
-See the [[http://beta.golang.org/pkg/time/#hdr-Monotonic_Clocks][package docs]] and
-[[https://github.com/golang/proposal/blob/master/design/12914-monotonic.md][design document]] for details.
+See the [package docs](http://beta.golang.org/pkg/time/#hdr-Monotonic_Clocks) and
+[design document](https://github.com/golang/proposal/blob/master/design/12914-monotonic.md) for details.
Finally, as part of the efforts to make the Go compiler faster, Go 1.9 compiles functions in a package concurrently.
Go 1.9 includes many more additions, improvements, and fixes. Find the complete set of changes,
and more information about the improvements listed above, in the
-[[https://golang.org/doc/go1.9][Go 1.9 release notes]].
+[Go 1.9 release notes](https://golang.org/doc/go1.9).
To celebrate the release, Go User Groups around the world are holding
-[[https://github.com/golang/cowg/blob/master/events/2017-08-go1.9-release-party.md][release parties]].
\ No newline at end of file
+[release parties](https://github.com/golang/cowg/blob/master/events/2017-08-go1.9-release-party.md).
diff --git a/content/go12.article b/content/go12.article
index 2516a77..4ba73c1 100644
--- a/content/go12.article
+++ b/content/go12.article
@@ -1,46 +1,47 @@
-Go 1.2 is released
+# Go 1.2 is released
1 Dec 2013
Tags: release
+Summary: We are pleased to announce the release of Go 1.2, the latest stable version of the Go Programming Language.
Andrew Gerrand
-* Introduction
+##
We are pleased to announce the release of Go 1.2, the latest stable version of
the Go Programming Language.
Binary distributions may be downloaded from the
-[[https://golang.org/doc/install][usual place]] or if you prefer to
-[[https://golang.org/doc/install/source][compile from source]] you should use
+[usual place](https://golang.org/doc/install) or if you prefer to
+[compile from source](https://golang.org/doc/install/source) you should use
the `release` or `go1.2` tags.
This new release comes nearly seven months after the release of Go 1.1 in May,
a much shorter period than the 14 months between 1.1 and 1.0.
We anticipate a comparable interval between future major releases.
-[[https://golang.org/doc/go1.2][Go 1.2]] includes a couple of minor
+[Go 1.2](https://golang.org/doc/go1.2) includes a couple of minor
language changes, several improvements to the language implementation and
tools, some performance improvements, and many additions and
(backward-compatible) changes to the standard library.
-Please read the [[https://golang.org/doc/go1.2][release notes]] for all
+Please read the [release notes](https://golang.org/doc/go1.2) for all
the details, as some changes may affect the behavior of existing (buggy) programs.
What follows is the highlights of the release.
-A new [[https://golang.org/doc/go1.2#three_index][three-index slice syntax]]
+A new [three-index slice syntax](https://golang.org/doc/go1.2#three_index)
adds the ability to specify capacity as well as length. This allows the
programmer to pass a slice value that can only access a limited portion of the
underlying array, a technique that previously required the use of the unsafe
package.
A major new feature of the tool chain is the facility to compute and display
-[[https://golang.org/doc/go1.2#cover][test coverage results]].
-See the [[https://golang.org/cmd/go/#hdr-Description_of_testing_flags][`go`test`]]
-and [[https://godoc.org/code.google.com/p/go.tools/cmd/cover/][cover tool]]
+[test coverage results](https://golang.org/doc/go1.2#cover).
+See the [`go test`](https://golang.org/cmd/go/#hdr-Description_of_testing_flags)
+and [cover tool](https://godoc.org/code.google.com/p/go.tools/cmd/cover/)
documentation for details. Later this week we will publish an article that
discusses this new feature in detail.
-Goroutines are now [[https://golang.org/doc/go1.2#preemption][pre-emptively scheduled]],
+Goroutines are now [pre-emptively scheduled](https://golang.org/doc/go1.2#preemption),
in that the scheduler is invoked occasionally upon entry to a function.
This can prevent busy goroutines from starving other goroutines on the same
thread.
@@ -49,21 +50,21 @@
performance of some programs. (The old size had a tendency to introduce
expensive stack-segment switching in performance-critical sections.)
On the other end, new restrictions on
-[[https://golang.org/doc/go1.2#stack_size][stack sizes]] and
-[[https://golang.org/doc/go1.2#thread_limit][the number of operating system threads]]
+[stack sizes](https://golang.org/doc/go1.2#stack_size) and
+[the number of operating system threads](https://golang.org/doc/go1.2#thread_limit)
should prevent misbehaving programs from consuming all the resources of a
machine. (These limits may be adjusted using new functions in the
-[[https://golang.org/pkg/runtime/debug][`runtime/debug` package]].)
+[`runtime/debug` package](https://golang.org/pkg/runtime/debug).)
-Finally, among the [[https://golang.org/doc/go1.2#library][many changes to the standard library]],
+Finally, among the [many changes to the standard library](https://golang.org/doc/go1.2#library),
significant changes include
-the new [[https://golang.org/doc/go1.2#encoding][`encoding` package]],
-[[https://golang.org/doc/go1.2#fmt_indexed_arguments][indexed arguments]] in `Printf` format strings, and
-some [[https://golang.org/doc/go1.2#text_template][convenient additions]] to the template packages.
+the new [`encoding` package](https://golang.org/doc/go1.2#encoding),
+[indexed arguments](https://golang.org/doc/go1.2#fmt_indexed_arguments) in `Printf` format strings, and
+some [convenient additions](https://golang.org/doc/go1.2#text_template) to the template packages.
-As part of the release, the [[http://play.golang.org/][Go Playground]] has been
+As part of the release, the [Go Playground](http://play.golang.org/) has been
updated to Go 1.2. This also affects services that use the Playground, such as
-[[http://tour.golang.org/][the Go Tour]] and this blog.
+[the Go Tour](http://tour.golang.org/) and this blog.
The update also adds the ability to use threads and the `os`, `net`, and
`unsafe` packages inside the sandbox, making it more like a real Go environment.
@@ -71,7 +72,7 @@
submitted bug reports to the 116 (!) contributors who committed more than 1600
changes to the core: Your help is invaluable to the project. Thank you!
-_This_blog_post_is_the_first_of_the_
-[[http://blog.gopheracademy.com/day-01-go-1.2][Go Advent Calendar]],
-_a_series_of_daily_articles_presented_by_the_
-[[http://gopheracademy.com/][Gopher Academy]] _from_December_1_to_25._
+_This blog post is the first of the_
+[Go Advent Calendar](http://blog.gopheracademy.com/day-01-go-1.2),
+_a series of daily articles presented by the_
+[Gopher Academy](http://gopheracademy.com/) _from December 1 to 25._
diff --git a/content/go15gc.article b/content/go15gc.article
index 56f7568..96b5cd9 100644
--- a/content/go15gc.article
+++ b/content/go15gc.article
@@ -1,10 +1,11 @@
-Go GC: Prioritizing low latency and simplicity
+# Go GC: Prioritizing low latency and simplicity
31 Aug 2015
+Summary: Go is building a garbage collector (GC) not only for 2015 but for 2025 and beyond: A GC that supports today’s software development and scales along with new software and hardware throughout the next decade. Such a future has no place for stop-the-world GC pauses, which have been an impediment to broader uses of safe and secure languages such as Go.
Richard Hudson
rlh@golang.org
-* The Setup
+## The Setup
Go is building a garbage collector (GC) not only for 2015 but for 2025 and
beyond: A GC that supports today’s software development and scales along with
@@ -14,13 +15,13 @@
Go 1.5, the first glimpse of this future, achieves GC latencies well below the
10 millisecond goal we set a year ago. We presented some impressive numbers
-in [[https://talks.golang.org/2015/go-gc.pdf][a talk at Gophercon]].
+in [a talk at Gophercon](https://talks.golang.org/2015/go-gc.pdf).
The latency improvements have generated a lot of attention;
Robin Verlangen’s blog post
-[[https://medium.com/@robin.verlangen/billions-of-request-per-day-meet-go-1-5-362bfefa0911][_Billions_of_requests_per_day_meet_Go_1.5_]]
+[_Billions of requests per day meet Go 1.5_](https://medium.com/@robin.verlangen/billions-of-request-per-day-meet-go-1-5-362bfefa0911)
validates our direction with end to end results.
We also particularly enjoyed
-[[https://twitter.com/inconshreveable/status/620650786662555648][Alan Shreve’s production server graphs]]
+[Alan Shreve’s production server graphs](https://twitter.com/inconshreveable/status/620650786662555648)
and his "Holy 85% reduction" comment.
Today 16 gigabytes of RAM costs $100 and CPUs come with many cores, each with
@@ -33,12 +34,12 @@
supports. This blog post gives a high-level overview of what we have done for
the Go 1.5 collector.
-* The Embellishment
+## The Embellishment
To create a garbage collector for the next decade, we turned to an algorithm
from decades ago. Go's new garbage collector is a _concurrent_, _tri-color_,
_mark-sweep_ collector, an idea first proposed by
-[[http://dl.acm.org/citation.cfm?id=359655][Dijkstra in 1978]].
+[Dijkstra in 1978](http://dl.acm.org/citation.cfm?id=359655).
This is a deliberate divergence from most "enterprise" grade garbage collectors
of today, and one that we believe is well suited to the properties of modern
hardware and the latency requirements of modern software.
@@ -58,7 +59,7 @@
maintain the invariant that no black object points to a white object, lest the
garbage collector lose track of an object installed in a part of the heap it
has already visited. Maintaining this invariant is the job of the
-_write_barrier_, which is a small function run by the mutator whenever a
+_write barrier_, which is a small function run by the mutator whenever a
pointer in the heap is modified. Go’s write barrier colors the now-reachable
object grey if it is currently white, ensuring that the garbage collector will
eventually scan it for pointers.
@@ -102,7 +103,7 @@
team can focus on improving the runtime based on feedback from real customer
applications.
-* The Punchline
+## The Punchline
Go 1.5’s GC ushers in a future where stop-the-world pauses are no longer a
barrier to moving to a safe and secure language. It is a future where
@@ -110,5 +111,5 @@
more powerful the GC will not be an impediment to better, more scalable
software. It’s a good place to be for the next decade and beyond.
For more details about the 1.5 GC and how we eliminated latency issues see the
-[[https://www.youtube.com/watch?v=aiv1JOfMjm0][Go GC: Latency Problem Solved presentation]]
-or [[https://talks.golang.org/2015/go-gc.pdf][the slides]].
+[Go GC: Latency Problem Solved presentation](https://www.youtube.com/watch?v=aiv1JOfMjm0)
+or [the slides](https://talks.golang.org/2015/go-gc.pdf).
diff --git a/content/go2-here-we-come.article b/content/go2-here-we-come.article
index 0f749de..c7927ae 100644
--- a/content/go2-here-we-come.article
+++ b/content/go2-here-we-come.article
@@ -1,14 +1,15 @@
-Go 2, here we come!
+# Go 2, here we come!
29 Nov 2018
Tags: go2, proposals, community
+Summary: At GopherCon 2017, Russ Cox officially started the thought process on the next big version of Go with his talk [The Future of Go](https://www.youtube.com/watch?v=0Zbh_vmAKvk) ([blog post](https://blog.golang.org/toward-go2)). We have called this future language informally Go 2, even though we understand now that it will arrive in incremental steps rather than with a big bang and a single major release. Still, Go 2 is a useful moniker, if only to have a way to talk about that future language, so let’s keep using it for now.
Robert Griesemer
-* Background
+## Background
At GopherCon 2017, Russ Cox officially started the thought process on the
-next big version of Go with his talk [[https://www.youtube.com/watch?v=0Zbh_vmAKvk][The Future of Go]]
-([[https://blog.golang.org/toward-go2][blog post]]). We have
+next big version of Go with his talk [The Future of Go](https://www.youtube.com/watch?v=0Zbh_vmAKvk)
+([blog post](https://blog.golang.org/toward-go2)). We have
called this future language informally Go 2, even though we understand now
that it will arrive in incremental steps rather than with a big bang and a
single major release. Still, Go 2 is a useful moniker, if only to have a way
@@ -21,7 +22,7 @@
learned a lot about the language and libraries that we didn’t know in the
beginning, and that was only possible through feedback from the Go community.
-In 2015 we introduced the [[https://golang.org/s/proposal][proposal process]]
+In 2015 we introduced the [proposal process](https://golang.org/s/proposal)
to gather a specific kind of feedback: proposals for language and library
changes. A committee composed of senior Go team members has been reviewing,
categorizing, and deciding on incoming proposals on a regular basis. That
@@ -33,28 +34,28 @@
It is now time to act on the Go 2 proposals, but to do this we first need a plan.
-* Status
+## Status
At the time of writing, there are around 120
-[[https://github.com/golang/go/issues?page=1&q=is%3Aissue+is%3Aopen+label%3Aproposal+label%3AGo2&utf8=%E2%9C%93][open issues labeled Go 2 proposal]].
+[open issues labeled Go 2 proposal](https://github.com/golang/go/issues?page=1&q=is%3Aissue+is%3Aopen+label%3Aproposal+label%3AGo2&utf8=%E2%9C%93).
Each of them proposes a significant library or language change, often one
that does not satisfy the existing
-[[https://golang.org/doc/go1compat][Go 1 compatibility guarantee]].
+[Go 1 compatibility guarantee](https://golang.org/doc/go1compat).
Ian Lance Taylor and I
have been working through these proposals and categorized them
-([[https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aproposal+label%3AGo2+label%3AGo2Cleanup][Go2Cleanup]],
-[[https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aproposal+label%3AGo2+label%3ANeedsDecision][NeedsDecision]],
+([Go2Cleanup](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aproposal+label%3AGo2+label%3AGo2Cleanup),
+[NeedsDecision](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Aproposal+label%3AGo2+label%3ANeedsDecision),
etc.) to get an idea of what’s there and to make it easier to
proceed with them. We also merged related proposals and closed the ones which
seemed clearly out of the scope of Go, or were otherwise unactionable.
Ideas from the remaining proposals will likely influence Go 2’s libraries
and languages. Two major themes have emerged early on: support for better
-error handling, and generics. [[https://blog.golang.org/go2draft][Draft designs]]
+error handling, and generics. [Draft designs](https://blog.golang.org/go2draft)
for these two areas have been
published at this year’s GopherCon, and more exploration is needed.
-But what about the rest? We are [[https://blog.golang.org/toward-go2][constrained]]
+But what about the rest? We are [constrained](https://blog.golang.org/toward-go2)
by the fact that we now have
millions of Go programmers and a large body of Go code, and we need to
bring it all along, lest we risk a split ecosystem. That means we cannot
@@ -62,19 +63,19 @@
carefully. To make progress, we are implementing a new proposal evaluation
process for these significant potential changes.
-* Proposal evaluation process
+## Proposal evaluation process
The purpose of the proposal evaluation process is to collect feedback on
a small number of select proposals such that a final decision can be made.
The process runs more or less in parallel to a release cycle and consists
of the following steps:
-1. _Proposal_selection_. The Go team selects a small number of
-[[https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3AGo2+label%3AProposal][Go 2 proposals]]
+1. _Proposal selection_. The Go team selects a small number of
+[Go 2 proposals](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3AGo2+label%3AProposal)
that seem worth considering for acceptance, without making a final decision.
See below for more on the selection criteria.
-2. _Proposal_feedback_. The Go team sends out an announcement listing the selected
+2. _Proposal feedback_. The Go team sends out an announcement listing the selected
proposals. The announcement explains to the community the tentative intent to
move forward with the selected proposals and to collect feedback for each
of them. This gives the community a chance to make suggestions and express
@@ -84,12 +85,12 @@
The target for these significant language and library changes is to have
them ready to submit on day 1 of an upcoming release cycle.
-4. _Implementation_feedback_. During the development cycle, the Go team and
+4. _Implementation feedback_. During the development cycle, the Go team and
community have a chance to experiment with the new features and collect
further feedback.
-5. _Launch_decision_. At the end of the three month
-[[https://github.com/golang/go/wiki/Go-Release-Cycle][development cycle]]
+5. _Launch decision_. At the end of the three month
+[development cycle](https://github.com/golang/go/wiki/Go-Release-Cycle)
(just when starting the three month repo freeze before a release), and
based on the experience and feedback gathered during the release cycle,
the Go team makes the final decision about whether to ship each change.
@@ -106,15 +107,15 @@
proposals, there are simply too many of them. That’s where the selection
criteria come into play.
-* Proposal selection criteria
+## Proposal selection criteria
A proposal must at the very least:
-1. _address_an_important_issue_for_many_people_,
+1. _address an important issue for many people_,
-2. _have_minimal_impact_on_everybody_else_, and
+2. _have minimal impact on everybody else_, and
-3. _come_with_a_clear_and_well-understood_solution_.
+3. _come with a clear and well-understood solution_.
Requirement 1 ensures that any changes we make help as many Go developers
as possible (make their code more robust, easier to write, more likely to
@@ -131,7 +132,7 @@
solution. That’s fine, it just means that the proposal needs to go back to
the drawing board before it can be considered.
-* Proposals
+## Proposals
We feel that this is a good plan that should serve us well but it is important
to understand that this is only a starting point. As the process is used we will
@@ -146,14 +147,14 @@
With all that said, we propose the following selection of Go 2 proposals for
the Go 1.13 release (step 1 in the proposal evaluation process):
-1. [[https://github.com/golang/go/issues/20706][_#20706_]] _General_Unicode_identifiers_based_on_ [[http://unicode.org/reports/tr31/][_Unicode_TR31_]]:
+1. [_\#20706_](https://github.com/golang/go/issues/20706) _General Unicode identifiers based on_ [_Unicode TR31_](http://unicode.org/reports/tr31/):
This addresses an important issue for Go programmers using non-Western alphabets
and should have little if any impact on anyone else. There are normalization
questions which we need to answer and where community feedback will be
important, but after that the implementation path is well understood.
Note that identifier export rules will not be affected by this.
-2. [[https://github.com/golang/go/issues/19308][_#19308_]], [[https://github.com/golang/go/issues/28493][_#28493_]] _Binary_integer_literals_and_support_for___in_number_literals_:
+2. [_\#19308_](https://github.com/golang/go/issues/19308), [_\#28493_](https://github.com/golang/go/issues/28493) _Binary integer literals and support for \_ in number literals_:
These are relatively minor changes that seem hugely popular among many
programmers. They may not quite reach the threshold of solving an
“important issue” (hexadecimal numbers have worked well so far) but they
@@ -162,14 +163,14 @@
don’t care about binary integer literals or number formatting, and the
implementation is well understood.
-3. [[https://github.com/golang/go/issues/19113][_#19113_]] _Permit_signed_integers_as_shift_counts_:
+3. [_\#19113_](https://github.com/golang/go/issues/19113) _Permit signed integers as shift counts_:
An estimated 38% of all non-constant shifts require an (artificial) uint
conversion (see the issue for a more detailed break-down). This proposal
will clean up a lot of code, get shift expressions better in sync with index
expressions and the built-in functions cap and len. It will mostly have a
positive impact on code. The implementation is well understood.
-* Next steps
+## Next steps
With this blog post we have executed the first step and started the second
step of the proposal evaluation process. It’s now up to you, the
diff --git a/content/go2-next-steps.article b/content/go2-next-steps.article
index 07f6abe..5a13d60 100644
--- a/content/go2-next-steps.article
+++ b/content/go2-next-steps.article
@@ -1,10 +1,11 @@
-Next steps toward Go 2
+# Next steps toward Go 2
26 Jun 2019
Tags: go2, proposals, community
+Summary: We’re well on the way towards the release of Go 1.13, hopefully in early August of this year. This is the first release that will include concrete changes to the language (rather than just minor adjustments to the spec), after a longer moratorium on any such changes.
Robert Griesemer, for the Go team
-* Status
+## Status
We’re well on the way towards the release of Go 1.13,
hopefully in early August of this year.
@@ -15,17 +16,17 @@
To arrive at these language changes,
we started out with a small set of viable proposals,
selected from the much larger list of
-[[https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3AGo2+label%3AProposal][Go 2 proposals]],
+[Go 2 proposals](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3AGo2+label%3AProposal),
per the new proposal evaluation process outlined
in the
-“[[https://blog.golang.org/go2-here-we-come][Go 2, here we come!]]” blog post.
+“[Go 2, here we come!](https://blog.golang.org/go2-here-we-come)” blog post.
We wanted our initial selection of proposals
to be relatively minor and mostly uncontroversial,
to have a reasonably high chance of having them
make it through the process.
The proposed changes had to be backward-compatible
to be minimally disruptive since
-[[https://blog.golang.org/using-go-modules][modules]],
+[modules](https://blog.golang.org/using-go-modules),
which eventually will allow module-specific language version selection,
are not the default build mode quite yet.
In short, this initial round of changes was more about
@@ -33,30 +34,30 @@
with the new process, rather than tackling big issues.
Our
-[[https://blog.golang.org/go2-here-we-come][original list of proposals]] –
-[[https://golang.org/issue/20706][general Unicode identifiers]],
-[[https://golang.org/issue/19308][binary integer literals]],
-[[https://golang.org/issue/28493][separators for number literals]],
-[[https://golang.org/issue/19113][signed integer shift counts]] –
+[original list of proposals](https://blog.golang.org/go2-here-we-come) –
+[general Unicode identifiers](https://golang.org/issue/20706),
+[binary integer literals](https://golang.org/issue/19308),
+[separators for number literals](https://golang.org/issue/28493),
+[signed integer shift counts](https://golang.org/issue/19113) –
got both trimmed and expanded.
The general Unicode identifiers didn’t make the cut
as we didn’t have a concrete design document in place in time.
The proposal for binary integer literals was expanded significantly
and led to a comprehensive overhaul and modernization of
-[[https://golang.org/design/19308-number-literals][Go’s number literal syntax]].
+[Go’s number literal syntax](https://golang.org/design/19308-number-literals).
And we added the Go 2 draft design proposal on
-[[https://golang.org/design/go2draft-error-inspection][error inspection]],
+[error inspection](https://golang.org/design/go2draft-error-inspection),
which has been
-[[https://golang.org/issue/29934#issuecomment-489682919][partially accepted]].
+[partially accepted](https://golang.org/issue/29934#issuecomment-489682919).
With these initial changes in place for Go 1.13,
it’s now time to look forward to Go 1.14
and determine what we want to tackle next.
-* Proposals for Go 1.14
+## Proposals for Go 1.14
The goals we have for Go today are the same as in 2007: to
-[[https://blog.golang.org/toward-go2][make software development scale]].
+[make software development scale](https://blog.golang.org/toward-go2).
The three biggest hurdles on this path to improved scalability for Go are
package and version management,
better error handling support,
@@ -66,14 +67,14 @@
support for package and version management is being addressed.
This leaves better error handling support and generics.
We have been working on both of these and presented
-[[https://golang.org/design/go2draft][draft designs]]
+[draft designs](https://golang.org/design/go2draft)
at last year’s GopherCon in Denver.
Since then we have been iterating those designs.
For error handling, we have published a concrete,
significantly revised and simplified proposal (see below).
For generics, we are making progress, with a talk
(“Generics in Go” by Ian Lance Taylor)
-[[https://www.gophercon.com/agenda/session/49028][coming up]]
+[coming up](https://www.gophercon.com/agenda/session/49028)
at this year’s GopherCon in San Diego,
but we have not reached the concrete proposal stage yet.
@@ -81,9 +82,9 @@
improvements to the language.
For Go 1.14, we have selected the following proposals:
-[[https://golang.org/issue/32437][#32437]].
+[\#32437](https://golang.org/issue/32437).
A built-in Go error check function, “try”
-([[https://golang.org/design/32437-try-builtin][design doc]]).
+([design doc](https://golang.org/design/32437-try-builtin)).
This is our concrete proposal for improved error handling.
While the proposed, fully backwards-compatible language extension
@@ -91,20 +92,20 @@
This proposal has already attracted an enormous amount of comments,
and it’s not easy to follow up.
We recommend starting with the
-[[https://golang.org/issue/32437#issue-452239211][initial comment]]
+[initial comment](https://golang.org/issue/32437#issue-452239211)
for a quick outline and then to read the detailed design doc.
The initial comment contains a couple of links leading to summaries
of the feedback so far.
Please follow the feedback recommendations
(see the “Next steps” section below) before posting.
-[[https://golang.org/issue/6977][#6977]].
+[\#6977](https://golang.org/issue/6977).
Allow embedding overlapping interfaces
-([[https://golang.org/design/6977-overlapping-interfaces][design doc]]).
+([design doc](https://golang.org/design/6977-overlapping-interfaces)).
This is an old, backwards-compatible proposal for making interface embedding more tolerant.
-[[https://golang.org/issue/32479][#32479]] Diagnose `string(int)` conversion in `go`vet`.
+[\#32479](https://golang.org/issue/32479) Diagnose `string(int)` conversion in `go vet`.
The `string(int)` conversion was introduced early in Go for convenience,
but it is confusing to newcomers (`string(10)` is `"\n"` not `"10"`)
@@ -113,16 +114,16 @@
Since removing this conversion is not a backwards-compatible change,
we propose to start with a `vet` error instead.
-[[https://golang.org/issue/32466][#32466]] Adopt crypto principles
-([[https://golang.org/design/cryptography-principles][design doc]]).
+[\#32466](https://golang.org/issue/32466) Adopt crypto principles
+([design doc](https://golang.org/design/cryptography-principles)).
This is a request for feedback on a set of design principles for
cryptographic libraries that we would like to adopt.
See also the related
-[[https://golang.org/issue/32716][proposal to remove SSLv3 support]]
+[proposal to remove SSLv3 support](https://golang.org/issue/32716)
from `crypto/tls`.
-* Next steps
+## Next steps
We are actively soliciting feedback on all these proposals.
We are especially interested in fact-based evidence
@@ -142,11 +143,11 @@
experimental phase with a given proposal,
we are planning to have all these implemented at the
start of the
-[[https://golang.org/wiki/Go-Release-Cycle][Go 1.14 cycle]]
+[Go 1.14 cycle](https://golang.org/wiki/Go-Release-Cycle)
(beginning of August, 2019)
so that they can be evaluated in practice.
Per the
-[[https://blog.golang.org/go2-here-we-come][proposal evaluation process]],
+[proposal evaluation process](https://blog.golang.org/go2-here-we-come),
the final decision will be
made at the end of the development cycle (beginning of November, 2019).
diff --git a/content/go2draft.article b/content/go2draft.article
index e1e4715..ed6e9b9 100644
--- a/content/go2draft.article
+++ b/content/go2draft.article
@@ -1,18 +1,19 @@
-Go 2 Draft Designs
+# Go 2 Draft Designs
28 Aug 2018
Tags: community, video
+Summary: Yesterday, at our annual Go contributor summit, attendees got a sneak peek at preliminary _drafts_ of possible designs for changes to error handling and generics. [The development of Go 2](https://blog.golang.org/toward-go2) was announced last year and we are excited to share updates with you today.
-* Introduction
+##
Yesterday, at our annual Go contributor summit,
attendees got a sneak peek at preliminary _drafts_ of
possible designs for changes to error handling and generics.
-[[https://blog.golang.org/toward-go2][The development of Go 2]] was announced last year and we are excited to share updates with you today.
+[The development of Go 2](https://blog.golang.org/toward-go2) was announced last year and we are excited to share updates with you today.
For a quick overview, watch this short message we just played at Gophercon 2018:
.iframe //www.youtube.com/embed/6wIP3rO6On8 315 560
We invite everyone in the Go community to
-[[https://go.googlesource.com/proposal/+/master/design/go2draft.md][learn more about the designs]]
+[learn more about the designs](https://go.googlesource.com/proposal/+/master/design/go2draft.md)
and help us improve them.
diff --git a/content/gobs-of-data.article b/content/gobs-of-data.article
index 21a9dca..965a98c 100644
--- a/content/gobs-of-data.article
+++ b/content/gobs-of-data.article
@@ -1,23 +1,24 @@
-Gobs of data
+# Gobs of data
24 Mar 2011
Tags: gob, json, protobuf, xml, technical
+Summary: To transmit a data structure across a network or to store it in a file, it must be encoded and then decoded again. There are many encodings available, of course: [JSON](http://www.json.org/), [XML](http://www.w3.org/XML/), Google's [protocol buffers](http://code.google.com/p/protobuf), and more. And now there's another, provided by Go's [gob](https://golang.org/pkg/encoding/gob/) package.
Rob Pike
-* Introduction
+## Introduction
To transmit a data structure across a network or to store it in a file,
it must be encoded and then decoded again.
There are many encodings available, of course:
-[[http://www.json.org/][JSON]], [[http://www.w3.org/XML/][XML]],
-Google's [[http://code.google.com/p/protobuf][protocol buffers]], and more.
-And now there's another, provided by Go's [[https://golang.org/pkg/encoding/gob/][gob]] package.
+[JSON](http://www.json.org/), [XML](http://www.w3.org/XML/),
+Google's [protocol buffers](http://code.google.com/p/protobuf), and more.
+And now there's another, provided by Go's [gob](https://golang.org/pkg/encoding/gob/) package.
Why define a new encoding? It's a lot of work and redundant at that.
Why not just use one of the existing formats? Well,
for one thing, we do!
-Go has [[https://golang.org/pkg/][packages]] supporting all the encodings
-just mentioned (the [[http://github.com/golang/protobuf][protocol buffer package]]
+Go has [packages](https://golang.org/pkg/) supporting all the encodings
+just mentioned (the [protocol buffer package](http://github.com/golang/protobuf)
is in a separate repository but it's one of the most frequently downloaded).
And for many purposes, including communicating with tools and systems written in other languages,
they're the right choice.
@@ -29,7 +30,7 @@
language-independent encoding cannot.
At the same time, there are lessons to be learned from the existing systems.
-* Goals
+## Goals
The gob package was designed with a number of goals in mind.
@@ -55,7 +56,7 @@
There were also some things to learn from our experiences with Google protocol buffers.
-* Protocol buffer misfeatures
+## Protocol buffer misfeatures
Protocol buffers had a major effect on the design of gobs,
but have three features that were deliberately avoided.
@@ -102,7 +103,7 @@
So gobs end up looking like a sort of generalized, simplified protocol buffer. How do they work?
-* Values
+## Values
The encoded gob data isn't about types like `int8` and `uint16`.
Instead, somewhat analogous to constants in Go,
@@ -167,18 +168,18 @@
such as small integers, have a lot of zeros at the low end that we can avoid transmitting.
One nice feature of gobs that Go makes possible is that they allow you to
-define your own encoding by having your type satisfy the [[https://golang.org/pkg/encoding/gob/#GobEncoder][GobEncoder]]
-and [[https://golang.org/pkg/encoding/gob/#GobDecoder][GobDecoder]] interfaces,
-in a manner analogous to the [[https://golang.org/pkg/encoding/json/][JSON]]
-package's [[https://golang.org/pkg/encoding/json/#Marshaler][Marshaler]]
-and [[https://golang.org/pkg/encoding/json/#Unmarshaler][Unmarshaler]] and
-also to the [[https://golang.org/pkg/fmt/#Stringer][Stringer]] interface
-from [[https://golang.org/pkg/fmt/][package fmt]].
+define your own encoding by having your type satisfy the [GobEncoder](https://golang.org/pkg/encoding/gob/#GobEncoder)
+and [GobDecoder](https://golang.org/pkg/encoding/gob/#GobDecoder) interfaces,
+in a manner analogous to the [JSON](https://golang.org/pkg/encoding/json/)
+package's [Marshaler](https://golang.org/pkg/encoding/json/#Marshaler)
+and [Unmarshaler](https://golang.org/pkg/encoding/json/#Unmarshaler) and
+also to the [Stringer](https://golang.org/pkg/fmt/#Stringer) interface
+from [package fmt](https://golang.org/pkg/fmt/).
This facility makes it possible to represent special features,
enforce constraints, or hide secrets when you transmit data.
-See the [[https://golang.org/pkg/encoding/gob/][documentation]] for details.
+See the [documentation](https://golang.org/pkg/encoding/gob/) for details.
-* Types on the wire
+## Types on the wire
The first time you send a given type, the gob package includes in the data
stream a description of that type.
@@ -212,7 +213,7 @@
for the set of bootstrap types,
which is a well-defined starting point.
-* Compiling a machine
+## Compiling a machine
The first time you encode a value of a given type,
the gob package builds a little interpreted machine specific to that data type.
@@ -237,13 +238,13 @@
Once that decoding machine is built, though,
it's again a reflectionless engine that uses unsafe methods to get maximum speed.
-* Use
+## Use
There's a lot going on under the hood, but the result is an efficient,
easy-to-use encoding system for transmitting data.
Here's a complete example showing differing encoded and decoded types.
Note how easy it is to send and receive values;
-all you need to do is present values and variables to the [[https://golang.org/pkg/encoding/gob/][gob package]]
+all you need to do is present values and variables to the [gob package](https://golang.org/pkg/encoding/gob/)
and it does all the work.
package main
@@ -286,16 +287,16 @@
fmt.Printf("%q: {%d,%d}\n", q.Name, *q.X, *q.Y)
}
-You can compile and run this example code in the [[http://play.golang.org/p/_-OJV-rwMq][Go Playground]].
+You can compile and run this example code in the [Go Playground](http://play.golang.org/p/_-OJV-rwMq).
-The [[https://golang.org/pkg/net/rpc/][rpc package]] builds on gobs to turn
+The [rpc package](https://golang.org/pkg/net/rpc/) builds on gobs to turn
this encode/decode automation into transport for method calls across the network.
That's a subject for another article.
-* Details
+## Details
-The [[https://golang.org/pkg/encoding/gob/][gob package documentation]],
-especially the file [[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]],
+The [gob package documentation](https://golang.org/pkg/encoding/gob/),
+especially the file [doc.go](https://golang.org/src/pkg/encoding/gob/doc.go),
expands on many of the details described here and includes a full worked
example showing how the encoding represents data.
If you are interested in the innards of the gob implementation,
diff --git a/content/godoc-documenting-go-code.article b/content/godoc-documenting-go-code.article
index 89df534..e75b105 100644
--- a/content/godoc-documenting-go-code.article
+++ b/content/godoc-documenting-go-code.article
@@ -1,10 +1,11 @@
-Godoc: documenting Go code
+# Godoc: documenting Go code
31 Mar 2011
Tags: godoc, technical
+Summary: The Go project takes documentation seriously. Documentation is a huge part of making software accessible and maintainable. Of course it must be well-written and accurate, but it also must be easy to write and to maintain. Ideally, it should be coupled to the code itself so the documentation evolves along with the code. The easier it is for programmers to produce good documentation, the better for everyone.
Andrew Gerrand
-* Introduction
+##
The Go project takes documentation seriously.
Documentation is a huge part of making software accessible and maintainable.
@@ -15,7 +16,7 @@
The easier it is for programmers to produce good documentation,
the better for everyone.
-To that end, we have developed the [[https://golang.org/cmd/godoc/][godoc]] documentation tool.
+To that end, we have developed the [godoc](https://golang.org/cmd/godoc/) documentation tool.
This article describes godoc's approach to documentation,
and explains how you can use our conventions and tools to write good documentation
for your own projects.
@@ -24,10 +25,10 @@
as HTML or plain text.
The end result is documentation tightly coupled with the code it documents.
For example, through godoc's web interface you can navigate from a function's
-[[https://golang.org/pkg/strings/#HasPrefix][documentation]] to its [[https://golang.org/src/pkg/strings/strings.go#L493][implementation]] with one click.
+[documentation](https://golang.org/pkg/strings/#HasPrefix) to its [implementation](https://golang.org/src/pkg/strings/strings.go#L493) with one click.
-Godoc is conceptually related to Python's [[http://www.python.org/dev/peps/pep-0257/][Docstring]]
-and Java's [[http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html][Javadoc]],
+Godoc is conceptually related to Python's [Docstring](http://www.python.org/dev/peps/pep-0257/)
+and Java's [Javadoc](http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html),
but its design is simpler.
The comments read by godoc are not language constructs (as with Docstring)
nor must they have their own machine-readable syntax (as with Javadoc).
@@ -39,7 +40,7 @@
write a regular comment directly preceding its declaration,
with no intervening blank line.
Godoc will then present that comment as text alongside the item it documents.
-For example, this is the documentation for the `fmt` package's [[https://golang.org/pkg/fmt/#Fprint][`Fprint`]] function:
+For example, this is the documentation for the `fmt` package's [`Fprint`](https://golang.org/pkg/fmt/#Fprint) function:
// Fprint formats using the default formats for its operands and writes to w.
// Spaces are added between operands when neither is a string.
@@ -54,29 +55,29 @@
such as when they extract the first line or sentence.
Comments on package declarations should provide general package documentation.
-These comments can be short, like the [[https://golang.org/pkg/sort/][`sort`]]
+These comments can be short, like the [`sort`](https://golang.org/pkg/sort/)
package's brief description:
// Package sort provides primitives for sorting slices and user-defined
// collections.
package sort
-They can also be detailed like the [[https://golang.org/pkg/encoding/gob/][gob package]]'s overview.
+They can also be detailed like the [gob package](https://golang.org/pkg/encoding/gob/)'s overview.
That package uses another convention for packages that need large amounts
of introductory documentation:
the package comment is placed in its own file,
-[[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]],
+[doc.go](https://golang.org/src/pkg/encoding/gob/doc.go),
which contains only those comments and a package clause.
When writing package comments of any size,
-keep in mind that their first sentence will appear in godoc's [[https://golang.org/pkg/][package list]].
+keep in mind that their first sentence will appear in godoc's [package list](https://golang.org/pkg/).
Comments that are not adjacent to a top-level declaration are omitted from godoc's output,
with one notable exception.
Top-level comments that begin with the word `"BUG(who)”` are recognized as known bugs,
and included in the "Bugs” section of the package documentation.
The "who” part should be the user name of someone who could provide more information.
-For example, this is a known issue from the [[https://golang.org/pkg/bytes/#pkg-note-BUG][bytes package]]:
+For example, this is a known issue from the [bytes package](https://golang.org/pkg/bytes/#pkg-note-BUG):
// BUG(r): The rule Title uses for word boundaries does not handle Unicode punctuation properly.
@@ -86,17 +87,17 @@
To signal that an identifier should not be used, add a paragraph to its doc
comment that begins with "Deprecated:" followed by some information about the
deprecation.
-There are a few examples [[https://golang.org/search?q=Deprecated:][in the standard library]].
+There are a few examples [in the standard library](https://golang.org/search?q=Deprecated:).
There are a few formatting rules that Godoc uses when converting comments to HTML:
-- Subsequent lines of text are considered part of the same paragraph;
- you must leave a blank line to separate paragraphs.
+ - Subsequent lines of text are considered part of the same paragraph;
+ you must leave a blank line to separate paragraphs.
-- Pre-formatted text must be indented relative to the surrounding comment
- text (see gob's [[https://golang.org/src/pkg/encoding/gob/doc.go][doc.go]] for an example).
+ - Pre-formatted text must be indented relative to the surrounding comment
+ text (see gob's [doc.go](https://golang.org/src/pkg/encoding/gob/doc.go) for an example).
-- URLs will be converted to HTML links; no special markup is necessary.
+ - URLs will be converted to HTML links; no special markup is necessary.
Note that none of these rules requires you to do anything out of the ordinary.
@@ -108,5 +109,5 @@
Any Go packages installed inside `$GOROOT/src/pkg` and any `GOPATH` work
spaces will already be accessible via godoc's command-line and HTTP interfaces,
and you can specify additional paths for indexing via the `-path` flag or
-just by running `"godoc`."` in the source directory.
-See the [[https://golang.org/cmd/godoc/][godoc documentation]] for more details.
+just by running `"godoc ."` in the source directory.
+See the [godoc documentation](https://golang.org/cmd/godoc/) for more details.
diff --git a/content/gopher.article b/content/gopher.article
index 3084655..edb1a18 100644
--- a/content/gopher.article
+++ b/content/gopher.article
@@ -1,12 +1,13 @@
-The Go Gopher
+# The Go Gopher
24 Mar 2014
Tags: gopher
+Summary: The Go gopher is an iconic mascot and one of the most distinctive features of the Go project. In this post we'll talk about its origins, evolution, and behavior.
Rob Pike
Andrew Gerrand
-* The Go Gopher
+##
.image gopher/header.jpg
@@ -15,20 +16,20 @@
evolution, and behavior.
About 15 years ago—long before the Go project—the gopher first appeared as
-a promotion for the [[https://wfmu.org/][WFMU radio station]] in New Jersey.
-[[http://reneefrench.blogspot.com][Renee French]] was commissioned to
+a promotion for the [WFMU radio station](https://wfmu.org/) in New Jersey.
+[Renee French](http://reneefrench.blogspot.com) was commissioned to
design a T-shirt for an annual fundraiser and out came the gopher.
.image gopher/wfmu.jpg
The gopher next made an appearance at Bell Labs,
-as Bob Flandrena's [[https://research.swtch.com/face][avatar]] in the Bell Labs mail system.
+as Bob Flandrena's [avatar](https://research.swtch.com/face) in the Bell Labs mail system.
Other Renee drawings became avatars for ken, r, rsc, and others.
-(Of course, Peter Weinberger's was his own [[http://spinroot.com/pico/pjw.html][iconic face]].)
+(Of course, Peter Weinberger's was his own [iconic face](http://spinroot.com/pico/pjw.html).)
.image gopher/avatars.png
-Another Bell Labs activity led to Renee creating [[https://9p.io/plan9/glenda.html][Glenda]],
+Another Bell Labs activity led to Renee creating [Glenda](https://9p.io/plan9/glenda.html),
the Plan 9 mascot, a distant cousin of the WFMU gopher.
.image gopher/glenda.png
@@ -45,9 +46,9 @@
(The gopher has no name, and is called just the "Go gopher".)
-For the [[https://www.youtube.com/watch?v=-i0hat7pdpk#t=24m40s][launch]]
-of the [[https://developers.google.com/appengine/docs/go][Go App Engine runtime]] at
-Google I/O 2011 we engaged [[http://squishable.com][Squishable]] to manufacture the plush gophers.
+For the [launch](https://www.youtube.com/watch?v=-i0hat7pdpk#t=24m40s)
+of the [Go App Engine runtime](https://developers.google.com/appengine/docs/go) at
+Google I/O 2011 we engaged [Squishable](http://squishable.com) to manufacture the plush gophers.
This was the first time the gopher was colored blue and appeared in three dimensions.
The first prototype was kinda hairy:
@@ -58,7 +59,7 @@
.image gopher/plush.jpg
Around the same time, Renee roughed out a gopher in clay.
-This inspired a refined sculpture that became a vinyl figurine made by [[http://www.kidrobot.com/][Kidrobot]].
+This inspired a refined sculpture that became a vinyl figurine made by [Kidrobot](http://www.kidrobot.com/).
The vinyls were first distributed at OSCON 2011.
.image gopher/vinyl.jpg
@@ -70,7 +71,7 @@
The Go gopher is a character; a unique creation. Not any old gopher, just as Snoopy is not any old cartoon dog.
-The [[https://golang.org/doc/gopher/][gopher images]] are Creative Commons
+The [gopher images](https://golang.org/doc/gopher/) are Creative Commons
Attribution 3.0 licensed.
That means you can play with the images but you must give credit to their
creator (Renee French) wherever they are used.
@@ -87,14 +88,14 @@
accept no substitutes!
But how can you get one? Their natural habitat is near high concentrations of Go programmers,
and their worldwide population is growing.
-They may be purchased from the [[https://www.googlemerchandisestore.com/Google+Redesign/Fun/Go+Gopher+Blue+Squishable.axd?cid=1399][Google Store]],
+They may be purchased from the [Google Store](https://www.googlemerchandisestore.com/Google+Redesign/Fun/Go+Gopher+Blue+Squishable.axd?cid=1399),
although the supply can be irregular.
-(These elusive creatures have been spotted in all [[http://www.flickr.com/photos/pinkhamsters/sets/72157627910426064/][kinds]] [[https://plus.google.com/107966629974328136037/posts/TcFA9zHzQB8][of]] [[https://twitter.com/goroutine][places]].)
+(These elusive creatures have been spotted in all [kinds](http://www.flickr.com/photos/pinkhamsters/sets/72157627910426064/) [of](https://plus.google.com/107966629974328136037/posts/TcFA9zHzQB8) [places](https://twitter.com/goroutine).)
Perhaps the best way to get a gopher is to catch one in the wild at a Go conference.
-There are two big chances this year: [[http://gophercon.com/][GopherCon]] (Denver,
-April 24-26) and [[http://dotgo.eu][dotGo]] (Paris, October 10).
+There are two big chances this year: [GopherCon](http://gophercon.com/) (Denver,
+April 24-26) and [dotGo](http://dotgo.eu) (Paris, October 10).
.image gopher/portrait.jpg
-_(Photo_by_ [[https://twitter.com/noahhlo/status/437395572081688576][_Noah_Lorang_]]_.)_
+_(Photo by_ [_Noah Lorang_](https://twitter.com/noahhlo/status/437395572081688576)_.)_
diff --git a/content/gopherchina.article b/content/gopherchina.article
index bae456e..bbe0690 100644
--- a/content/gopherchina.article
+++ b/content/gopherchina.article
@@ -1,21 +1,22 @@
-GopherChina Trip Report
+# GopherChina Trip Report
1 Jul 2015
Tags: community, china
+Summary: We have known for some time that Go is more popular in China than in any other country. According to Google Trends, most [searches for the term “golang”](https://www.google.com/trends/explore#q=golang) come from The People’s Republic than anywhere else. [Others](http://herman.asia/why-is-go-popular-in-china) have speculated on the same observation, yet so far we have had [sparse concrete information](https://news.ycombinator.com/item?id=8872400) about the phenomenon.
Robert Griesemer
gri@golang.org
-* Introduction
+##
We have known for some time that Go is more popular in China than in any other
country.
-According to Google Trends, most [[https://www.google.com/trends/explore#q=golang][searches for the term “golang”]] come from The People’s Republic than anywhere else.
-[[http://herman.asia/why-is-go-popular-in-china][Others]] have speculated on
+According to Google Trends, most [searches for the term “golang”](https://www.google.com/trends/explore#q=golang) come from The People’s Republic than anywhere else.
+[Others](http://herman.asia/why-is-go-popular-in-china) have speculated on
the same observation, yet so far we have had
-[[https://news.ycombinator.com/item?id=8872400][sparse concrete information]]
+[sparse concrete information](https://news.ycombinator.com/item?id=8872400)
about the phenomenon.
-The first Go conference in China, [[http://gopherchina.org/][GopherChina]],
+The first Go conference in China, [GopherChina](http://gopherchina.org/),
seemed like an excellent opportunity to explore the situation by putting some
Western Gopher feet on Chinese ground. An actual invitation made it real and I
decided to accept and give a presentation about gofmt’s impact on software
@@ -23,23 +24,23 @@
.image gopherchina/image04.jpg
-_Hello,_Shanghai!_
+_Hello, Shanghai!_
The conference took place over an April weekend in Shanghai, in the
-[[https://www.google.com/maps/place/Puruan+Bldg,+Pudong,+Shanghai,+China][Puruan Building]]
+[Puruan Building](https://www.google.com/maps/place/Puruan+Bldg,+Pudong,+Shanghai,+China)
of the Shanghai Pudong Software Park, easily reachable by subway within an hour
or less from Shanghai’s more central parts.
-Modelled after [[http://www.gophercon.com][GopherCon]], the conference was
+Modelled after [GopherCon](http://www.gophercon.com), the conference was
single-track, with all talks presented in a conference room that fit about 400
attendees.
-It was organized by volunteers, lead by [[https://github.com/astaxie][Asta Xie]],
+It was organized by volunteers, lead by [Asta Xie](https://github.com/astaxie),
and with robust sponsorship from major industry names. According to the
organizers, many more people were hoping to attend than could be accommodated
due to space constraints.
.image gopherchina/image01.jpg
-_The_welcoming_committee_with_Asta_Xie_(2nd_from_left),_the_primary_organizer._
+_The welcoming committee with Asta Xie (2nd from left), the primary organizer._
Each attendee received a bag filled with the obligatory GopherChina t-shirt,
various sponsor-related informational brochures, stickers, and the occasional
@@ -49,7 +50,7 @@
.image gopherchina/image05.jpg
-_Go_books!_
+_Go books!_
On first impression, the average attendee seemed pretty young, which made for
an enthusiastic crowd, and the event appeared well run.
@@ -69,9 +70,9 @@
As expected, many of the presentations were about web services, backends for
mobile applications, and so on. Some of the systems appear to be huge by any
measure.
-For instance, a talk by [[http://gopherchina.org/user/zhouyang][Yang Zhou]]
+For instance, a talk by [Yang Zhou](http://gopherchina.org/user/zhouyang)
described a large-scale internal messaging system, used by
-[[http://www.360.cn/][Qihoo 360]], a major Chinese software firm, all written
+[Qihoo 360](http://www.360.cn/), a major Chinese software firm, all written
in Go. The presentation discussed how his team managed to reduce an original
heap size of 69GB (!) and the resulting long GC pauses of 3-6s to more
manageable numbers, and how they run millions of goroutines per machine, on a
@@ -80,15 +81,15 @@
.image gopherchina/image03.jpg
-_Packed_conference_room_on_Saturday._
+_Packed conference room on Saturday._
-In another presentation, [[http://gopherchina.org/user/guofeng][Feng Guo]] from
-[[https://www.daocloud.io/][DaoCloud]] talked about how they use Go in their
+In another presentation, [Feng Guo](http://gopherchina.org/user/guofeng) from
+[DaoCloud](https://www.daocloud.io/) talked about how they use Go in their
company for what they call the “continuous delivery” of applications. DaoCloud
takes care of automatically moving software hosted on GitHub (and Chinese
equivalents) to the cloud. A software developer simply pushes a new version on
GitHub and DaoCloud takes care of the rest: running tests,
-[[https://www.docker.com/][Dockerizing]] it, and shipping it using your
+[Dockerizing](https://www.docker.com/) it, and shipping it using your
preferred cloud service provider.
Several speakers were from well-recognized major software firms (I showed the
@@ -100,7 +101,7 @@
Not being an expert in web services myself, in my presentation I veered off the
general conference theme a bit by talking about
-[[https://golang.org/cmd/gofmt/][gofmt]] and how its widespread use has started
+[gofmt](https://golang.org/cmd/gofmt/) and how its widespread use has started
to shape expectations not just for Go but other languages as well.
I presented in English but had my slides translated to Mandarin beforehand. Due
to the significant language barrier I wasn’t expecting too many questions on my
@@ -110,11 +111,11 @@
.image gopherchina/image06.jpg
-_No_social_event_in_China_is_complete_without_fantastic_food._
+_No social event in China is complete without fantastic food._
A couple of days after the conference I visited the 4-year-old startup company
-[[http://www.qiniu.com/][Qiniu]] (“Seven Bulls”), at the invitation of its
-[[http://gopherchina.org/user/xushiwei][CEO]] Wei Hsu, facilitated and
+[Qiniu](http://www.qiniu.com/) (“Seven Bulls”), at the invitation of its
+[CEO](http://gopherchina.org/user/xushiwei) Wei Hsu, facilitated and
translated with the help of Asta Xie. Qiniu is a cloud-based storage provider
for mobile applications; Wei Hsu presented at the conference and also happens
to be the author of one of the first Chinese books on Go (the leftmost one in
@@ -123,7 +124,7 @@
.image gopherchina/image02.jpg
.image gopherchina/image00.jpg
-_Qiniu_lobby,_engineering._
+_Qiniu lobby, engineering._
Qiniu is an extremely successful all-Go shop, with about 160 employees, serving
over 150,000 companies and developers, storing over 50 Billion files, and
@@ -144,11 +145,11 @@
According to Asta Xie, Qiniu is just one of many Go shops in the PRC. Large
companies such as Alibaba, Baidu, Tencent, and Weibo, are now all using Go in
one form or another. He pointed out that while Shanghai and neighboring cities
-like [[https://www.google.com/maps/place/Suzhou,+Jiangsu,+China][Suzhou]] are
+like [Suzhou](https://www.google.com/maps/place/Suzhou,+Jiangsu,+China) are
high-tech centres, even more software developers are found in the Beijing area.
For 2016, Asta hopes to organize a larger (1000, perhaps 1500 people)
successor conference in Beijing.
It appears that we have found the Go users in China: They are everywhere!
-_Some_of_the_GopherChina_materials,_including_videos,_are_now_available_alongside_Go_coursework_on_a_ [[http://www.imooc.com/view/407][_3rd_party_site_]].
+_Some of the GopherChina materials, including videos, are now available alongside Go coursework on a_ [_3rd party site_](http://www.imooc.com/view/407).
diff --git a/content/gophercon.article b/content/gophercon.article
index e7d8931..c0f0a47 100644
--- a/content/gophercon.article
+++ b/content/gophercon.article
@@ -1,12 +1,13 @@
-GopherCon 2014 Wrap Up
+# GopherCon 2014 Wrap Up
28 May 2014
+Summary: In April this year 700 gophers descended upon Denver to attend [GopherCon](http://www.gophercon.com/), the world's first large-scale Go conference, organized entirely by the community. The three day event featured 24 talks and one panel discussion in a single track over two days, followed by an informal "hack day" full of code, conversation, and more than 4 hours (!) of lightning talks.
Andrew Gerrand
adg@golang.org
-* Introduction
+##
-In April this year 700 gophers descended upon Denver to attend [[http://www.gophercon.com/][GopherCon]],
+In April this year 700 gophers descended upon Denver to attend [GopherCon](http://www.gophercon.com/),
the world's first large-scale Go conference, organized entirely by the community.
The three day event featured 24 talks and one panel discussion in a single track over two days,
followed by an informal "hack day" full of code, conversation,
@@ -14,24 +15,24 @@
.image gophercon/image02.jpg
-A [[http://confreaks.com/events/gophercon2014][complete set of video recordings]] is now available
-(the [[https://github.com/gophercon/2014-talks][slides are here]]).
+A [complete set of video recordings](http://confreaks.com/events/gophercon2014) is now available
+(the [slides are here](https://github.com/gophercon/2014-talks)).
Two keynotes framed the conference:
-- Rob Pike's opening talk [[https://www.youtube.com/watch?v=VoS7DsT1rdM]["Hello, Gophers!"]] ([[https://talks.golang.org/2014/hellogophers.slide][slides]])
- discusses the history of Go by walking through two of the first Go programs.
-- Andrew Gerrand's closing talk [[https://www.youtube.com/watch?v=dKGmK_Z1Zl0]["Go for gophers"]] ([[https://talks.golang.org/2014/go4gophers.slide][slides]]) explains
- the Go design philosophy through the lens of his personal experience learning the language.
+ - Rob Pike's opening talk ["Hello, Gophers!"](https://www.youtube.com/watch?v=VoS7DsT1rdM) ([slides](https://talks.golang.org/2014/hellogophers.slide))
+ discusses the history of Go by walking through two of the first Go programs.
+ - Andrew Gerrand's closing talk ["Go for gophers"](https://www.youtube.com/watch?v=dKGmK_Z1Zl0) ([slides](https://talks.golang.org/2014/go4gophers.slide)) explains
+ the Go design philosophy through the lens of his personal experience learning the language.
One talk that resonated with members of the Go team was Peter Bourgon's
-[[https://www.youtube.com/watch?v=Y1-RLAl7iOI]["Best practices for Production Environments"]]
-([[http://peter.bourgon.org/go-in-production/][notes]]).
+["Best practices for Production Environments"](https://www.youtube.com/watch?v=Y1-RLAl7iOI)
+([notes](http://peter.bourgon.org/go-in-production/)).
From deployment to dependency management,
it answers many frequently asked questions about Go use in the real world
and is a must-see for anyone serious about building systems in Go.
-But, really, you should just [[http://confreaks.com/events/gophercon2014][watch them all]].
+But, really, you should just [watch them all](http://confreaks.com/events/gophercon2014).
They're great.
The Go Gopher was everywhere.
@@ -40,7 +41,7 @@
.image gophercon/image01.jpg
-The gopher was also seen wearing a cape on the side of the incredible [[https://coreos.com/][CoreOS]] bus:
+The gopher was also seen wearing a cape on the side of the incredible [CoreOS](https://coreos.com/) bus:
.image gophercon/image00.jpg
@@ -55,4 +56,4 @@
in to make the event such a success.
We look forward to GopherCon 2015, which promises to be bigger and better still.
-But if you really can't wait, we'll see you at [[http://www.dotgo.eu/][dotGo]] in Paris on the 10th of October!
+But if you really can't wait, we'll see you at [dotGo](http://www.dotgo.eu/) in Paris on the 10th of October!
diff --git a/content/gophercon2015.article b/content/gophercon2015.article
index e41bd70..1176eb3 100644
--- a/content/gophercon2015.article
+++ b/content/gophercon2015.article
@@ -1,10 +1,11 @@
-GopherCon 2015 Roundup
+# GopherCon 2015 Roundup
28 Jul 2015
Tags: conference, report, gopher
+Summary: A few weeks ago, Go programmers from around the world descended on Denver, Colorado for GopherCon 2015. The two-day, single-track conference attracted more than 1,250 attendees—nearly double last year's number—and featured 22 talks presented by Go community members.
Andrew Gerrand
-* Introduction
+##
A few weeks ago, Go programmers from around the world descended on Denver,
Colorado for GopherCon 2015. The two-day, single-track conference attracted
@@ -17,57 +18,57 @@
Today the organizers have posted the videos online so you can now enjoy the
conference from afar:
-[[http://gophercon.com/schedule/8july/][Day 1]]:
+[Day 1](http://gophercon.com/schedule/8july/):
-- Go, Open Source, Community — Russ Cox ([[https://www.youtube.com/watch?v=XvZOdpd_9tc][video]])
- ([[https://blog.golang.org/open-source][text]])
-- Go kit: A Standard Library for Distributed Programming — Peter Bourgon
- ([[https://www.youtube.com/watch?v=1AjaZi4QuGo][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Go%20kit/go-kit.pdf][slides]])
-- Delve Into Go — Derek Parker ([[https://www.youtube.com/watch?v=InG72scKPd4][video]])
- ([[http://go-talks.appspot.com/github.com/derekparker/talks/gophercon-2015/delve-into-go.slide][slides]])
-- How a complete beginner learned Go as her first backend language in 5
- weeks — Audrey Lim ([[https://www.youtube.com/watch?v=fZh8uCInEfw][video]])
- ([[https://github.com/gophercon/2015-talks/blob/master/Audrey%20Lim%20-%20How%20a%20Complete%20Beginner%20Picked%20Up%20Go%20as%20Her%20First%20Backend%20Language%20in%205%20weeks/audreylim_slides.pdf][slides]])
-- A Practical Guide to Preventing Deadlocks and Leaks in Go — Richard
- Fliam ([[https://www.youtube.com/watch?v=3EW1hZ8DVyw][video]])
-- Go GC: Solving the Latency Problem — Rick Hudson ([[https://www.youtube.com/watch?v=aiv1JOfMjm0][video]])
- ([[https://talks.golang.org/2015/go-gc.pdf][slides]])
-- Simplicity and Go — Katherine Cox-Buday ([[https://www.youtube.com/watch?v=S6mEo_FHZ5Y][video]])
- ([[https://github.com/gophercon/2015-talks/blob/master/Katherine%20Cox-Buday:%20Simplicity%20%26%20Go/Simplicity%20%26%20Go.pdf][slides]])
-- Rebuilding Parse.com in Go - an opinionated rewrite — Abhishek Kona
- ([[https://www.youtube.com/watch?v=_f9LS-OWfeA][video]]) ([[https://github.com/gophercon/2015-talks/blob/master/Abhishek%20Kona%20Rewriting%20Parse%20in%20GO/myslides.pdf][slides]])
-- Prometheus: Designing and Implementing a Modern Monitoring Solution in
- Go — Björn Rabenstein ([[https://www.youtube.com/watch?v=1V7eJ0jN8-E][video]])
- ([[https://github.com/gophercon/2015-talks/blob/master/Bj%C3%B6rn%20Rabenstein%20-%20Prometheus/slides.pdf][slides]])
-- What Could Go Wrong? — Kevin Cantwell ([[https://www.youtube.com/watch?v=VC3QXZ-x5yI][video]])
-- The Roots of Go — Baishampayan Ghose ([[https://www.youtube.com/watch?v=0hPOopcJ8-E][video]])
- ([[https://speakerdeck.com/bg/the-roots-of-go][slides]])
+ - Go, Open Source, Community — Russ Cox ([video](https://www.youtube.com/watch?v=XvZOdpd_9tc))
+ ([text](https://blog.golang.org/open-source))
+ - Go kit: A Standard Library for Distributed Programming — Peter Bourgon
+ ([video](https://www.youtube.com/watch?v=1AjaZi4QuGo)) ([slides](https://github.com/gophercon/2015-talks/blob/master/Go%20kit/go-kit.pdf))
+ - Delve Into Go — Derek Parker ([video](https://www.youtube.com/watch?v=InG72scKPd4))
+ ([slides](http://go-talks.appspot.com/github.com/derekparker/talks/gophercon-2015/delve-into-go.slide))
+ - How a complete beginner learned Go as her first backend language in 5
+ weeks — Audrey Lim ([video](https://www.youtube.com/watch?v=fZh8uCInEfw))
+ ([slides](https://github.com/gophercon/2015-talks/blob/master/Audrey%20Lim%20-%20How%20a%20Complete%20Beginner%20Picked%20Up%20Go%20as%20Her%20First%20Backend%20Language%20in%205%20weeks/audreylim_slides.pdf))
+ - A Practical Guide to Preventing Deadlocks and Leaks in Go — Richard
+ Fliam ([video](https://www.youtube.com/watch?v=3EW1hZ8DVyw))
+ - Go GC: Solving the Latency Problem — Rick Hudson ([video](https://www.youtube.com/watch?v=aiv1JOfMjm0))
+ ([slides](https://talks.golang.org/2015/go-gc.pdf))
+ - Simplicity and Go — Katherine Cox-Buday ([video](https://www.youtube.com/watch?v=S6mEo_FHZ5Y))
+ ([slides](https://github.com/gophercon/2015-talks/blob/master/Katherine%20Cox-Buday:%20Simplicity%20%26%20Go/Simplicity%20%26%20Go.pdf))
+ - Rebuilding Parse.com in Go - an opinionated rewrite — Abhishek Kona
+ ([video](https://www.youtube.com/watch?v=_f9LS-OWfeA)) ([slides](https://github.com/gophercon/2015-talks/blob/master/Abhishek%20Kona%20Rewriting%20Parse%20in%20GO/myslides.pdf))
+ - Prometheus: Designing and Implementing a Modern Monitoring Solution in
+ Go — Björn Rabenstein ([video](https://www.youtube.com/watch?v=1V7eJ0jN8-E))
+ ([slides](https://github.com/gophercon/2015-talks/blob/master/Bj%C3%B6rn%20Rabenstein%20-%20Prometheus/slides.pdf))
+ - What Could Go Wrong? — Kevin Cantwell ([video](https://www.youtube.com/watch?v=VC3QXZ-x5yI))
+ - The Roots of Go — Baishampayan Ghose ([video](https://www.youtube.com/watch?v=0hPOopcJ8-E))
+ ([slides](https://speakerdeck.com/bg/the-roots-of-go))
-[[http://gophercon.com/schedule/9july/][Day 2]]:
+[Day 2](http://gophercon.com/schedule/9july/):
-- The Evolution of Go — Robert Griesemer ([[https://www.youtube.com/watch?v=0ReKdcpNyQg][video]])
- ([[https://talks.golang.org/2015/gophercon-goevolution.slide][slides]])
-- Static Code Analysis Using SSA — Ben Johnson ([[https://www.youtube.com/watch?v=D2-gaMvWfQY][video]])
- ([[https://speakerdeck.com/benbjohnson/static-code-analysis-using-ssa][slides]])
-- Go on Mobile — Hana Kim ([[https://www.youtube.com/watch?v=sQ6-HyPxHKg][video]])
- ([[https://talks.golang.org/2015/gophercon-go-on-mobile.slide][slides]])
-- Go Dynamic Tools — Dmitry Vyukov ([[https://www.youtube.com/watch?v=a9xrxRsIbSU][video]])
- ([[https://talks.golang.org/2015/dynamic-tools.slide][slides]])
-- Embrace the Interface — Tomás Senart ([[https://www.youtube.com/watch?v=xyDkyFjzFVc][video]])
- ([[https://github.com/gophercon/2015-talks/blob/master/Tom%C3%A1s%20Senart%20-%20Embrace%20the%20Interface/ETI.pdf][slides]])
-- Uptime: Building Resilient Services with Go — Blake Caldwell ([[https://www.youtube.com/watch?v=PyBJQA4clfc][video]])
- ([[https://github.com/gophercon/2015-talks/blob/master/Blake%20Caldwell%20-%20Uptime:%20Building%20Resilient%20Services%20with%20Go/2015-GopherCon-Talk-Uptime.pdf][slides]])
-- Cayley: Building a Graph Database — Barak Michener ([[https://www.youtube.com/watch?v=-9kWbPmSyCI][video]])
- ([[https://github.com/gophercon/2015-talks/blob/master/Barak%20Michener%20-%20Cayley:%20Building%20a%20Graph%20Database/Cayley%20-%20Building%20a%20Graph%20Database.pdf][slides]])
-- Code Generation For The Sake Of Consistency — Sarah Adams ([[https://www.youtube.com/watch?v=kGAgHwfjg1s][video]])
-- The Many Faces of Struct Tags — Sam Helman and Kyle Erf ([[https://www.youtube.com/watch?v=_SCRvMunkdA][video]])
- ([[https://github.com/gophercon/2015-talks/blob/master/Sam%20Helman%20%26%20Kyle%20Erf%20-%20The%20Many%20Faces%20of%20Struct%20Tags/StructTags.pdf][slides]])
-- Betting the Company on Go and Winning — Kelsey Hightower ([[https://www.youtube.com/watch?v=wqVbLlHqAeY][video]])
-- How Go Was Made — Andrew Gerrand ([[https://www.youtube.com/watch?v=0ht89TxZZnk][video]])
- ([[https://talks.golang.org/2015/how-go-was-made.slide][slides]])
+ - The Evolution of Go — Robert Griesemer ([video](https://www.youtube.com/watch?v=0ReKdcpNyQg))
+ ([slides](https://talks.golang.org/2015/gophercon-goevolution.slide))
+ - Static Code Analysis Using SSA — Ben Johnson ([video](https://www.youtube.com/watch?v=D2-gaMvWfQY))
+ ([slides](https://speakerdeck.com/benbjohnson/static-code-analysis-using-ssa))
+ - Go on Mobile — Hana Kim ([video](https://www.youtube.com/watch?v=sQ6-HyPxHKg))
+ ([slides](https://talks.golang.org/2015/gophercon-go-on-mobile.slide))
+ - Go Dynamic Tools — Dmitry Vyukov ([video](https://www.youtube.com/watch?v=a9xrxRsIbSU))
+ ([slides](https://talks.golang.org/2015/dynamic-tools.slide))
+ - Embrace the Interface — Tomás Senart ([video](https://www.youtube.com/watch?v=xyDkyFjzFVc))
+ ([slides](https://github.com/gophercon/2015-talks/blob/master/Tom%C3%A1s%20Senart%20-%20Embrace%20the%20Interface/ETI.pdf))
+ - Uptime: Building Resilient Services with Go — Blake Caldwell ([video](https://www.youtube.com/watch?v=PyBJQA4clfc))
+ ([slides](https://github.com/gophercon/2015-talks/blob/master/Blake%20Caldwell%20-%20Uptime:%20Building%20Resilient%20Services%20with%20Go/2015-GopherCon-Talk-Uptime.pdf))
+ - Cayley: Building a Graph Database — Barak Michener ([video](https://www.youtube.com/watch?v=-9kWbPmSyCI))
+ ([slides](https://github.com/gophercon/2015-talks/blob/master/Barak%20Michener%20-%20Cayley:%20Building%20a%20Graph%20Database/Cayley%20-%20Building%20a%20Graph%20Database.pdf))
+ - Code Generation For The Sake Of Consistency — Sarah Adams ([video](https://www.youtube.com/watch?v=kGAgHwfjg1s))
+ - The Many Faces of Struct Tags — Sam Helman and Kyle Erf ([video](https://www.youtube.com/watch?v=_SCRvMunkdA))
+ ([slides](https://github.com/gophercon/2015-talks/blob/master/Sam%20Helman%20%26%20Kyle%20Erf%20-%20The%20Many%20Faces%20of%20Struct%20Tags/StructTags.pdf))
+ - Betting the Company on Go and Winning — Kelsey Hightower ([video](https://www.youtube.com/watch?v=wqVbLlHqAeY))
+ - How Go Was Made — Andrew Gerrand ([video](https://www.youtube.com/watch?v=0ht89TxZZnk))
+ ([slides](https://talks.golang.org/2015/how-go-was-made.slide))
-The [[http://gophercon.com/schedule/10july/][hack day]] was also a ton of fun,
-with hours of [[https://www.youtube.com/playlist?list=PL2ntRZ1ySWBeHqlHM8DmvS8axgbrpvF9b][lightning talks]]
+The [hack day](http://gophercon.com/schedule/10july/) was also a ton of fun,
+with hours of [lightning talks](https://www.youtube.com/playlist?list=PL2ntRZ1ySWBeHqlHM8DmvS8axgbrpvF9b)
and a range of activities from programming robots
to a Magic: the Gathering tournament.
diff --git a/content/gophergala.article b/content/gophergala.article
index af8d477..769e822 100644
--- a/content/gophergala.article
+++ b/content/gophergala.article
@@ -1,23 +1,24 @@
-The Gopher Gala is the first worldwide Go hackathon
+# The Gopher Gala is the first worldwide Go hackathon
7 Jan 2015
+Summary: The [Gopher Gala](http://gophergala.com/) is the first Go hackathon at a global scale and will take place from January 23rd through the 25th. The event is organized by the community, supported by the Go team, and sponsored by Google among others.
Francesc Campoy
campoy@golang.org
-* Introduction
+##
-The [[http://gophergala.com/][Gopher Gala]] is the first Go hackathon at a
+The [Gopher Gala](http://gophergala.com/) is the first Go hackathon at a
global scale and will take place from January 23rd through the 25th. The event
is organized by the community, supported by the Go team, and sponsored by
Google among others.
.image gophergala/fancygopher.jpg _ 300
-.caption _Fancy_Gopher,_by_ [[http://www.reneefrench.com/][_Renée_French_]]
+_Fancy_Gopher,_by_ [[http://www.reneefrench.com/][_Renée_French_]]
You can read about the rules of the hackathon
-[[http://gophergala.com/rules/][here]], but if you know about
-[[http://railsrumble.com/][Rails Rumble]] or
-[[http://nodeknockout.com/][Node Knockout]] you already have a pretty good idea
+[here](http://gophergala.com/rules/), but if you know about
+[Rails Rumble](http://railsrumble.com/) or
+[Node Knockout](http://nodeknockout.com/) you already have a pretty good idea
of what to expect.
During this event gophers from all around the globe will form teams to build
@@ -25,11 +26,11 @@
will vote for their favorite applications and the 20 highest voted applications
will be ranked by a jury of renowned names from the community, including some
members of the Go core team. More information on the judging phase can be found
-[[http://gophergala.com/judging/][here]].
+[here](http://gophergala.com/judging/).
And in case you needed one more reason to
-[[https://gophers.typeform.com/to/wondM5][get involved]] there will be prizes!
+[get involved](https://gophers.typeform.com/to/wondM5) there will be prizes!
"What prizes?" you ask. Well, that’s a
-[[http://gophergala.com/prizes/][secret]] until January 10th but we’re pretty
+[secret](http://gophergala.com/prizes/) until January 10th but we’re pretty
sure you won’t be disappointed.
diff --git a/content/gos-declaration-syntax.article b/content/gos-declaration-syntax.article
index bb1d18f..a6113a1 100644
--- a/content/gos-declaration-syntax.article
+++ b/content/gos-declaration-syntax.article
@@ -1,16 +1,17 @@
-Go's Declaration Syntax
+# Go's Declaration Syntax
7 Jul 2010
Tags: c, syntax, ethos
+Summary: Newcomers to Go wonder why the declaration syntax is different from the tradition established in the C family. In this post we'll compare the two approaches and explain why Go's declarations look as they do.
Rob Pike
-* Introduction
+## Introduction
Newcomers to Go wonder why the declaration syntax is different from the
tradition established in the C family.
In this post we'll compare the two approaches and explain why Go's declarations look as they do.
-* C syntax
+## C syntax
First, let's talk about C syntax. C took an unusual and clever approach
to declaration syntax.
@@ -30,7 +31,7 @@
int *p;
int a[3];
-state that p is a pointer to int because '*p' has type int,
+state that p is a pointer to int because '\*p' has type int,
and that a is an array of ints because a[3] (ignoring the particular index value,
which is punned to be the size of the array) has type int.
@@ -56,7 +57,7 @@
int (*fp)(int a, int b);
-Here, fp is a pointer to a function because if you write the expression (*fp)(a,
+Here, fp is a pointer to a function because if you write the expression (\*fp)(a,
b) you'll call a function that returns int.
What if one of fp's arguments is itself a function?
@@ -73,7 +74,7 @@
char *argv[]
so you drop the name from the middle of its declaration to construct its type.
-It's not obvious, though, that you declare something of type char *[] by
+It's not obvious, though, that you declare something of type char \*[] by
putting its name in the middle.
And look what happens to fp's declaration if you don't name the parameters:
@@ -101,7 +102,7 @@
(int)M_PI
-* Go syntax
+## Go syntax
Languages outside the C family usually use a distinct type syntax in declarations.
Although it's a separate point, the name usually comes first,
@@ -157,7 +158,7 @@
sum := func(a, b int) int { return a+b } (3, 4)
-* Pointers
+## Pointers
Pointers are the exception that proves the rule.
Notice that in arrays and slices, for instance,
@@ -167,7 +168,7 @@
var a []int
x = a[1]
-For familiarity, Go's pointers use the * notation from C,
+For familiarity, Go's pointers use the \* notation from C,
but we could not bring ourselves to make a similar reversal for pointer types.
Thus pointers work like this
@@ -179,7 +180,7 @@
var p *int
x = p*
-because that postfix * would conflate with multiplication. We could have used the Pascal ^, for example:
+because that postfix \* would conflate with multiplication. We could have used the Pascal ^, for example:
var p ^int
x = p^
@@ -191,11 +192,11 @@
[]int("hi")
-as a conversion, one must parenthesize the type if it starts with a *:
+as a conversion, one must parenthesize the type if it starts with a \*:
(*int)(nil)
-Had we been willing to give up * as pointer syntax, those parentheses would be unnecessary.
+Had we been willing to give up \* as pointer syntax, those parentheses would be unnecessary.
So Go's pointer syntax is tied to the familiar C form,
but those ties mean that we cannot break completely from using parentheses
@@ -203,7 +204,7 @@
Overall, though, we believe Go's type syntax is easier to understand than C's, especially when things get complicated.
-* Notes
+## Notes
Go's declarations read left to right. It's been pointed out that C's read in a spiral!
-See [[http://c-faq.com/decl/spiral.anderson.html][ The "Clockwise/Spiral Rule"]] by David Anderson.
+See [ The "Clockwise/Spiral Rule"](http://c-faq.com/decl/spiral.anderson.html) by David Anderson.
diff --git a/content/gothamgo.article b/content/gothamgo.article
index e5e5575..f3e4632 100644
--- a/content/gothamgo.article
+++ b/content/gothamgo.article
@@ -1,10 +1,11 @@
-GothamGo: gophers in the big apple
+# GothamGo: gophers in the big apple
9 Jan 2015
+Summary: Last November more than two hundred gophers from all across the United States got together for the first full-day Go conference in New York City.
Francesc Campoy
campoy@golang.org
-* Introduction
+##
Last November more than two hundred gophers from all across the United States
got together for the first full-day Go conference in New York City.
@@ -15,50 +16,50 @@
.image gothamgo/gothamgo.jpg _ 600
-- [[http://vimeo.com/115728346][Launching into Go]] _by_Kathy_Spardlin_ -
- a CockroachDB contributor provides pointers for people getting started with Go.
-- [[http://vimeo.com/115782573][Error Handling]] _by_ [[https://twitter.com/goinggodotnet][_Bill_Kennedy_]] -
- ideas on how to use the Go error interface.
-- [[http://vimeo.com/115776445][7 common mistakes in Go and how to avoid them]] _by_
- [[https://twitter.com/spf13][_Steve_Francia_]] - the author of some popular
- Go libraries shares his experience.
-- [[http://vimeo.com/115309491][Cancellation, Context, and Plumbing]] _by_
- [[https://twitter.com/sajma][_Sameer_Ajmani_]] - the Google NYC Go team
- lead explains how cancellation works in Go,
- and how we're retrofitting the Google code base to use it.
-- [[http://vimeo.com/115940605][Dethorning Package Management]] _by_ [[https://twitter.com/krarick][_Keith_Rarick_]] -
- the creator of godep talks about how to manage your dependencies well.
-- [[http://vimeo.com/115940590][Everything You've Always Wanted to Know About Go Web Apps (But were afraid to ask)]]
- _by_ [[https://twitter.com/markbates][_Mark_Bates_]] - a survey of Go packages
- for building web apps,
- and insights into why there are so few Go "frameworks".
-- [[http://vimeo.com/116215450][Building high-performance database applications using Aerospike]]
- _by_Chris_Stivers_ - a principal engineer at Aerospike shares his experiences
- building scalable applications.
-- [[http://vimeo.com/115307069][The state of Go on the Android platform]]
- _by_ [[https://twitter.com/davidcrawshaw][_David_Crawshaw_]] - the leader
- of the Go on mobile platforms project tells us what’s coming up and shows a working demo.
-- [[http://vimeo.com/116108566][Mutexes and Locks]] _by_ [[https://twitter.com/frazelledazzell][_Jessie_Frazelle_]] -
- a member of the Docker core team tells us about concurrency and what to
- do when things go wrong.
-- [[http://vimeo.com/115618722][Gobot.io]] _by_ [[https://twitter.com/deadprogram][_Ron_Evans_]] -
- awesome robots controlled by Go, with demos!
-- [[http://vimeo.com/114941260][Doing Go]] _by_ [[https://twitter.com/bryanl][_Bryan_Liles_]] -
- a DigitalOcean engineer delivers a hilarious comedy routine that happens to be about Go.
-- [[http://vimeo.com/115308225][Things I learned teaching Go]] _by_ [[https://twitter.com/francesc][_Francesc_Campoy_]] -
- the Developer Advocate for the Go team shares his experience teaching Go
- and some advice on how to become a better gopher.
+ - [Launching into Go](http://vimeo.com/115728346) _by Kathy Spardlin_ -
+ a CockroachDB contributor provides pointers for people getting started with Go.
+ - [Error Handling](http://vimeo.com/115782573) _by_ [_Bill Kennedy_](https://twitter.com/goinggodotnet) -
+ ideas on how to use the Go error interface.
+ - [7 common mistakes in Go and how to avoid them](http://vimeo.com/115776445) _by_
+ [_Steve Francia_](https://twitter.com/spf13) - the author of some popular
+ Go libraries shares his experience.
+ - [Cancellation, Context, and Plumbing](http://vimeo.com/115309491) _by_
+ [_Sameer Ajmani_](https://twitter.com/sajma) - the Google NYC Go team
+ lead explains how cancellation works in Go,
+ and how we're retrofitting the Google code base to use it.
+ - [Dethorning Package Management](http://vimeo.com/115940605) _by_ [_Keith Rarick_](https://twitter.com/krarick) -
+ the creator of godep talks about how to manage your dependencies well.
+ - [Everything You've Always Wanted to Know About Go Web Apps (But were afraid to ask)](http://vimeo.com/115940590)
+ _by_ [_Mark Bates_](https://twitter.com/markbates) - a survey of Go packages
+ for building web apps,
+ and insights into why there are so few Go "frameworks".
+ - [Building high-performance database applications using Aerospike](http://vimeo.com/116215450)
+ _by Chris Stivers_ - a principal engineer at Aerospike shares his experiences
+ building scalable applications.
+ - [The state of Go on the Android platform](http://vimeo.com/115307069)
+ _by_ [_David Crawshaw_](https://twitter.com/davidcrawshaw) - the leader
+ of the Go on mobile platforms project tells us what’s coming up and shows a working demo.
+ - [Mutexes and Locks](http://vimeo.com/116108566) _by_ [_Jessie Frazelle_](https://twitter.com/frazelledazzell) -
+ a member of the Docker core team tells us about concurrency and what to
+ do when things go wrong.
+ - [Gobot.io](http://vimeo.com/115618722) _by_ [_Ron Evans_](https://twitter.com/deadprogram) -
+ awesome robots controlled by Go, with demos!
+ - [Doing Go](http://vimeo.com/114941260) _by_ [_Bryan Liles_](https://twitter.com/bryanl) -
+ a DigitalOcean engineer delivers a hilarious comedy routine that happens to be about Go.
+ - [Things I learned teaching Go](http://vimeo.com/115308225) _by_ [_Francesc Campoy_](https://twitter.com/francesc) -
+ the Developer Advocate for the Go team shares his experience teaching Go
+ and some advice on how to become a better gopher.
Two more talks come from the Go meetup in New York City, which met the day before GothamGo:
-- [[http://vimeo.com/114975899][Benchmarking Go]] _by_ [[https://twitter.com/bbulkow][_Brian_Bulkowski_]] -
- the founder of Aerospike talks about profiling tools for Go and Linux,
- and micro benchmarks for goroutines, channels,
- buffers, and and other Go features.
-- [[http://vimeo.com/114736889][Go Static Analysis Tools]] _by_Alan_Donovan_ -
- a member of the Go team at Google NY gives a guided tour of several static
- analysis tools designed to help Go programmers understand,
- navigate , and refactor their code.
+ - [Benchmarking Go](http://vimeo.com/114975899) _by_ [_Brian Bulkowski_](https://twitter.com/bbulkow) -
+ the founder of Aerospike talks about profiling tools for Go and Linux,
+ and micro benchmarks for goroutines, channels,
+ buffers, and and other Go features.
+ - [Go Static Analysis Tools](http://vimeo.com/114736889) _by Alan Donovan_ -
+ a member of the Go team at Google NY gives a guided tour of several static
+ analysis tools designed to help Go programmers understand,
+ navigate , and refactor their code.
-Make sure to have a look at all of those in preparation for the [[https://fosdem.org/][FOSDEM]] Go
-devroom FOSDEM in Brussels (Belgium) and [[http://www.gophercon.in/][gophercon.in]] in Bengaluru (India).
+Make sure to have a look at all of those in preparation for the [FOSDEM](https://fosdem.org/) Go
+devroom FOSDEM in Brussels (Belgium) and [gophercon.in](http://www.gophercon.in/) in Bengaluru (India).
diff --git a/content/gouk15.article b/content/gouk15.article
index 9499358..b4f3b44 100644
--- a/content/gouk15.article
+++ b/content/gouk15.article
@@ -1,64 +1,65 @@
-GolangUK 2015
-09 Oct 2015
+# GolangUK 2015
+9 Oct 2015
Tags: conference, golanguk
+Summary: On August 21st the Go community gathered in London for the first edition of [Golang UK](https://golanguk.com). The conference featured two parallel tracks and nearly 400 gophers attended.
Francesc Campoy
-* Introduction
+##
On August 21st the Go community gathered in London for the first edition of
-[[https://golanguk.com][Golang UK]]. The conference featured two parallel
+[Golang UK](https://golanguk.com). The conference featured two parallel
tracks and nearly 400 gophers attended.
.image gouk15/gouk.jpg 300 _
-The conference started with the opening keynote by [[https://twitter.com/calavera][David Calavera]]
-called Crossing the Language Chasm ([[https://www.youtube.com/watch?v=JPVRnEZ4v_w&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-and continued with two concurrently executed [[http://golanguk.com/schedule/][tracks]].
+The conference started with the opening keynote by [David Calavera](https://twitter.com/calavera)
+called Crossing the Language Chasm ([video](https://www.youtube.com/watch?v=JPVRnEZ4v_w&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+and continued with two concurrently executed [tracks](http://golanguk.com/schedule/).
Main track:
-- Stupid Gopher Tricks,
- by [[https://twitter.com/enneff][Andrew Gerrand]]
- ([[https://www.youtube.com/watch?v=UECh7X07m6E&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Complex Concurrency Patterns in Go,
- by [[https://twitter.com/eapache][Evan Huus]]
- ([[https://www.youtube.com/watch?v=2HOO5gIgyMg&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Code Analysis [no reading required],
- by [[https://twitter.com/francesc][Francesc Campoy]]
- ([[https://www.youtube.com/watch?v=oorX84tBMqo&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Go kit: a toolkit for microservices,
- by [[https://twitter.com/peterbourgon][Peter Bourgon]]
- ([[https://www.youtube.com/watch?v=aL6sd4d4hxk&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Dependency Management Conundrum,
- by [[https://twitter.com/goinggodotnet][William Kennedy]]
- ([[https://www.youtube.com/watch?v=CdhucJShJU8&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+ - Stupid Gopher Tricks,
+ by [Andrew Gerrand](https://twitter.com/enneff)
+ ([video](https://www.youtube.com/watch?v=UECh7X07m6E&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - Complex Concurrency Patterns in Go,
+ by [Evan Huus](https://twitter.com/eapache)
+ ([video](https://www.youtube.com/watch?v=2HOO5gIgyMg&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - Code Analysis [no reading required],
+ by [Francesc Campoy](https://twitter.com/francesc)
+ ([video](https://www.youtube.com/watch?v=oorX84tBMqo&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - Go kit: a toolkit for microservices,
+ by [Peter Bourgon](https://twitter.com/peterbourgon)
+ ([video](https://www.youtube.com/watch?v=aL6sd4d4hxk&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - Dependency Management Conundrum,
+ by [William Kennedy](https://twitter.com/goinggodotnet)
+ ([video](https://www.youtube.com/watch?v=CdhucJShJU8&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
Side track:
-- Building APIs,
- by [[https://twitter.com/matryer][Mat Ryer]] ([[https://www.youtube.com/watch?v=tIm8UkSf6RA&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Building a Bank with Go,
- by [[https://twitter.com/mattheath][Matt Heath]]
- ([[https://www.youtube.com/watch?v=cFJkLfujOts&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- CockroachDB: Make Data Easy,
- by [[https://twitter.com/bendarnell][Ben Darnell]]
- ([[https://www.youtube.com/watch?v=33oqpLmQ3LE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Understanding memory allocation in Go,
- by [[https://twitter.com/DeanElbaz][Dean Elbaz]]
- ([[https://www.youtube.com/watch?v=zjoieOpy5hE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
-- Whispered Secrets,
- by [[https://twitter.com/feyeleanor][Eleanor McHugh]]
- ([[https://www.youtube.com/watch?v=ViBRx-F4Z2U&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]])
+ - Building APIs,
+ by [Mat Ryer](https://twitter.com/matryer) ([video](https://www.youtube.com/watch?v=tIm8UkSf6RA&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - Building a Bank with Go,
+ by [Matt Heath](https://twitter.com/mattheath)
+ ([video](https://www.youtube.com/watch?v=cFJkLfujOts&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - CockroachDB: Make Data Easy,
+ by [Ben Darnell](https://twitter.com/bendarnell)
+ ([video](https://www.youtube.com/watch?v=33oqpLmQ3LE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - Understanding memory allocation in Go,
+ by [Dean Elbaz](https://twitter.com/DeanElbaz)
+ ([video](https://www.youtube.com/watch?v=zjoieOpy5hE&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
+ - Whispered Secrets,
+ by [Eleanor McHugh](https://twitter.com/feyeleanor)
+ ([video](https://www.youtube.com/watch?v=ViBRx-F4Z2U&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd))
-Finally [[https://twitter.com/dgryski][Damian Gryski]]
+Finally [Damian Gryski](https://twitter.com/dgryski)
took the stage for the closing keynote
-([[https://www.youtube.com/watch?v=IiSyFc10Jj0&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd][video]]),
+([video](https://www.youtube.com/watch?v=IiSyFc10Jj0&list=PLDWZ5uzn69ezRJYeWxYNRMYebvf8DerHd)),
giving an overview of how the Go community has evolved over time and hinting
to what the future might look like.
On the day before the conference,
-[[https://twitter.com/goinggodotnet][William Kennedy]]
+[William Kennedy](https://twitter.com/goinggodotnet)
gave a full day Go workshop.
It was a great conference, so congratulations to the organizers and see you next year in London!
diff --git a/content/h2push.article b/content/h2push.article
index 87e3649..f8bc53d 100644
--- a/content/h2push.article
+++ b/content/h2push.article
@@ -1,10 +1,11 @@
-HTTP/2 Server Push
+# HTTP/2 Server Push
24 Mar 2017
Tags: http, technical
+Summary: HTTP/2 is designed to address many of the failings of HTTP/1.x. Modern web pages use many resources: HTML, stylesheets, scripts, images, and so on. In HTTP/1.x, each of these resources must be requested explicitly. This can be a slow process. The browser starts by fetching the HTML, then learns of more resources incrementally as it parses and evaluates the page. Since the server must wait for the browser to make each request, the network is often idle and underutilized.
Jaana Burcu Dogan, Tom Bergan
-* Introduction
+## Introduction
HTTP/2 is designed to address many of the failings of HTTP/1.x.
Modern web pages use many resources: HTML, stylesheets,
@@ -15,7 +16,7 @@
must wait for the browser to make each request, the network is often
idle and underutilized.
-To improve latency, HTTP/2 introduced _server_push_, which allows the
+To improve latency, HTTP/2 introduced _server push_, which allows the
server to push resources to the browser before they are explicitly
requested. A server often knows many of the additional resources a
page will need and can start pushing those resources as it responds
@@ -32,13 +33,13 @@
wait for the push to complete rather than sending a new request.
This reduces the time the browser spends waiting on the network.
-* Server Push in net/http
+## Server Push in net/http
-Go 1.8 introduced support for pushing responses from an [[https://golang.org/pkg/net/http/#Server][`http.Server`]].
+Go 1.8 introduced support for pushing responses from an [`http.Server`](https://golang.org/pkg/net/http/#Server).
This feature is available if the running server is an HTTP/2 server
and the incoming connection uses HTTP/2. In any HTTP handler,
you can assert if the http.ResponseWriter supports server push by checking
-if it implements the new [[https://golang.org/pkg/net/http/#Pusher][`http.Pusher`]] interface.
+if it implements the new [`http.Pusher`](https://golang.org/pkg/net/http/#Pusher) interface.
For example, if the server knows that `app.js` will be required to
render the page, the handler can initiate a push if `http.Pusher`
@@ -60,13 +61,13 @@
$ go get golang.org/x/blog/content/h2push/server
-If you run the server and load [[https://localhost:8080][https://localhost:8080]],
+If you run the server and load [https://localhost:8080](https://localhost:8080),
your browser's developer tools should show that `app.js` and
`style.css` were pushed by the server.
.image h2push/networktimeline.png _ 605
-* Start Your Pushes Before You Respond
+## Start Your Pushes Before You Respond
It's a good idea to call the Push method before sending any bytes
of the response. Otherwise it is possible to accidentally generate
@@ -78,12 +79,12 @@
<link rel="stylesheet" href="a.css">...
Then you call Push("a.css", nil). The browser may parse this fragment
-of HTML before it receives your PUSH_PROMISE, in which case the browser
+of HTML before it receives your PUSH\_PROMISE, in which case the browser
will send a request for `a.css` in addition to receiving your
`PUSH_PROMISE`. Now the server will generate two responses for `a.css`.
Calling Push before writing the response avoids this possibility entirely.
-* When To Use Server Push
+## When To Use Server Push
Consider using server push any time your network link is idle.
Just finished sending the HTML for your web app? Don't waste time waiting,
@@ -104,17 +105,17 @@
The following links make for good supplemental reading:
-- [[https://calendar.perfplanet.com/2016/http2-push-the-details/][HTTP/2 Push: The Details]]
-- [[https://www.igvita.com/2013/06/12/innovating-with-http-2.0-server-push/][Innovating with HTTP/2 Server Push]]
-- [[https://github.com/h2o/h2o/issues/421][Cache-Aware Server Push in H2O]]
-- [[https://developers.google.com/web/fundamentals/performance/prpl-pattern/][The PRPL Pattern]]
-- [[https://docs.google.com/document/d/1K0NykTXBbbbTlv60t5MyJvXjqKGsCVNYHyLEXIxYMv0][Rules of Thumb for HTTP/2 Push]]
-- [[https://tools.ietf.org/html/rfc7540#section-8.2][Server Push in the HTTP/2 spec]]
+ - [HTTP/2 Push: The Details](https://calendar.perfplanet.com/2016/http2-push-the-details/)
+ - [Innovating with HTTP/2 Server Push](https://www.igvita.com/2013/06/12/innovating-with-http-2.0-server-push/)
+ - [Cache-Aware Server Push in H2O](https://github.com/h2o/h2o/issues/421)
+ - [The PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/)
+ - [Rules of Thumb for HTTP/2 Push](https://docs.google.com/document/d/1K0NykTXBbbbTlv60t5MyJvXjqKGsCVNYHyLEXIxYMv0)
+ - [Server Push in the HTTP/2 spec](https://tools.ietf.org/html/rfc7540#section-8.2)
-* Conclusion
+## Conclusion
With Go 1.8, the standard library provides out-of-the-box support for HTTP/2
Server Push, giving you more flexibility to optimize your web applications.
-Go to our [[https://http2.golang.org/serverpush][HTTP/2 Server Push demo]]
+Go to our [HTTP/2 Server Push demo](https://http2.golang.org/serverpush)
page to see it in action.
diff --git a/content/hello-china.article b/content/hello-china.article
index abb4b0f..7766d81 100644
--- a/content/hello-china.article
+++ b/content/hello-china.article
@@ -1,30 +1,31 @@
-Hello, 中国!
+# Hello, 中国!
22 Jan 2018
Tags: community, china
+Summary: We are thrilled to announce that the content on [golang.org](https://golang.org) is now available in mainland China through the name [https://golang.google.cn](https://golang.google.cn). The growing Go developer community in China can now directly access official documentation, technical articles, and binaries.
Andrew Bonventre
-* Introduction
+##
We are thrilled to announce that the content on
-[[https://golang.org][golang.org]] is now available in mainland China through
-the name [[https://golang.google.cn][https://golang.google.cn]].
+[golang.org](https://golang.org) is now available in mainland China through
+the name [https://golang.google.cn](https://golang.google.cn).
The growing Go developer community in China can now directly access official
documentation, technical articles, and binaries.
The Go community in China is bigger than ever.
-In 2015, Robert Griesemer [[gopherchina][visited Shanghai]] to attend
+In 2015, Robert Griesemer [visited Shanghai](gopherchina) to attend
GopherChina, the first Go conference in the country.
In the years since, it has become one of the largest Go conferences in the world
with over 1200 attendees at their 2017 event.
Over the same period, one of the most popular
-[[https://gocn.io][community-built Go forums]] saw their traffic increase
+[community-built Go forums](https://gocn.io) saw their traffic increase
threefold and the number of participants in Go-specific groups on social
platforms like WeChat and QQ has grown to over 11,000 people.
Go adoption within China-based companies has also increased, with
-[[https://www.qiniu.com/][Qiniu]], [[http://www.huawei.com/][Huawei]],
-[[http://www.alibabagroup.com/][Alibaba]], and countless others using Go heavily
+[Qiniu](https://www.qiniu.com/), [Huawei](http://www.huawei.com/),
+[Alibaba](http://www.alibabagroup.com/), and countless others using Go heavily
in their production stacks.
We’re excited to provide even more resources for Go developers in China to
diff --git a/content/http-tracing.article b/content/http-tracing.article
index 710ae60..665ee1a 100644
--- a/content/http-tracing.article
+++ b/content/http-tracing.article
@@ -1,34 +1,35 @@
-Introducing HTTP Tracing
+# Introducing HTTP Tracing
4 Oct 2016
Tags: http, technical
+Summary: In Go 1.7 we introduced HTTP tracing, a facility to gather fine-grained information throughout the lifecycle of an HTTP client request. Support for HTTP tracing is provided by the [`net/http/httptrace`](https://golang.org/pkg/net/http/httptrace/) package. The collected information can be used for debugging latency issues, service monitoring, writing adaptive systems, and more.
Jaana Burcu Dogan
-* Introduction
+## Introduction
In Go 1.7 we introduced HTTP tracing, a facility to gather fine-grained
information throughout the lifecycle of an HTTP client request.
-Support for HTTP tracing is provided by the [[https://golang.org/pkg/net/http/httptrace/][`net/http/httptrace`]]
+Support for HTTP tracing is provided by the [`net/http/httptrace`](https://golang.org/pkg/net/http/httptrace/)
package. The collected information can be used for debugging latency issues,
service monitoring, writing adaptive systems, and more.
-* HTTP events
+## HTTP events
The `httptrace` package provides a number of hooks to gather information
during an HTTP round trip about a variety of events. These events include:
-- Connection creation
-- Connection reuse
-- DNS lookups
-- Writing the request to the wire
-- Reading the response
+ - Connection creation
+ - Connection reuse
+ - DNS lookups
+ - Writing the request to the wire
+ - Reading the response
-* Tracing events
+## Tracing events
You can enable HTTP tracing by putting an
-[[https://golang.org/pkg/net/http/httptrace/#ClientTrace][`*httptrace.ClientTrace`]]
-containing hook functions into a request's [[https://golang.org/pkg/context/#Context][`context.Context`]].
-Various [[https://golang.org/pkg/net/http/#RoundTripper][`http.RoundTripper`]]
+[`*httptrace.ClientTrace`](https://golang.org/pkg/net/http/httptrace/#ClientTrace)
+containing hook functions into a request's [`context.Context`](https://golang.org/pkg/context/#Context).
+Various [`http.RoundTripper`](https://golang.org/pkg/net/http/#RoundTripper)
implementations report the internal events by
looking for context's `*httptrace.ClientTrace` and calling the relevant hook functions.
@@ -42,7 +43,7 @@
information as soon as the DNS lookup is complete. It will similarly print
connection information when a connection is established to the request's host.
-* Tracing with http.Client
+## Tracing with http.Client
The tracing mechanism is designed to trace the events in the lifecycle
of a single `http.Transport.RoundTrip`. However, a client may
@@ -67,11 +68,11 @@
you can support tracing by checking the request context for an
`*httptest.ClientTrace` and invoking the relevant hooks as the events occur.
-* Conclusion
+## Conclusion
HTTP tracing is a valuable addition to Go for those who are interested
in debugging HTTP request latency and writing tools for network debugging
for outbound traffic.
By enabling this new facility, we hope to see HTTP debugging, benchmarking
and visualization tools from the community — such as
-[[https://github.com/davecheney/httpstat][httpstat]].
+[httpstat](https://github.com/davecheney/httpstat).
diff --git a/content/introducing-go-playground.article b/content/introducing-go-playground.article
index 41087da..f22045e 100644
--- a/content/introducing-go-playground.article
+++ b/content/introducing-go-playground.article
@@ -1,17 +1,18 @@
-Introducing the Go Playground
+# Introducing the Go Playground
15 Sep 2010
Tags: playground
+Summary: If you visit [golang.org](https://golang.org/) today you'll see our new look. We have given the site a new coat of paint and reorganized its content to make it easier to find. These changes are also reflected in the web interface of [godoc](https://golang.org/cmd/godoc/), the Go documentation tool. But the real news is a prominent new feature: the [Go Playground](https://golang.org/).
Andrew Gerrand
-* Introduction
+##
-If you visit [[https://golang.org/][golang.org]] today you'll see our new look.
+If you visit [golang.org](https://golang.org/) today you'll see our new look.
We have given the site a new coat of paint and reorganized its content to
make it easier to find.
-These changes are also reflected in the web interface of [[https://golang.org/cmd/godoc/][godoc]],
+These changes are also reflected in the web interface of [godoc](https://golang.org/cmd/godoc/),
the Go documentation tool.
-But the real news is a prominent new feature: the [[https://golang.org/][Go Playground]].
+But the real news is a prominent new feature: the [Go Playground](https://golang.org/).
.image introducing-go-playground_Untitled.png
@@ -20,7 +21,7 @@
link, and run on our servers.
There are a few example programs to get you started (see the "Examples" drop-down).
We hope that this will give curious programmers an opportunity to try the
-language before [[https://golang.org/doc/install.html][installing it]],
+language before [installing it](https://golang.org/doc/install.html),
and experienced Go users a convenient place in which to experiment.
Beyond the front page, this functionality has the potential to make our
reference and tutorial materials more engaging.
@@ -32,6 +33,6 @@
the only communication your program has to the outside world is via standard output,
and there are limits to CPU and memory use.
As such, consider this just a taste of the wonderful world of Go;
-to have the full experience you'll need to [[https://golang.org/doc/install.html][download it yourself]].
+to have the full experience you'll need to [download it yourself](https://golang.org/doc/install.html).
If you've been meaning to try Go but never got around to it,
-why not visit [[https://golang.org/][golang.org]] to try it right now?
+why not visit [golang.org](https://golang.org/) to try it right now?
diff --git a/content/introducing-gofix.article b/content/introducing-gofix.article
index 93c6853..63290ed 100644
--- a/content/introducing-gofix.article
+++ b/content/introducing-gofix.article
@@ -1,25 +1,26 @@
-Introducing Gofix
+# Introducing Gofix
15 Apr 2011
Tags: gofix, technical
+Summary: The next Go release will include significant API changes in several fundamental Go packages. Code that [implements an HTTP server handler](http://codereview.appspot.com/4239076), [calls `net.Dial`](http://codereview.appspot.com/4244055), [calls `os.Open`](http://codereview.appspot.com/4357052), or [uses the reflect package](http://codereview.appspot.com/4281055) will not build unless it is updated to use the new APIs. Now that our releases are [more stable and less frequent](https://blog.golang.org/2011/03/go-becomes-more-stable.html), this will be a common situation. Each of these API changes happened in a different weekly snapshot and might have been manageable on its own; together, however, they represent a significant amount of manual effort to update existing code.
Russ Cox
-* Introduction
+##
The next Go release will include significant API changes in several fundamental Go packages.
-Code that [[http://codereview.appspot.com/4239076][implements an HTTP server handler]],
-[[http://codereview.appspot.com/4244055][calls `net.Dial`]],
-[[http://codereview.appspot.com/4357052][calls `os.Open`]],
-or [[http://codereview.appspot.com/4281055][uses the reflect package]] will
+Code that [implements an HTTP server handler](http://codereview.appspot.com/4239076),
+[calls `net.Dial`](http://codereview.appspot.com/4244055),
+[calls `os.Open`](http://codereview.appspot.com/4357052),
+or [uses the reflect package](http://codereview.appspot.com/4281055) will
not build unless it is updated to use the new APIs.
-Now that our releases are [[https://blog.golang.org/2011/03/go-becomes-more-stable.html][more stable and less frequent]],
+Now that our releases are [more stable and less frequent](https://blog.golang.org/2011/03/go-becomes-more-stable.html),
this will be a common situation.
Each of these API changes happened in a different weekly snapshot and might
have been manageable on its own;
together, however, they represent a significant amount of manual effort
to update existing code.
-[[https://golang.org/cmd/fix/][Gofix]] is a new tool that reduces the amount
+[Gofix](https://golang.org/cmd/fix/) is a new tool that reduces the amount
of effort it takes to update existing code.
It reads a program from a source file, looks for uses of old APIs,
rewrites them to use the current API, and writes the program back to the file.
@@ -43,10 +44,10 @@
Right now, writing a new fix requires doing some scanning and rewriting
of the go/ast syntax tree,
usually in proportion to how complex the API changes are.
-If you want to explore, the [[https://go.googlesource.com/go/+/go1/src/cmd/fix/netdial.go][`netdialFix`]],
-[[https://go.googlesource.com/go/+/go1/src/cmd/fix/osopen.go][`osopenFix`]],
-[[https://go.googlesource.com/go/+/go1/src/cmd/fix/httpserver.go][`httpserverFix`]],
-and [[https://go.googlesource.com/go/+/go1/src/cmd/fix/reflect.go][`reflectFix`]]
+If you want to explore, the [`netdialFix`](https://go.googlesource.com/go/+/go1/src/cmd/fix/netdial.go),
+[`osopenFix`](https://go.googlesource.com/go/+/go1/src/cmd/fix/osopen.go),
+[`httpserverFix`](https://go.googlesource.com/go/+/go1/src/cmd/fix/httpserver.go),
+and [`reflectFix`](https://go.googlesource.com/go/+/go1/src/cmd/fix/reflect.go)
are all illustrative examples,
in increasing order of complexity.
@@ -58,7 +59,7 @@
We even use gofix to update Google’s internal source tree when it is time
to build against a new Go release.
-As an example, gofix can rewrite code like [[http://codereview.appspot.com/4353043/diff/10001/src/pkg/fmt/print.go#newcode657][this snippet from `fmt/print.go`]]:
+As an example, gofix can rewrite code like [this snippet from `fmt/print.go`](http://codereview.appspot.com/4353043/diff/10001/src/pkg/fmt/print.go#newcode657):
switch f := value.(type) {
case *reflect.BoolValue:
@@ -94,8 +95,8 @@
The changes involved in the rewrite are extensive but nearly entirely mechanical,
just the kind of thing that computers are great at doing.
-Gofix is possible because Go has support in its standard libraries for [[https://golang.org/pkg/go/parser][parsing Go source files into syntax trees]]
-and also for [[https://golang.org/pkg/go/printer][printing those syntax trees back to Go source code]].
+Gofix is possible because Go has support in its standard libraries for [parsing Go source files into syntax trees](https://golang.org/pkg/go/parser)
+and also for [printing those syntax trees back to Go source code](https://golang.org/pkg/go/printer).
Importantly, the Go printing library prints a program in the official format
(typically enforced via the gofmt tool),
allowing gofix to make mechanical changes to Go programs without causing
diff --git a/content/io2014.article b/content/io2014.article
index d3dded7..684317d 100644
--- a/content/io2014.article
+++ b/content/io2014.article
@@ -1,44 +1,45 @@
-Go at Google I/O and Gopher SummerFest
+# Go at Google I/O and Gopher SummerFest
6 Oct 2014
Tags: conference, io, report
+Summary: The week of June 23rd was a good week for gophers in San Francisco. Go was a big part of [Google I/O](https://www.google.com/events/io) on Wednesday and Thursday, and on Monday we took advantage of the large gopher population to run the [Go SummerFest](http://www.meetup.com/golangsf/events/170421402/), a special instance of the [GoSF](http://www.meetup.com/golangsf) meetup. This blog post is a recap of both events.
Francesc Campoy
-* Introduction
+## Introduction
The week of June 23rd was a good week for gophers in San Francisco. Go was a big
-part of [[https://www.google.com/events/io][Google I/O]] on Wednesday and
+part of [Google I/O](https://www.google.com/events/io) on Wednesday and
Thursday, and on Monday we took advantage of the large gopher population to run
-the [[http://www.meetup.com/golangsf/events/170421402/][Go SummerFest]], a
-special instance of the [[http://www.meetup.com/golangsf][GoSF]] meetup. This
+the [Go SummerFest](http://www.meetup.com/golangsf/events/170421402/), a
+special instance of the [GoSF](http://www.meetup.com/golangsf) meetup. This
blog post is a recap of both events.
-* Gopher SummerFest
+## Gopher SummerFest
.image io2014/summerfest.jpg _ 800
On the Monday, more than 200 gophers gathered at the Google office in San
Francisco to hear a series of talks:
-- The State of Go, ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVQm9tdncxWnJGUTQ/edit][slides]]
- and [[http://www.hakkalabs.co/articles/state-go][video]]) by Andrew Gerrand.
-- I was wrong, again! ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVTTUwS25qaFlzMGs/edit][slides]]
- and [[http://www.hakkalabs.co/articles/why-we-use-go][video]]), by Derek Collison.
-- Go at Splice ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVZklnNnJITlhSbXc/edit][slides]]), by Matt Aimonetti
-- Quick testing with quick ([[https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVVElmOHpwamp4aTA/edit][slides]]), by Evan Shaw
-- Something about Go (no slides), by Blake Mizerany.
+ - The State of Go, ([slides](https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVQm9tdncxWnJGUTQ/edit)
+ and [video](http://www.hakkalabs.co/articles/state-go)) by Andrew Gerrand.
+ - I was wrong, again! ([slides](https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVTTUwS25qaFlzMGs/edit)
+ and [video](http://www.hakkalabs.co/articles/why-we-use-go)), by Derek Collison.
+ - Go at Splice ([slides](https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVZklnNnJITlhSbXc/edit)), by Matt Aimonetti
+ - Quick testing with quick ([slides](https://docs.google.com/a/golang.org/file/d/0B-nws9GU_6qVVElmOHpwamp4aTA/edit)), by Evan Shaw
+ - Something about Go (no slides), by Blake Mizerany.
More comments and pictures from the event are available on the
-[[http://www.meetup.com/golangsf/events/170421402/][meetup event page]].
+[meetup event page](http://www.meetup.com/golangsf/events/170421402/).
-* Go at Google I/O
+## Go at Google I/O
On the Wednesday and Thursday, Go was at Google I/O in two different
formats: the Go booth in the sandbox area and the Go code labs available in the
code lab area and all around the world through
-[[https://www.google.com/events/io/io-extended][I/O Extended]].
+[I/O Extended](https://www.google.com/events/io/io-extended).
-** The Go booth
+### The Go booth
.image io2014/booth.jpg _ 800
@@ -49,38 +50,38 @@
recorded, but the slides and some screencasts and blog posts will be shared
soon.
-- Organizing Go Code, by David Crawshaw. ([[https://talks.golang.org/2014/organizeio.slide#1][slides]])
-- Testing Techniques, by Andrew Gerrand. ([[https://www.youtube.com/watch?v=ndmB0bj7eyw][video]]
- and [[https://talks.golang.org/2014/testing.slide#1][slides]])
-- Go for Java Developers, by Francesc Campoy. ([[https://talks.golang.org/2014/go4java.slide#1][slides]])
-- Camlistore: Android, ARM, App Engine, Everywhere,
- by Brad Fitzpatrick.
- ([[https://talks.golang.org/2014/camlistore.slide#1][slides]])
-- Go Compilation Complexities, by Ian Lance Taylor. ([[https://talks.golang.org/2014/compiling.slide#1][slides]])
-- SourceGraph: a Code Search Engine in Go,
- by Quinn Slack. ([[https://youtu.be/-DpKaoPz8l8][video]] and [[https://go-talks.appspot.com/github.com/sourcegraph/talks/google-io-2014/gio2014.slide#1][slides]])
+ - Organizing Go Code, by David Crawshaw. ([slides](https://talks.golang.org/2014/organizeio.slide#1))
+ - Testing Techniques, by Andrew Gerrand. ([video](https://www.youtube.com/watch?v=ndmB0bj7eyw)
+ and [slides](https://talks.golang.org/2014/testing.slide#1))
+ - Go for Java Developers, by Francesc Campoy. ([slides](https://talks.golang.org/2014/go4java.slide#1))
+ - Camlistore: Android, ARM, App Engine, Everywhere,
+ by Brad Fitzpatrick.
+ ([slides](https://talks.golang.org/2014/camlistore.slide#1))
+ - Go Compilation Complexities, by Ian Lance Taylor. ([slides](https://talks.golang.org/2014/compiling.slide#1))
+ - SourceGraph: a Code Search Engine in Go,
+ by Quinn Slack. ([video](https://youtu.be/-DpKaoPz8l8) and [slides](https://go-talks.appspot.com/github.com/sourcegraph/talks/google-io-2014/gio2014.slide#1))
We also organized Q&A sessions and lightning talks by members of the Go
community:
-- [[https://twitter.com/bradrydzewski][Brad Rydzewski]] talked about his project [[https://drone.io/][drone.io]].
-- [[https://twitter.com/barakmich][Barak Michener]] presented [[https://github.com/google/cayley][Cayley]],
- an open source graph database.
-- [[https://twitter.com/mattetti][Matt Aimonetti]] discussed how Go is used at [[https://splice.com/][Splice]].
-- [[https://twitter.com/ssougou][Sugu Sougoumarane]] talked about how [[https://github.com/youtube/vitess][vitess]] solved
- scalability problems at YouTube.
- ([[https://youtu.be/midJ6b1LkA0][video]])
+ - [Brad Rydzewski](https://twitter.com/bradrydzewski) talked about his project [drone.io](https://drone.io/).
+ - [Barak Michener](https://twitter.com/barakmich) presented [Cayley](https://github.com/google/cayley),
+ an open source graph database.
+ - [Matt Aimonetti](https://twitter.com/mattetti) discussed how Go is used at [Splice](https://splice.com/).
+ - [Sugu Sougoumarane](https://twitter.com/ssougou) talked about how [vitess](https://github.com/youtube/vitess) solved
+ scalability problems at YouTube.
+ ([video](https://youtu.be/midJ6b1LkA0))
-** The Go code lab
+### The Go code lab
This year attendees of Google I/O had a code lab area with self-service
computers where they could sit and learn Go. The code labs were also available
to anyone through the Google I/O extended brand. You can try it yourself at
-[[https://io2014codelabs.appspot.com/][io2014codelabs.appspot.com]].
+[io2014codelabs.appspot.com](https://io2014codelabs.appspot.com/).
.image io2014/collage.jpg _ 800
-* Conclusion
+## Conclusion
Thanks to the organizers, speakers, and attendees who helped make these events a
-great success. See you next year. (Or at [[http://dotgo.eu][dotGo]] this week!)
+great success. See you next year. (Or at [dotGo](http://dotgo.eu) this week!)
diff --git a/content/ismmkeynote.article b/content/ismmkeynote.article
index 33b2227..ea105d3 100644
--- a/content/ismmkeynote.article
+++ b/content/ismmkeynote.article
@@ -1,10 +1,11 @@
-Getting to Go: The Journey of Go's Garbage Collector
+# Getting to Go: The Journey of Go's Garbage Collector
12 Jul 2018
+Summary: This is the transcript from the keynote I gave at the International Symposium on Memory Management (ISMM) on June 18, 2018. For the past 25 years ISMM has been the premier venue for publishing memory management and garbage collection papers and it was an honor to have been invited to give the keynote.
Rick Hudson
rlh@golang.org
-* Abstract
+##
This is the transcript from the keynote I gave at the International Symposium
on Memory Management (ISMM) on June 18, 2018.
@@ -12,7 +13,7 @@
management and garbage collection papers and it was an honor to have been
invited to give the keynote.
-** Abstract
+## Abstract
The Go language features, goals, and use cases have forced us to rethink
the entire garbage collection stack and have led us to a surprising place.
@@ -22,7 +23,7 @@
This talk will provide insight into the how and the why of our journey,
where we are in 2018, and Go's preparation for the next part of the journey.
-** Bio
+## Bio
Richard L. Hudson (Rick) is best known for his work in memory management
including the invention of the Train,
@@ -33,9 +34,9 @@
Contact: rlh@golang.org
-Comments: See [[https://groups.google.com/forum/#!topic/golang-dev/UuDv7W1Hsns][the discussion on golang-dev]].
+Comments: See [the discussion on golang-dev](https://groups.google.com/forum/#!topic/golang-dev/UuDv7W1Hsns).
-** The Transcript
+## The Transcript
.image ismmkeynote/image63.png
@@ -322,8 +323,8 @@
this math and see if it's the same as your math.
If you have any suggestions let us know.
-[[https://golang.org/s/go15gcpacing][*Go 1.5 concurrent garbage collector pacing]]
-and [[https://github.com/golang/proposal/blob/master/design/14951-soft-heap-limit.md][Proposal: Separate soft and hard heap size goal]]
+[\*Go 1.5 concurrent garbage collector pacing](https://golang.org/s/go15gcpacing)
+and [Proposal: Separate soft and hard heap size goal](https://github.com/golang/proposal/blob/master/design/14951-soft-heap-limit.md)
.image ismmkeynote/image40.png
@@ -738,7 +739,7 @@
Put another way, we think that doubling memory is going to be a better value than doubling cores.
-[[http://www.kurzweilai.net/ask-ray-the-future-of-moores-law][Original graph]]
+[Original graph](http://www.kurzweilai.net/ask-ray-the-future-of-moores-law)
at www.kurzweilai.net/ask-ray-the-future-of-moores-law.
.image ismmkeynote/image57.png
@@ -769,7 +770,7 @@
Chang M.S., Electrical & Computer Engineering,
Carnegie Mellon University B.S., Electrical & Computer Engineering,
Carnegie Mellon University Carnegie Mellon University Pittsburgh, PA May, 2017".
-See [[http://repository.cmu.edu/cgi/viewcontent.cgi?article%3D1946%26context%3Ddissertations&sa=D&ust=1531164842660000][Kevin K. Chang's thesis.]]
+See [Kevin K. Chang's thesis.](http://repository.cmu.edu/cgi/viewcontent.cgi?article%3D1946%26context%3Ddissertations&sa=D&ust=1531164842660000)
The original graph in the introduction was not in a form that I could draw
a Moore's law line on it easily so I changed the X-axis to be more uniform.)
@@ -795,7 +796,7 @@
Long term, it is our belief that memory pricing will drop at a rate that is much faster than CPU pricing.
-(Sources [[https://hblok.net/blog/][https://hblok.net/blog/]] and [[https://hblok.net/storage_data/storage_memory_prices_2005-2017-12.png][https://hblok.net/storage_data/storage_memory_prices_2005-2017-12.png]])
+(Sources [https://hblok.net/blog/](https://hblok.net/blog/) and [https://hblok.net/storage\_data/storage\_memory\_prices\_2005-2017-12.png](https://hblok.net/storage_data/storage_memory_prices_2005-2017-12.png))
.image ismmkeynote/image37.png
@@ -848,4 +849,4 @@
P.S. The Go team is looking to hire engineers to help develop and maintain the Go runtime and compiler toolchain.
-Interested? Have a look at our [[https://go-jobs-at-goog.firebaseapp.com][open positions]].
+Interested? Have a look at our [open positions](https://go-jobs-at-goog.firebaseapp.com).
diff --git a/content/json-and-go.article b/content/json-and-go.article
index 8e4dfcd..4287cf8 100644
--- a/content/json-and-go.article
+++ b/content/json-and-go.article
@@ -1,25 +1,26 @@
-JSON and Go
+# JSON and Go
25 Jan 2011
Tags: json, technical
+Summary: JSON (JavaScript Object Notation) is a simple data interchange format. Syntactically it resembles the objects and lists of JavaScript. It is most commonly used for communication between web back-ends and JavaScript programs running in the browser, but it is used in many other places, too. Its home page, [json.org](http://json.org), provides a wonderfully clear and concise definition of the standard.
Andrew Gerrand
-* Introduction
+## Introduction
JSON (JavaScript Object Notation) is a simple data interchange format.
Syntactically it resembles the objects and lists of JavaScript.
It is most commonly used for communication between web back-ends and JavaScript
programs running in the browser,
but it is used in many other places, too.
-Its home page, [[http://json.org][json.org]],
+Its home page, [json.org](http://json.org),
provides a wonderfully clear and concise definition of the standard.
-With the [[https://golang.org/pkg/encoding/json/][json package]] it's a
+With the [json package](https://golang.org/pkg/encoding/json/) it's a
snap to read and write JSON data from your Go programs.
-* Encoding
+## Encoding
-To encode JSON data we use the [[https://golang.org/pkg/encoding/json/#Marshal][`Marshal`]] function.
+To encode JSON data we use the [`Marshal`](https://golang.org/pkg/encoding/json/#Marshal) function.
func Marshal(v interface{}) ([]byte, error)
@@ -33,11 +34,11 @@
and an instance of `Message`
- m := Message{"Alice", "Hello", 1294706395881547000}
+ m := Message{"Alice", "Hello", 1294706395881547000}
we can marshal a JSON-encoded version of m using `json.Marshal`:
- b, err := json.Marshal(m)
+ b, err := json.Marshal(m)
If all is well, `err` will be `nil` and `b` will be a `[]byte` containing this JSON data:
@@ -45,62 +46,62 @@
Only data structures that can be represented as valid JSON will be encoded:
-- JSON objects only support strings as keys;
- to encode a Go map type it must be of the form `map[string]T` (where `T`
- is any Go type supported by the json package).
+ - JSON objects only support strings as keys;
+ to encode a Go map type it must be of the form `map[string]T` (where `T`
+ is any Go type supported by the json package).
-- Channel, complex, and function types cannot be encoded.
+ - Channel, complex, and function types cannot be encoded.
-- Cyclic data structures are not supported; they will cause `Marshal` to go into an infinite loop.
+ - Cyclic data structures are not supported; they will cause `Marshal` to go into an infinite loop.
-- Pointers will be encoded as the values they point to (or 'null' if the pointer is `nil`).
+ - Pointers will be encoded as the values they point to (or 'null' if the pointer is `nil`).
The json package only accesses the exported fields of struct types (those
that begin with an uppercase letter).
Therefore only the the exported fields of a struct will be present in the JSON output.
-* Decoding
+## Decoding
-To decode JSON data we use the [[https://golang.org/pkg/encoding/json/#Unmarshal][`Unmarshal`]] function.
+To decode JSON data we use the [`Unmarshal`](https://golang.org/pkg/encoding/json/#Unmarshal) function.
func Unmarshal(data []byte, v interface{}) error
We must first create a place where the decoded data will be stored
- var m Message
+ var m Message
and call `json.Unmarshal`, passing it a `[]byte` of JSON data and a pointer to `m`
- err := json.Unmarshal(b, &m)
+ err := json.Unmarshal(b, &m)
If `b` contains valid JSON that fits in `m`,
after the call `err` will be `nil` and the data from `b` will have been
stored in the struct `m`,
as if by an assignment like:
- m = Message{
- Name: "Alice",
- Body: "Hello",
- Time: 1294706395881547000,
- }
+ m = Message{
+ Name: "Alice",
+ Body: "Hello",
+ Time: 1294706395881547000,
+ }
How does `Unmarshal` identify the fields in which to store the decoded data?
For a given JSON key `"Foo"`,
`Unmarshal` will look through the destination struct's fields to find (in
order of preference):
-- An exported field with a tag of `"Foo"` (see the [[https://golang.org/ref/spec#Struct_types][Go spec]]
- for more on struct tags),
+ - An exported field with a tag of `"Foo"` (see the [Go spec](https://golang.org/ref/spec#Struct_types)
+ for more on struct tags),
-- An exported field named `"Foo"`, or
+ - An exported field named `"Foo"`, or
-- An exported field named `"FOO"` or `"FoO"` or some other case-insensitive match of `"Foo"`.
+ - An exported field named `"FOO"` or `"FoO"` or some other case-insensitive match of `"Foo"`.
What happens when the structure of the JSON data doesn't exactly match the Go type?
- b := []byte(`{"Name":"Bob","Food":"Pickle"}`)
- var m Message
- err := json.Unmarshal(b, &m)
+ b := []byte(`{"Name":"Bob","Food":"Pickle"}`)
+ var m Message
+ err := json.Unmarshal(b, &m)
`Unmarshal` will decode only the fields that it can find in the destination type.
In this case, only the Name field of m will be populated,
@@ -112,99 +113,99 @@
But what if you don't know the structure of your JSON data beforehand?
-* Generic JSON with interface{}
+## Generic JSON with interface{}
The `interface{}` (empty interface) type describes an interface with zero methods.
Every Go type implements at least zero methods and therefore satisfies the empty interface.
The empty interface serves as a general container type:
- var i interface{}
- i = "a string"
- i = 2011
- i = 2.777
+ var i interface{}
+ i = "a string"
+ i = 2011
+ i = 2.777
A type assertion accesses the underlying concrete type:
- r := i.(float64)
- fmt.Println("the circle's area", math.Pi*r*r)
+ r := i.(float64)
+ fmt.Println("the circle's area", math.Pi*r*r)
Or, if the underlying type is unknown, a type switch determines the type:
- switch v := i.(type) {
- case int:
- fmt.Println("twice i is", v*2)
- case float64:
- fmt.Println("the reciprocal of i is", 1/v)
- case string:
- h := len(v) / 2
- fmt.Println("i swapped by halves is", v[h:]+v[:h])
- default:
- // i isn't one of the types above
- }
+ switch v := i.(type) {
+ case int:
+ fmt.Println("twice i is", v*2)
+ case float64:
+ fmt.Println("the reciprocal of i is", 1/v)
+ case string:
+ h := len(v) / 2
+ fmt.Println("i swapped by halves is", v[h:]+v[:h])
+ default:
+ // i isn't one of the types above
+ }
The json package uses `map[string]interface{}` and
`[]interface{}` values to store arbitrary JSON objects and arrays;
it will happily unmarshal any valid JSON blob into a plain
`interface{}` value. The default concrete Go types are:
-- `bool` for JSON booleans,
+ - `bool` for JSON booleans,
-- `float64` for JSON numbers,
+ - `float64` for JSON numbers,
-- `string` for JSON strings, and
+ - `string` for JSON strings, and
-- `nil` for JSON null.
+ - `nil` for JSON null.
-* Decoding arbitrary data
+## Decoding arbitrary data
Consider this JSON data, stored in the variable `b`:
- b := []byte(`{"Name":"Wednesday","Age":6,"Parents":["Gomez","Morticia"]}`)
+ b := []byte(`{"Name":"Wednesday","Age":6,"Parents":["Gomez","Morticia"]}`)
Without knowing this data's structure, we can decode it into an `interface{}` value with `Unmarshal`:
- var f interface{}
- err := json.Unmarshal(b, &f)
+ var f interface{}
+ err := json.Unmarshal(b, &f)
At this point the Go value in `f` would be a map whose keys are strings
and whose values are themselves stored as empty interface values:
- f = map[string]interface{}{
- "Name": "Wednesday",
- "Age": 6,
- "Parents": []interface{}{
- "Gomez",
- "Morticia",
- },
- }
+ f = map[string]interface{}{
+ "Name": "Wednesday",
+ "Age": 6,
+ "Parents": []interface{}{
+ "Gomez",
+ "Morticia",
+ },
+ }
To access this data we can use a type assertion to access `f`'s underlying `map[string]interface{}`:
- m := f.(map[string]interface{})
+ m := f.(map[string]interface{})
We can then iterate through the map with a range statement and use a type
switch to access its values as their concrete types:
- for k, v := range m {
- switch vv := v.(type) {
- case string:
- fmt.Println(k, "is string", vv)
- case float64:
- fmt.Println(k, "is float64", vv)
- case []interface{}:
- fmt.Println(k, "is an array:")
- for i, u := range vv {
- fmt.Println(i, u)
- }
- default:
- fmt.Println(k, "is of a type I don't know how to handle")
+ for k, v := range m {
+ switch vv := v.(type) {
+ case string:
+ fmt.Println(k, "is string", vv)
+ case float64:
+ fmt.Println(k, "is float64", vv)
+ case []interface{}:
+ fmt.Println(k, "is an array:")
+ for i, u := range vv {
+ fmt.Println(i, u)
}
+ default:
+ fmt.Println(k, "is of a type I don't know how to handle")
}
+ }
In this way you can work with unknown JSON data while still enjoying the benefits of type safety.
-* Reference Types
+## Reference Types
Let's define a Go type to contain the data from the previous example:
@@ -253,12 +254,12 @@
To know which messages to process, the programmer need simply test that
either `Cmd` or `Msg` is not `nil`.
-* Streaming Encoders and Decoders
+## Streaming Encoders and Decoders
The json package provides `Decoder` and `Encoder` types to support the common
operation of reading and writing streams of JSON data.
-The `NewDecoder` and `NewEncoder` functions wrap the [[https://golang.org/pkg/io/#Reader][`io.Reader`]]
-and [[https://golang.org/pkg/io/#Writer][`io.Writer`]] interface types.
+The `NewDecoder` and `NewEncoder` functions wrap the [`io.Reader`](https://golang.org/pkg/io/#Reader)
+and [`io.Writer`](https://golang.org/pkg/io/#Writer) interface types.
func NewDecoder(r io.Reader) *Decoder
func NewEncoder(w io.Writer) *Encoder
@@ -300,7 +301,7 @@
such as reading and writing to HTTP connections,
WebSockets, or files.
-* References
+## References
-For more information see the [[https://golang.org/pkg/encoding/json/][json package documentation]].
-For an example usage of json see the source files of the [[https://golang.org/pkg/net/rpc/jsonrpc/][jsonrpc package]].
+For more information see the [json package documentation](https://golang.org/pkg/encoding/json/).
+For an example usage of json see the source files of the [jsonrpc package](https://golang.org/pkg/net/rpc/jsonrpc/).
diff --git a/content/json-rpc-tale-of-interfaces.article b/content/json-rpc-tale-of-interfaces.article
index 3ccabc7..59875f1 100644
--- a/content/json-rpc-tale-of-interfaces.article
+++ b/content/json-rpc-tale-of-interfaces.article
@@ -1,16 +1,17 @@
-JSON-RPC: a tale of interfaces
+# JSON-RPC: a tale of interfaces
27 Apr 2010
Tags: json, rpc, technical
+Summary: Here we present an example where Go's [interfaces](https://golang.org/doc/effective_go.html#interfaces_and_types) made it easy to refactor some existing code to make it more flexible and extensible. Originally, the standard library's [RPC package](https://golang.org/pkg/net/rpc/) used a custom wire format called [gob](https://golang.org/pkg/encoding/gob/). For a particular application, we wanted to use [JSON](https://golang.org/pkg/encoding/json/) as an alternate wire format.
Andrew Gerrand
-* Introduction
+##
-Here we present an example where Go's [[https://golang.org/doc/effective_go.html#interfaces_and_types][interfaces]]
+Here we present an example where Go's [interfaces](https://golang.org/doc/effective_go.html#interfaces_and_types)
made it easy to refactor some existing code to make it more flexible and extensible.
-Originally, the standard library's [[https://golang.org/pkg/net/rpc/][RPC package]]
-used a custom wire format called [[https://golang.org/pkg/encoding/gob/][gob]].
-For a particular application, we wanted to use [[https://golang.org/pkg/encoding/json/][JSON]]
+Originally, the standard library's [RPC package](https://golang.org/pkg/net/rpc/)
+used a custom wire format called [gob](https://golang.org/pkg/encoding/gob/).
+For a particular application, we wanted to use [JSON](https://golang.org/pkg/encoding/json/)
as an alternate wire format.
We first defined a pair of interfaces to describe the functionality of the
@@ -42,7 +43,7 @@
this was the full extent of the work we needed to do on the RPC package.
This whole exercise took about 20 minutes!
After tidying up and testing the new code,
-the [[https://github.com/golang/go/commit/dcff89057bc0e0d7cb14cf414f2df6f5fb1a41ec][final changeset]] was submitted.
+the [final changeset](https://github.com/golang/go/commit/dcff89057bc0e0d7cb14cf414f2df6f5fb1a41ec) was submitted.
In an inheritance-oriented language like Java or C++,
the obvious path would be to generalize the RPC class,
diff --git a/content/laws-of-reflection.article b/content/laws-of-reflection.article
index 10cd663..6e34859 100644
--- a/content/laws-of-reflection.article
+++ b/content/laws-of-reflection.article
@@ -1,10 +1,11 @@
-The Laws of Reflection
+# The Laws of Reflection
6 Sep 2011
Tags: interface, reflect, type, technical
+Summary: Reflection in computing is the ability of a program to examine its own structure, particularly through types; it's a form of metaprogramming. It's also a great source of confusion.
Rob Pike
-* Introduction
+## Introduction
Reflection in computing is the ability of a program to examine its own structure,
particularly through types;
@@ -16,7 +17,7 @@
but this article is about Go, so for the rest of this article the word "reflection"
should be taken to mean "reflection in Go".
-* Types and interfaces
+## Types and interfaces
Because reflection builds on the type system, let's start with a refresher about types in Go.
@@ -39,7 +40,7 @@
An interface variable can store any concrete (non-interface) value as long
as that value implements the interface's methods.
A well-known pair of examples is `io.Reader` and `io.Writer`,
-the types `Reader` and `Writer` from the [[https://golang.org/pkg/io/][io package]]:
+the types `Reader` and `Writer` from the [io package](https://golang.org/pkg/io/):
// Reader is the interface that wraps the basic Read method.
type Reader interface {
@@ -56,11 +57,11 @@
For the purposes of this discussion, that means that a variable of type
`io.Reader` can hold any value whose type has a `Read` method:
- var r io.Reader
- r = os.Stdin
- r = bufio.NewReader(r)
- r = new(bytes.Buffer)
- // and so on
+ var r io.Reader
+ r = os.Stdin
+ r = bufio.NewReader(r)
+ r = new(bytes.Buffer)
+ // and so on
It's important to be clear that whatever concrete value `r` may hold,
`r`'s type is always `io.Reader`:
@@ -80,9 +81,9 @@
We need to be precise about all this because reflection and interfaces are closely related.
-* The representation of an interface
+## The representation of an interface
-Russ Cox has written a [[https://research.swtch.com/2009/12/go-data-structures-interfaces.html][ detailed blog post]]
+Russ Cox has written a [ detailed blog post](https://research.swtch.com/2009/12/go-data-structures-interfaces.html)
about the representation of interface values in Go.
It's not necessary to repeat the full story here,
but a simplified summary is in order.
@@ -93,12 +94,12 @@
To be more precise, the value is the underlying concrete data item that
implements the interface and the type describes the full type of that item. For instance, after
- var r io.Reader
- tty, err := os.OpenFile("/dev/tty", os.O_RDWR, 0)
- if err != nil {
- return nil, err
- }
- r = tty
+ var r io.Reader
+ tty, err := os.OpenFile("/dev/tty", os.O_RDWR, 0)
+ if err != nil {
+ return nil, err
+ }
+ r = tty
`r` contains, schematically, the (value, type) pair,
(`tty`, `*os.File`).
@@ -107,8 +108,8 @@
the value inside carries all the type information about that value.
That's why we can do things like this:
- var w io.Writer
- w = r.(io.Writer)
+ var w io.Writer
+ w = r.(io.Writer)
The expression in this assignment is a type assertion;
what it asserts is that the item inside `r` also implements `io.Writer`,
@@ -120,8 +121,8 @@
Continuing, we can do this:
- var empty interface{}
- empty = w
+ var empty interface{}
+ empty = w
and our empty interface value `empty` will again contain that same pair,
(`tty`, `*os.File`).
@@ -140,14 +141,14 @@
Now we're ready to reflect.
-* The first law of reflection
+## The first law of reflection
-* 1. Reflection goes from interface value to reflection object.
+## 1. Reflection goes from interface value to reflection object.
At the basic level, reflection is just a mechanism to examine the type and
value pair stored inside an interface variable.
-To get started, there are two types we need to know about in [[https://golang.org/pkg/reflect/][package reflect]]:
-[[https://golang.org/pkg/reflect/#Type][Type]] and [[https://golang.org/pkg/reflect/#Value][Value]].
+To get started, there are two types we need to know about in [package reflect](https://golang.org/pkg/reflect/):
+[Type](https://golang.org/pkg/reflect/#Type) and [Value](https://golang.org/pkg/reflect/#Value).
Those two types give access to the contents of an interface variable,
and two simple functions, called `reflect.TypeOf` and `reflect.ValueOf`,
retrieve `reflect.Type` and `reflect.Value` pieces out of an interface value.
@@ -175,7 +176,7 @@
You might be wondering where the interface is here,
since the program looks like it's passing the `float64` variable `x`,
not an interface value, to `reflect.TypeOf`.
-But it's there; as [[https://golang.org/pkg/reflect/#TypeOf][godoc reports]],
+But it's there; as [godoc reports](https://golang.org/pkg/reflect/#TypeOf),
the signature of `reflect.TypeOf` includes an empty interface:
// TypeOf returns the reflection Type of the value in the interface{}.
@@ -189,8 +190,8 @@
recovers the value (from here on we'll elide the boilerplate and focus just
on the executable code):
- var x float64 = 3.4
- fmt.Println("value:", reflect.ValueOf(x).String())
+ var x float64 = 3.4
+ fmt.Println("value:", reflect.ValueOf(x).String())
prints
@@ -210,11 +211,11 @@
Also methods on `Value` with names like `Int` and `Float` let us grab values
(as `int64` and `float64`) stored inside:
- var x float64 = 3.4
- v := reflect.ValueOf(x)
- fmt.Println("type:", v.Type())
- fmt.Println("kind is float64:", v.Kind() == reflect.Float64)
- fmt.Println("value:", v.Float())
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
+ fmt.Println("type:", v.Type())
+ fmt.Println("kind is float64:", v.Kind() == reflect.Float64)
+ fmt.Println("value:", v.Float())
prints
@@ -234,29 +235,29 @@
value takes an `int64`;
it may be necessary to convert to the actual type involved:
- var x uint8 = 'x'
- v := reflect.ValueOf(x)
- fmt.Println("type:", v.Type()) // uint8.
- fmt.Println("kind is uint8: ", v.Kind() == reflect.Uint8) // true.
- x = uint8(v.Uint()) // v.Uint returns a uint64.
+ var x uint8 = 'x'
+ v := reflect.ValueOf(x)
+ fmt.Println("type:", v.Type()) // uint8.
+ fmt.Println("kind is uint8: ", v.Kind() == reflect.Uint8) // true.
+ x = uint8(v.Uint()) // v.Uint returns a uint64.
The second property is that the `Kind` of a reflection object describes
the underlying type,
not the static type.
If a reflection object contains a value of a user-defined integer type, as in
- type MyInt int
- var x MyInt = 7
- v := reflect.ValueOf(x)
+ type MyInt int
+ var x MyInt = 7
+ v := reflect.ValueOf(x)
the `Kind` of `v` is still `reflect.Int`,
even though the static type of `x` is `MyInt`, not `int`.
In other words, the `Kind` cannot discriminate an int from a `MyInt` even
though the `Type` can.
-* The second law of reflection
+## The second law of reflection
-* 2. Reflection goes from reflection object to interface value.
+## 2. Reflection goes from reflection object to interface value.
Like physical reflection, reflection in Go generates its own inverse.
@@ -269,8 +270,8 @@
As a consequence we can say
- y := v.Interface().(float64) // y will have type float64.
- fmt.Println(y)
+ y := v.Interface().(float64) // y will have type float64.
+ fmt.Println(y)
to print the `float64` value represented by the reflection object `v`.
@@ -281,13 +282,13 @@
Therefore all it takes to print the contents of a `reflect.Value` correctly
is to pass the result of the `Interface` method to the formatted print routine:
- fmt.Println(v.Interface())
+ fmt.Println(v.Interface())
(Why not `fmt.Println(v)`? Because `v` is a `reflect.Value`;
we want the concrete value it holds.) Since our value is a `float64`,
we can even use a floating-point format if we want:
- fmt.Printf("value is %7.1e\n", v.Interface())
+ fmt.Printf("value is %7.1e\n", v.Interface())
and get in this case
@@ -302,17 +303,17 @@
Reiterating: Reflection goes from interface values to reflection objects and back again.
-* The third law of reflection
+## The third law of reflection
-* 3. To modify a reflection object, the value must be settable.
+## 3. To modify a reflection object, the value must be settable.
The third law is the most subtle and confusing, but it's easy enough to understand if we start from first principles.
Here is some code that does not work, but is worth studying.
- var x float64 = 3.4
- v := reflect.ValueOf(x)
- v.SetFloat(7.1) // Error: will panic.
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
+ v.SetFloat(7.1) // Error: will panic.
If you run this code, it will panic with the cryptic message
@@ -325,9 +326,9 @@
The `CanSet` method of `Value` reports the settability of a `Value`; in our case,
- var x float64 = 3.4
- v := reflect.ValueOf(x)
- fmt.Println("settability of v:", v.CanSet())
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
+ fmt.Println("settability of v:", v.CanSet())
prints
@@ -340,15 +341,15 @@
that was used to create the reflection object.
Settability is determined by whether the reflection object holds the original item. When we say
- var x float64 = 3.4
- v := reflect.ValueOf(x)
+ var x float64 = 3.4
+ v := reflect.ValueOf(x)
we pass a copy of `x` to `reflect.ValueOf`,
so the interface value created as the argument to `reflect.ValueOf` is a
copy of `x`, not `x` itself.
Thus, if the statement
- v.SetFloat(7.1)
+ v.SetFloat(7.1)
were allowed to succeed, it would not update `x`,
even though `v` looks like it was created from `x`.
@@ -375,10 +376,10 @@
Let's do that. First we initialize `x` as usual and then create a reflection value that points to it, called `p`.
- var x float64 = 3.4
- p := reflect.ValueOf(&x) // Note: take the address of x.
- fmt.Println("type of p:", p.Type())
- fmt.Println("settability of p:", p.CanSet())
+ var x float64 = 3.4
+ p := reflect.ValueOf(&x) // Note: take the address of x.
+ fmt.Println("type of p:", p.Type())
+ fmt.Println("settability of p:", p.CanSet())
The output so far is
@@ -390,8 +391,8 @@
To get to what `p` points to, we call the `Elem` method of `Value`,
which indirects through the pointer, and save the result in a reflection `Value` called `v`:
- v := p.Elem()
- fmt.Println("settability of v:", v.CanSet())
+ v := p.Elem()
+ fmt.Println("settability of v:", v.CanSet())
Now `v` is a settable reflection object, as the output demonstrates,
@@ -399,9 +400,9 @@
and since it represents `x`, we are finally able to use `v.SetFloat` to modify the value of `x`:
- v.SetFloat(7.1)
- fmt.Println(v.Interface())
- fmt.Println(x)
+ v.SetFloat(7.1)
+ fmt.Println(v.Interface())
+ fmt.Println(x)
The output, as expected, is
@@ -413,7 +414,7 @@
Just keep in mind that reflection Values need the address of something in
order to modify what they represent.
-* Structs
+## Structs
In our previous example `v` wasn't a pointer itself,
it was just derived from one.
@@ -426,22 +427,22 @@
We create the reflection object with the address of the struct because we'll
want to modify it later.
Then we set `typeOfT` to its type and iterate over the fields using straightforward
-method calls (see [[https://golang.org/pkg/reflect/][package reflect]] for details).
+method calls (see [package reflect](https://golang.org/pkg/reflect/) for details).
Note that we extract the names of the fields from the struct type,
but the fields themselves are regular `reflect.Value` objects.
- type T struct {
- A int
- B string
- }
- t := T{23, "skidoo"}
- s := reflect.ValueOf(&t).Elem()
- typeOfT := s.Type()
- for i := 0; i < s.NumField(); i++ {
- f := s.Field(i)
- fmt.Printf("%d: %s %s = %v\n", i,
- typeOfT.Field(i).Name, f.Type(), f.Interface())
- }
+ type T struct {
+ A int
+ B string
+ }
+ t := T{23, "skidoo"}
+ s := reflect.ValueOf(&t).Elem()
+ typeOfT := s.Type()
+ for i := 0; i < s.NumField(); i++ {
+ f := s.Field(i)
+ fmt.Printf("%d: %s %s = %v\n", i,
+ typeOfT.Field(i).Name, f.Type(), f.Interface())
+ }
The output of this program is
@@ -454,9 +455,9 @@
Because `s` contains a settable reflection object, we can modify the fields of the structure.
- s.Field(0).SetInt(77)
- s.Field(1).SetString("Sunset Strip")
- fmt.Println("t is now", t)
+ s.Field(0).SetInt(77)
+ s.Field(1).SetString("Sunset Strip")
+ fmt.Println("t is now", t)
And here's the result:
@@ -466,15 +467,15 @@
not `&t`, the calls to `SetInt` and `SetString` would fail as the fields
of `t` would not be settable.
-* Conclusion
+## Conclusion
Here again are the laws of reflection:
-- Reflection goes from interface value to reflection object.
+ - Reflection goes from interface value to reflection object.
-- Reflection goes from reflection object to interface value.
+ - Reflection goes from reflection object to interface value.
-- To modify a reflection object, the value must be settable.
+ - To modify a reflection object, the value must be settable.
Once you understand these laws reflection in Go becomes much easier to use,
although it remains subtle.
diff --git a/content/learn-go-from-your-browser.article b/content/learn-go-from-your-browser.article
index 8458c09..559f898 100644
--- a/content/learn-go-from-your-browser.article
+++ b/content/learn-go-from-your-browser.article
@@ -1,21 +1,22 @@
-Learn Go from your browser
+# Learn Go from your browser
4 Oct 2011
Tags: playground, tour
+Summary: We are excited to announce [A Tour of Go](https://tour.golang.org/), a guided tour of the Go programming language you can run from your browser.
Andrew Gerrand
-* Introduction
+##
-We are excited to announce [[https://tour.golang.org/][A Tour of Go]],
+We are excited to announce [A Tour of Go](https://tour.golang.org/),
a guided tour of the Go programming language you can run from your browser.
The tour is hands-on, demonstrating the language through code samples that you can modify,
compile, and run from the tour itself.
-(The technology behind the [[https://golang.org/doc/play/][Go Playground]] does the work.)
+(The technology behind the [Go Playground](https://golang.org/doc/play/) does the work.)
The tour has three sections. The first section covers basic syntax and data structures;
the second discusses methods and interfaces;
and the third introduces Go's concurrency primitives.
Each section concludes with a few exercises so you can practice what you've learned.
-So, what are you waiting for? [[https://tour.golang.org/][Get started now!]]
+So, what are you waiting for? [Get started now!](https://tour.golang.org/)
diff --git a/content/matchlang.article b/content/matchlang.article
index 47473ea..ea64dbd 100644
--- a/content/matchlang.article
+++ b/content/matchlang.article
@@ -1,10 +1,11 @@
-Language and Locale Matching in Go
-09 Feb 2016
+# Language and Locale Matching in Go
+9 Feb 2016
Tags: language, locale, tag, BCP 47, matching
+Summary: Consider an application, such as a web site, with support for multiple languages in its user interface. When a user arrives with a list of preferred languages, the application must decide which language it should use in its presentation to the user. This requires finding the best match between the languages the application supports and those the user prefers. This post explains why this is a difficult decision and how Go can help.
Marcel van Lohuizen
-* Introduction
+## Introduction
Consider an application, such as a web site, with support for multiple languages
in its user interface.
@@ -14,7 +15,7 @@
and those the user prefers.
This post explains why this is a difficult decision and how Go can help.
-* Language Tags
+## Language Tags
Language tags, also known as locale identifiers, are machine-readable
identifiers for the language and/or dialect being used.
@@ -47,14 +48,14 @@
sorting order for Portuguese, a collate package may fall back to the sorting
order for the default, or “root”, language.
-* The Messy Nature of Matching Languages
+## The Messy Nature of Matching Languages
Handling language tags is tricky.
This is partly because the boundaries of human languages are not well defined
and partly because of the legacy of evolving language tag standards.
In this section we will show some of the messy aspects of handling language tags.
-__Tags_with_different_language_codes_can_indicate_the_same_language_
+_ Tags with different language codes can indicate the same language_
For historical and political reasons, many language codes have changed over
time, leaving languages with an older legacy code as well as a new one.
@@ -66,7 +67,7 @@
Tags for macro languages are often used interchangeably with the most-spoken
language in the group.
-_Matching_language_code_alone_is_not_sufficient_
+_Matching language code alone is not sufficient_
Azerbaijani (“az”), for example, is written in different scripts depending on
the country in which it is spoken: "az-Latn" for Latin (the default script),
@@ -82,7 +83,7 @@
If you ignore subtags, you might as well present Greek to the user.
-_The_best_match_might_be_a_language_not_listed_by_the_user_
+_The best match might be a language not listed by the user_
The most common written form of Norwegian (“nb”) looks an awful lot like Danish.
If Norwegian is not available, Danish may be a good second choice.
@@ -93,7 +94,7 @@
If a user-requested language is not supported, falling back to English is often
not the best thing to do.
-_The_choice_of_language_decides_more_than_translation_
+_The choice of language decides more than translation_
Suppose a user asks for Danish, with German as a second choice.
If an application chooses German, it must not only use German translations
@@ -105,10 +106,10 @@
language) and then you stick with this protocol for all communication for the
duration of a session.
-_Using_a_“parent”_of_a_language_as_fallback_is_non-trivial_
+_Using a “parent” of a language as fallback is non-trivial_
Suppose your application supports Angolan Portuguese (“pt-AO”).
-Packages in [[https://golang.org/x/text]], like collation and display, may not
+Packages in [golang.org/x/text](https://golang.org/x/text), like collation and display, may not
have specific support for this dialect.
The correct course of action in such cases is to match the closest parent dialect.
Languages are arranged in a hierarchy, with each specific language having a more
@@ -127,9 +128,9 @@
If you compute the parent by simply removing subtags, you may select a “dialect”
that is incomprehensible to the user.
-* Language Matching in Go
+## Language Matching in Go
-The Go package [[https://golang.org/x/text/language]] implements the BCP 47
+The Go package [golang.org/x/text/language](https://golang.org/x/text/language) implements the BCP 47
standard for language tags and adds support for deciding which language to use
based on data published in the Unicode Common Locale Data Repository (CLDR).
@@ -138,7 +139,7 @@
.code -edit matchlang/complete.go
-** Creating Language Tags
+### Creating Language Tags
The simplest way to create a language.Tag from a user-given language code string
is with language.Make.
@@ -164,7 +165,7 @@
A full array of canonicalization options are available if the programmer still
desires to do so.
-** Matching User-Preferred Languages to Supported Languages
+### Matching User-Preferred Languages to Supported Languages
A Matcher matches user-preferred languages to supported languages.
Users are strongly advised to use it if they don’t want to deal with all the
@@ -193,7 +194,7 @@
It is all the same for the Matcher. An application may even add both, allowing
for more specific American slang for “en-US”.
-** Matching Example
+### Matching Example
Consider the following Matcher and lists of supported languages:
@@ -245,7 +246,7 @@
German is the best match for Swiss German in the server's language list, and the
option for phone-book collation order has been carried over.
-** Confidence Scores
+### Confidence Scores
Go uses coarse-grained confidence scoring with rule-based elimination.
A match is classified as Exact, High (not exact, but no known ambiguity), Low
@@ -264,9 +265,9 @@
simpler to implement, more maintainable, and faster, meaning that we could
handle more rules.
-** Displaying Supported Languages
+### Displaying Supported Languages
-The [[https://golang.org/x/text/language/display]] package allows naming language
+The [golang.org/x/text/language/display](https://golang.org/x/text/language/display) package allows naming language
tags in many languages.
It also contains a “Self” namer for displaying a tag in its own language.
@@ -287,7 +288,7 @@
In the second column, note the differences in capitalization, reflecting the
rules of the respective language.
-* Conclusion
+## Conclusion
At first glance, language tags look like nicely structured data, but because
they describe human languages, the structure of relationships between language
@@ -297,5 +298,5 @@
language tags.
As described above, this can produce awful results.
-Go's [[https://golang.org/x/text/language]] package solves this complex problem
+Go's [golang.org/x/text/language](https://golang.org/x/text/language) package solves this complex problem
while still presenting a simple, easy-to-use API. Enjoy.
diff --git a/content/migrating-to-go-modules.article b/content/migrating-to-go-modules.article
index e3c8759..10bf730 100644
--- a/content/migrating-to-go-modules.article
+++ b/content/migrating-to-go-modules.article
@@ -1,24 +1,25 @@
-Migrating to Go Modules
+# Migrating to Go Modules
21 Aug 2019
Tags: tools, versioning, modules
+Summary: This post is part 2 in a series.
Jean de Klerk
-* Introduction
+## Introduction
This post is part 2 in a series.
-- Part 1 — [[/using-go-modules][Using Go Modules]]
-- *Part*2*—*Migrating*To*Go*Modules* (this post)
-- Part 3 — [[/publishing-go-modules][Publishing Go Modules]]
-- Part 4 — [[/v2-go-modules][Go Modules: v2 and Beyond]]
+ - Part 1 — [Using Go Modules](/using-go-modules)
+ - **Part 2 — Migrating To Go Modules** (this post)
+ - Part 3 — [Publishing Go Modules](/publishing-go-modules)
+ - Part 4 — [Go Modules: v2 and Beyond](/v2-go-modules)
Go projects use a wide variety of dependency management strategies.
-[[https://golang.org/cmd/go/#hdr-Vendor_Directories][Vendoring]] tools such
-as [[https://github.com/golang/dep][dep]] and [[https://github.com/Masterminds/glide][glide]] are popular,
+[Vendoring](https://golang.org/cmd/go/#hdr-Vendor_Directories) tools such
+as [dep](https://github.com/golang/dep) and [glide](https://github.com/Masterminds/glide) are popular,
but they have wide differences in behavior and don't always work well together.
Some projects store their entire GOPATH directory in a single Git repository.
-Others simply rely on `go`get` and expect fairly recent versions of dependencies
+Others simply rely on `go get` and expect fairly recent versions of dependencies
to be installed in GOPATH.
Go's module system, introduced in Go 1.11,
@@ -30,18 +31,18 @@
We'll explain how to do that without breaking your users in a future article
focused on v2 and beyond.
-* Migrating to Go modules in your project
+## Migrating to Go modules in your project
A project might be in one of three states when beginning the transition to Go modules:
-- A brand new Go project.
-- An established Go project with a non-modules dependency manager.
-- An established Go project without any dependency manager.
+ - A brand new Go project.
+ - An established Go project with a non-modules dependency manager.
+ - An established Go project without any dependency manager.
-The first case is covered in [[https://blog.golang.org/using-go-modules][Using Go Modules]];
+The first case is covered in [Using Go Modules](https://blog.golang.org/using-go-modules);
we'll address the latter two in this post.
-* With a dependency manager
+## With a dependency manager
To convert a project that already uses a dependency management tool, run the following commands:
@@ -77,12 +78,12 @@
require rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca
$
-`go`mod`init` creates a new go.mod file and automatically imports dependencies from `Godeps.json`,
-`Gopkg.lock`, or a number of [[https://go.googlesource.com/go/+/362625209b6cd2bc059b6b0a67712ddebab312d9/src/cmd/go/internal/modconv/modconv.go#9][other supported formats]].
-The argument to `go`mod`init` is the module path,
+`go mod init` creates a new go.mod file and automatically imports dependencies from `Godeps.json`,
+`Gopkg.lock`, or a number of [other supported formats](https://go.googlesource.com/go/+/362625209b6cd2bc059b6b0a67712ddebab312d9/src/cmd/go/internal/modconv/modconv.go#9).
+The argument to `go mod init` is the module path,
the location where the module may be found.
-This is a good time to pause and run `go`build`./...` and `go`test`./...` before continuing.
+This is a good time to pause and run `go build ./...` and `go test ./...` before continuing.
Later steps may modify your `go.mod` file,
so if you prefer to take an iterative approach,
this is the closest your `go.mod` file will be to your pre-modules dependency specification.
@@ -95,13 +96,13 @@
rsc.io/binaryregexp v0.2.1-0.20190524193500-545cabda89ca/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8=
$
-`go`mod`tidy` finds all the packages transitively imported by packages in your module.
+`go mod tidy` finds all the packages transitively imported by packages in your module.
It adds new module requirements for packages not provided by any known module,
and it removes requirements on modules that don't provide any imported packages.
If a module provides packages that are only imported by projects that haven't
migrated to modules yet,
-the module requirement will be marked with an `//`indirect` comment.
-It is always good practice to run `go`mod`tidy` before committing a `go.mod`
+the module requirement will be marked with an `// indirect` comment.
+It is always good practice to run `go mod tidy` before committing a `go.mod`
file to version control.
Let's finish by making sure the code builds and tests pass:
@@ -129,10 +130,10 @@
and compare the resulting versions with your old dependency management file
to ensure that the selected versions are appropriate.
If you find a version that wasn't what you wanted,
-you can find out why using `go`mod`why`-m` and/or `go`mod`graph`,
-and upgrade or downgrade to the correct version using `go`get`.
+you can find out why using `go mod why -m` and/or `go mod graph`,
+and upgrade or downgrade to the correct version using `go get`.
(If the version you request is older than the version that was previously selected,
-`go`get` will downgrade other dependencies as needed to maintain compatibility.) For example,
+`go get` will downgrade other dependencies as needed to maintain compatibility.) For example,
$ go mod why -m rsc.io/binaryregexp
[...]
@@ -141,7 +142,7 @@
$ go get rsc.io/binaryregexp@v0.2.0
$
-* Without a dependency manager
+## Without a dependency manager
For a Go project without a dependency management system, start by creating a `go.mod` file:
@@ -157,9 +158,9 @@
$
Without a configuration file from a previous dependency manager,
-`go`mod`init` will create a `go.mod` file with only the `module` and `go` directives.
+`go mod init` will create a `go.mod` file with only the `module` and `go` directives.
In this example, we set the module path to `golang.org/x/blog` because that
-is its [[https://golang.org/cmd/go/#hdr-Remote_import_paths][custom import path]].
+is its [custom import path](https://golang.org/cmd/go/#hdr-Remote_import_paths).
Users may import packages with this path,
and we must be careful not to change it.
@@ -167,7 +168,7 @@
and the `go` directive declares the expected version of the Go language
used to compile the code within the module.
-Next, run `go`mod`tidy` to add the module's dependencies:
+Next, run `go mod tidy` to add the module's dependencies:
$ go mod tidy
go: finding golang.org/x/website latest
@@ -206,7 +207,7 @@
[...]
$
-`go`mod`tidy` added module requirements for all the packages transitively
+`go mod tidy` added module requirements for all the packages transitively
imported by packages in your module and built a `go.sum` with checksums
for each library at a specific version.
Let's finish by making sure the code still builds and tests still pass:
@@ -222,22 +223,22 @@
? golang.org/x/blog/support/racy [no test files]
$
-Note that when `go`mod`tidy` adds a requirement,
+Note that when `go mod tidy` adds a requirement,
it adds the latest version of the module.
If your `GOPATH` included an older version of a dependency that subsequently
published a breaking change,
-you may see errors in `go`mod`tidy`, `go`build`, or `go`test`.
-If this happens, try downgrading to an older version with `go`get` (for example,
-`go`get`github.com/broken/module@v1.1.0`),
+you may see errors in `go mod tidy`, `go build`, or `go test`.
+If this happens, try downgrading to an older version with `go get` (for example,
+`go get github.com/broken/module@v1.1.0`),
or take the time to make your module compatible with the latest version of each dependency.
-** Tests in module mode
+### Tests in module mode
Some tests may need tweaks after migrating to Go modules.
If a test needs to write files in the package directory,
it may fail when the package directory is in the module cache, which is read-only.
-In particular, this may cause `go`test`all` to fail.
+In particular, this may cause `go test all` to fail.
The test should copy files it needs to write to a temporary directory instead.
If a test relies on relative paths (`../package-in-another-module`) to locate
@@ -252,12 +253,12 @@
If this is the case, you may need to add a `go.mod` file to the source tree to be tested,
or set `GO111MODULE=off` explicitly.
-* Publishing a release
+## Publishing a release
Finally, you should tag and publish a release version for your new module.
This is optional if you haven't released any versions yet,
but without an official release, downstream users will depend on specific
-commits using [[https://golang.org/cmd/go/#hdr-Pseudo_versions][pseudo-versions]],
+commits using [pseudo-versions](https://golang.org/cmd/go/#hdr-Pseudo_versions),
which may be more difficult to support.
$ git tag v1.2.0
@@ -268,31 +269,31 @@
import path, and your dependencies haven't made breaking changes, then adding
the `go.mod` file is backwards-compatible — but it's a significant change, and
may expose existing problems. If you have existing version tags, you should
-increment the [[https://semver.org/#spec-item-7][minor version]]. See
-[[/publishing-go-modules][Publishing Go Modules]] to learn how to increment and
+increment the [minor version](https://semver.org/#spec-item-7). See
+[Publishing Go Modules](/publishing-go-modules) to learn how to increment and
publish versions.
-* Imports and canonical module paths
+## Imports and canonical module paths
Each module declares its module path in its `go.mod` file.
Each `import` statement that refers to a package within the module must
have the module path as a prefix of the package path.
However, the `go` command may encounter a repository containing the module
-through many different [[https://golang.org/cmd/go/#hdr-Remote_import_paths][remote import paths]].
+through many different [remote import paths](https://golang.org/cmd/go/#hdr-Remote_import_paths).
For example, both `golang.org/x/lint` and `github.com/golang/lint` resolve
-to repositories containing the code hosted at [[https://go.googlesource.com/lint][go.googlesource.com/lint]].
-The [[https://go.googlesource.com/lint/+/refs/heads/master/go.mod][`go.mod` file]]
+to repositories containing the code hosted at [go.googlesource.com/lint](https://go.googlesource.com/lint).
+The [`go.mod` file](https://go.googlesource.com/lint/+/refs/heads/master/go.mod)
contained in that repository declares its path to be `golang.org/x/lint`,
so only that path corresponds to a valid module.
-Go 1.4 provided a mechanism for declaring canonical import paths using [[https://golang.org/cmd/go/#hdr-Import_path_checking][`//`import` comments]],
+Go 1.4 provided a mechanism for declaring canonical import paths using [`// import` comments](https://golang.org/cmd/go/#hdr-Import_path_checking),
but package authors did not always provide them.
As a result, code written prior to modules may have used a non-canonical
import path for a module without surfacing an error for the mismatch.
When using modules, the import path must match the canonical module path,
so you may need to update `import` statements:
-for example, you may need to change `import`"github.com/golang/lint"` to
-`import`"golang.org/x/lint"`.
+for example, you may need to change `import "github.com/golang/lint"` to
+`import "golang.org/x/lint"`.
Another scenario in which a module's canonical path may differ from its
repository path occurs for Go modules at major version 2 or higher.
@@ -304,15 +305,15 @@
`v2.0.1` may have imported it as `github.com/russross/blackfriday` instead,
and will need to update the import path to include the `/v2` suffix.
-* Conclusion
+## Conclusion
Converting to Go modules should be a straightforward process for most users.
Occasional issues may arise due to non-canonical import paths or breaking
changes within a dependency.
-Future posts will explore [[/publishing-go-modules][publishing new versions]],
+Future posts will explore [publishing new versions](/publishing-go-modules),
v2 and beyond, and ways to debug strange situations.
To provide feedback and help shape the future of dependency management in Go,
-please send us [[https://golang.org/issue/new][bug reports]] or [[https://golang.org/wiki/ExperienceReports][experience reports]].
+please send us [bug reports](https://golang.org/issue/new) or [experience reports](https://golang.org/wiki/ExperienceReports).
Thanks for all your feedback and help improving modules.
diff --git a/content/module-mirror-launch.article b/content/module-mirror-launch.article
index d86a716..a0f3247 100644
--- a/content/module-mirror-launch.article
+++ b/content/module-mirror-launch.article
@@ -1,48 +1,49 @@
-Module Mirror and Checksum Database Launched
+# Module Mirror and Checksum Database Launched
29 Aug 2019
Tags: tools, versioning
+Summary: We are excited to share that our module [mirror](https://proxy.golang.org), [index](https://index.golang.org), and [checksum database](https://sum.golang.org) are now production ready! The `go` command will use the module mirror and checksum database by default for [Go 1.13 module users](https://golang.org/doc/go1.13#introduction). See [proxy.golang.org/privacy](https://proxy.golang.org/privacy) for privacy information about these services and the [go command documentation](https://golang.org/cmd/go/#hdr-Module_downloading_and_verification) for configuration details, including how to disable the use of these servers or use different ones. If you depend on non-public modules, see the [documentation for configuring your environment](https://golang.org/cmd/go/#hdr-Module_configuration_for_non_public_modules).
Katie Hockman
-* Introduction
+##
-We are excited to share that our module [[https://proxy.golang.org][mirror]],
-[[https://index.golang.org][index]], and
-[[https://sum.golang.org][checksum database]] are now production ready! The `go` command
+We are excited to share that our module [mirror](https://proxy.golang.org),
+[index](https://index.golang.org), and
+[checksum database](https://sum.golang.org) are now production ready! The `go` command
will use the module mirror and checksum database by default for
-[[https://golang.org/doc/go1.13#introduction][Go 1.13 module users]]. See
-[[https://proxy.golang.org/privacy][proxy.golang.org/privacy]] for privacy
+[Go 1.13 module users](https://golang.org/doc/go1.13#introduction). See
+[proxy.golang.org/privacy](https://proxy.golang.org/privacy) for privacy
information about these services and the
-[[https://golang.org/cmd/go/#hdr-Module_downloading_and_verification][go command documentation]]
+[go command documentation](https://golang.org/cmd/go/#hdr-Module_downloading_and_verification)
for configuration details, including how to disable the use of these servers or
use different ones. If you depend on non-public modules, see the
-[[https://golang.org/cmd/go/#hdr-Module_configuration_for_non_public_modules][documentation for configuring your environment]].
+[documentation for configuring your environment](https://golang.org/cmd/go/#hdr-Module_configuration_for_non_public_modules).
This post will describe these services and the benefits of using them, and
summarizes some of the points from the
-[[https://youtu.be/KqTySYYhPUE][Go Module Proxy: Life of a Query]] talk at Gophercon 2019.
-See the [[https://youtu.be/KqTySYYhPUE][recording]] if you are interested in the full talk.
+[Go Module Proxy: Life of a Query](https://youtu.be/KqTySYYhPUE) talk at Gophercon 2019.
+See the [recording](https://youtu.be/KqTySYYhPUE) if you are interested in the full talk.
-** Module Mirror
+## Module Mirror
-[[https://blog.golang.org/versioning-proposal][Modules]] are sets of Go packages
+[Modules](https://blog.golang.org/versioning-proposal) are sets of Go packages
that are versioned together, and the contents of each version are immutable.
That immutability provides new opportunities for caching and authentication.
-When `go`get` runs in module mode, it must fetch the module containing the
+When `go get` runs in module mode, it must fetch the module containing the
requested packages, as well as any new dependencies introduced by that module,
updating your
-[[https://golang.org/cmd/go/#hdr-The_go_mod_file][go.mod]] and
-[[https://golang.org/cmd/go/#hdr-Module_downloading_and_verification][go.sum]]
+[go.mod](https://golang.org/cmd/go/#hdr-The_go_mod_file) and
+[go.sum](https://golang.org/cmd/go/#hdr-Module_downloading_and_verification)
files as needed. Fetching modules from version control can be expensive in terms
of latency and storage in your system: the `go` command may be forced to pull down
the full commit history of a repository containing a transitive dependency, even
one that isn’t being built, just to resolve its version.
The solution is to use a module proxy, which speaks an API that is better suited
-to the `go` command’s needs (see `go`help`goproxy`). When `go`get` runs in
+to the `go` command’s needs (see `go help goproxy`). When `go get` runs in
module mode with a proxy, it will work faster by only asking for the specific
module metadata or source code it needs, and not worrying about the rest. Below is
-an example of how the `go` command may use a proxy with `go`get` by requesting the list
+an example of how the `go` command may use a proxy with `go get` by requesting the list
of versions, then the info, mod, and zip file for the latest tagged version.
.image module-mirror-launch/proxy-protocol.png _ 800
@@ -51,15 +52,15 @@
source code in its own storage system, allowing the mirror to continue to serve
source code that is no longer available from the original locations. This can
speed up downloads and protect you from disappearing dependencies. See
-[[https://blog.golang.org/modules2019][Go Modules in 2019]] for more information.
+[Go Modules in 2019](https://blog.golang.org/modules2019) for more information.
The Go team maintains a module mirror, served at
-[[https://proxy.golang.org][proxy.golang.org]], which the `go` command will use by
+[proxy.golang.org](https://proxy.golang.org), which the `go` command will use by
default for module users as of Go 1.13. If you are running an earlier version of the `go`
command, then you can use this service by setting
`GOPROXY=https://proxy.golang.org` in your local environment.
-** Checksum Database
+## Checksum Database
Modules introduced the `go.sum` file, which is a list of SHA-256 hashes of the
source code and `go.mod` files of each dependency when it was first downloaded.
@@ -76,15 +77,15 @@
targeted to you.
Go's solution is a global source of `go.sum` lines, called a
-[[https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#checksum-database][checksum database]],
+[checksum database](https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#checksum-database),
which ensures that the `go` command always adds the same lines to everyone's
`go.sum` file. Whenever the `go` command receives new source code, it can verify the
hash of that code against this global database to make sure the hashes match,
ensuring that everyone is using the same code for a given version.
-The checksum database is served by [[https://sum.golang.org][sum.golang.org]], and
-is built on a [[https://research.swtch.com/tlog][Transparent Log]] (or “Merkle
-tree”) of hashes backed by [[https://github.com/google/trillian][Trillian]]. The
+The checksum database is served by [sum.golang.org](https://sum.golang.org), and
+is built on a [Transparent Log](https://research.swtch.com/tlog) (or “Merkle
+tree”) of hashes backed by [Trillian](https://github.com/google/trillian). The
main advantage of a Merkle tree is that it is tamper proof and has properties
that don’t allow for misbehavior to go undetected, which makes it more
trustworthy than a simple database. The `go` command uses this tree to check
@@ -95,7 +96,7 @@
.image module-mirror-launch/tree.png _ 800
The checksum database supports
-[[https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#checksum-database][a set of endpoints]]
+[a set of endpoints](https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#checksum-database)
used by the `go` command to request and verify `go.sum` lines. The `/lookup`
endpoint provides a “signed tree head” (STH) and the requested `go.sum` lines. The
`/tile` endpoint provides chunks of the tree called _tiles_ which the `go` command
@@ -114,7 +115,7 @@
If you are using Go 1.12 or earlier, you can manually check a `go.sum` file
against the checksum database with
-[[https://godoc.org/golang.org/x/mod/gosumcheck][gosumcheck]]:
+[gosumcheck](https://godoc.org/golang.org/x/mod/gosumcheck):
$ go get golang.org/x/mod/gosumcheck
$ gosumcheck /path/to/go.sum
@@ -125,17 +126,17 @@
the tree as it grows to ensure that it remains uncompromised, and we hope that
the Go community will run them.
-** Module Index
+## Module Index
-The module index is served by [[https://index.golang.org][index.golang.org]], and
+The module index is served by [index.golang.org](https://index.golang.org), and
is a public feed of new module versions that become available through
-[[https://proxy.golang.org][proxy.golang.org]]. This is particularly useful for
+[proxy.golang.org](https://proxy.golang.org). This is particularly useful for
tool developers that want to keep their own cache of what’s available in
-[[https://proxy.golang.org][proxy.golang.org]], or keep up-to-date on some of the
+[proxy.golang.org](https://proxy.golang.org), or keep up-to-date on some of the
newest modules that people are using.
-** Feedback or bugs
+## Feedback or bugs
We hope these services improve your experience with modules, and encourage you
-to [[https://github.com/golang/go/issues/new?title=proxy.golang.org][file issues]] if you run into
+to [file issues](https://github.com/golang/go/issues/new?title=proxy.golang.org) if you run into
problems or have feedback!
diff --git a/content/modules2019.article b/content/modules2019.article
index 6ea86c0..52a290d 100644
--- a/content/modules2019.article
+++ b/content/modules2019.article
@@ -1,10 +1,11 @@
-Go Modules in 2019
+# Go Modules in 2019
19 Dec 2018
Tags: tools, versioning
+Summary: 2018 was a great year for the Go ecosystem, with package management as one of our major focuses. In February, we started a community-wide discussion about how to integrate package management directly into the Go toolchain, and in August we delivered the first rough implementation of that feature, called Go modules, in Go 1.11. The migration to Go modules will be the most far-reaching change for the Go ecosystem since Go 1. Converting the entire ecosystem—code, users, tools, and so on—from GOPATH to modules will require work in many different areas. The module system will in turn help us deliver better authentication and build speeds to the Go ecosystem.
Russ Cox
-* What a year!
+## What a year!
2018 was a great year for the Go ecosystem, with
package management as one of our major focuses.
@@ -22,9 +23,9 @@
This post is a preview of what the Go team is planning
relating to modules in 2019.
-* Releases
+## Releases
-Go 1.11, released in August 2018, introduced [[https://golang.org/doc/go1.11#modules][preliminary support for modules]].
+Go 1.11, released in August 2018, introduced [preliminary support for modules](https://golang.org/doc/go1.11#modules).
For now, module support is maintained alongside the
traditional GOPATH-based mechanisms.
The `go` command defaults to module mode when run
@@ -51,7 +52,7 @@
In order to do that, we’ve been working on better tooling support
along with better support for the open-source module ecosystem.
-* Tooling & IDE Integration
+## Tooling & IDE Integration
In the eight years that we’ve had GOPATH,
an incredible amount of tooling has been created
@@ -59,7 +60,7 @@
Moving to modules requires updating all code that makes
that assumption.
We’ve designed a new package,
-[[https://godoc.org/golang.org/x/tools/go/packages][golang.org/x/tools/go/packages]],
+[golang.org/x/tools/go/packages](https://godoc.org/golang.org/x/tools/go/packages),
that abstracts the operation of finding and loading information
about the Go source code for a given target.
This new package adapts automatically to both
@@ -74,7 +75,7 @@
like gocode, godef, and go-outline
into a single tool that can be used from the
command line and also supports
-the [[https://langserver.org/][language server protocol]]
+the [language server protocol](https://langserver.org/)
used by modern IDEs.
The transition to modules and the changes in package loading
@@ -85,7 +86,7 @@
in which an analyzer is invoked for one package at a time.
In this framework, the analysis of one package can write out facts
made available to analyses of other packages that import the first.
-For example, `go` `vet`’s analysis of the [[https://golang.org/pkg/log/][log package]]
+For example, `go` `vet`’s analysis of the [log package](https://golang.org/pkg/log/)
determines and records the fact that `log.Printf` is a `fmt.Printf` wrapper.
Then `go` `vet` can check printf-style format strings in other packages
that call `log.Printf`.
@@ -93,7 +94,7 @@
program analysis tools to help developers find bugs earlier
and understand code better.
-* Module Index
+## Module Index
One of the most important parts of the original design for `go` `get`
was that it was _decentralized_:
@@ -126,7 +127,7 @@
using simple queries, to allow `goimports` to add
imports for packages that have not yet been downloaded to the local system.
-* Module Authentication
+## Module Authentication
Today, `go` `get` relies on connection-level authentication (HTTPS or SSH)
to check that it is talking to the right server to download code.
@@ -157,8 +158,8 @@
and cryptographically signs statements of the form
“module M at version V has file tree hash H.”
The notary service will publish all these notarized hashes
-in a queryable, [[https://www.certificate-transparency.org/][Certificate Transparency]]-style
-[[http://static.usenix.org/event/sec09/tech/full_papers/crosby.pdf][tamper-proof log]],
+in a queryable, [Certificate Transparency](https://www.certificate-transparency.org/)-style
+[tamper-proof log](http://static.usenix.org/event/sec09/tech/full_papers/crosby.pdf),
so that anyone can verify that the notary is behaving correctly.
This log will serve as a public, global `go.sum` file
that `go` `get` can use to authenticate modules
@@ -168,7 +169,7 @@
for publicly-available modules not already in `go.sum`
starting in Go 1.13.
-* Module Mirrors
+## Module Mirrors
Because the decentralized `go` `get` fetches code from multiple origin servers,
fetching code is only as fast and reliable as the slowest,
@@ -183,7 +184,7 @@
The Go module design introduces the idea of a module proxy,
which is a server that the `go` command asks for modules,
instead of the origin servers.
-One important kind of proxy is a _module_mirror_,
+One important kind of proxy is a _module mirror_,
which answers requests for modules by fetching them
from origin servers and then caching them for use in
future requests.
@@ -210,7 +211,7 @@
Using an alternate mirror, or no mirror at all, will be trivial
to configure.
-* Module Discovery
+## Module Discovery
Finally, we mentioned earlier that the module index will make it easier to
build sites like godoc.org.
@@ -219,7 +220,7 @@
discover available modules
and then decide whether to rely on a given module or not.
-* Big Picture
+## Big Picture
This diagram shows how module source code
moves through the design in this post.
diff --git a/content/new-talk-and-tutorials.article b/content/new-talk-and-tutorials.article
index 3b74ca2..6eeab6c 100644
--- a/content/new-talk-and-tutorials.article
+++ b/content/new-talk-and-tutorials.article
@@ -1,25 +1,26 @@
-New Talk and Tutorials
+# New Talk and Tutorials
5 May 2010
+Summary: Rob Pike recently gave a talk at Stanford's [Computer Systems Colloquium](http://www.stanford.edu/class/ee380/) (EE380). Titled [_Another Go at Language Design_](http://www.stanford.edu/class/ee380/Abstracts/100428.html), the presentation gives an overview of the itches Go was built to scratch, and how Go addresses those problems. You can view [a video stream of the talk](https://www.youtube.com/watch?v=7VcArS4Wpqk), and [download the slides](http://www.stanford.edu/class/ee380/Abstracts/100428-pike-stanford.pdf).
Andrew Gerrand
-* Introduction
+##
-Rob Pike recently gave a talk at Stanford's [[http://www.stanford.edu/class/ee380/][Computer Systems Colloquium]] (EE380).
-Titled [[http://www.stanford.edu/class/ee380/Abstracts/100428.html][_Another_Go_at_Language_Design_]],
+Rob Pike recently gave a talk at Stanford's [Computer Systems Colloquium](http://www.stanford.edu/class/ee380/) (EE380).
+Titled [_Another Go at Language Design_](http://www.stanford.edu/class/ee380/Abstracts/100428.html),
the presentation gives an overview of the itches Go was built to scratch,
and how Go addresses those problems.
-You can view [[https://www.youtube.com/watch?v=7VcArS4Wpqk][a video stream of the talk]],
-and [[http://www.stanford.edu/class/ee380/Abstracts/100428-pike-stanford.pdf][download the slides]].
+You can view [a video stream of the talk](https://www.youtube.com/watch?v=7VcArS4Wpqk),
+and [download the slides](http://www.stanford.edu/class/ee380/Abstracts/100428-pike-stanford.pdf).
-Last week's release included a code lab, [[https://golang.org/doc/codelab/wiki/][Writing Web Applications]],
+Last week's release included a code lab, [Writing Web Applications](https://golang.org/doc/codelab/wiki/),
that details the construction of a simple wiki program.
It is a practical introduction to some fundamental Go concepts,
and the first of a series of Go code labs.
Lastly, we are often asked "How do Go packages work?" It's easier to show than to explain,
-so I put together a [[http://www.youtube.com/watch?v=jDWBJOXs_iI][Go Packages screen cast]]
+so I put together a [Go Packages screen cast](http://www.youtube.com/watch?v=jDWBJOXs_iI)
that demonstrates the process of writing,
building, installing, and redistributing Go packages.
I hope to post more of these covering a variety of Go programming topics
-to the [[http://youtube.com/gocoding][gocoding YouTube channel]] in the near future.
+to the [gocoding YouTube channel](http://youtube.com/gocoding) in the near future.
diff --git a/content/normalization.article b/content/normalization.article
index 636eac8..0076d62 100644
--- a/content/normalization.article
+++ b/content/normalization.article
@@ -1,27 +1,28 @@
-Text normalization in Go
+# Text normalization in Go
26 Nov 2013
Tags: strings, bytes, runes, characters
+Summary: An earlier [post](https://blog.golang.org/strings) talked about strings, bytes and characters in Go. I've been working on various packages for multilingual text processing for the go.text repository. Several of these packages deserve a separate blog post, but today I want to focus on [go.text/unicode/norm](https://godoc.org/code.google.com/p/go.text/unicode/norm), which handles normalization, a topic touched in the [strings article](https://blog.golang.org/strings) and the subject of this post. Normalization works at a higher level of abstraction than raw bytes.
Marcel van Lohuizen
-* Introduction
+## Introduction
-An earlier [[https://blog.golang.org/strings][post]] talked about strings, bytes
+An earlier [post](https://blog.golang.org/strings) talked about strings, bytes
and characters in Go. I've been working on various packages for multilingual
text processing for the go.text repository. Several of these packages deserve a
separate blog post, but today I want to focus on
-[[https://godoc.org/code.google.com/p/go.text/unicode/norm][go.text/unicode/norm]],
+[go.text/unicode/norm](https://godoc.org/code.google.com/p/go.text/unicode/norm),
which handles normalization, a topic touched in the
-[[https://blog.golang.org/strings][strings article]] and the subject of this
+[strings article](https://blog.golang.org/strings) and the subject of this
post. Normalization works at a higher level of abstraction than raw bytes.
To learn pretty much everything you ever wanted to know about normalization
-(and then some), [[http://unicode.org/reports/tr15/][Annex 15 of the Unicode Standard]]
+(and then some), [Annex 15 of the Unicode Standard](http://unicode.org/reports/tr15/)
is a good read. A more approachable article is the corresponding
-[[http://en.wikipedia.org/wiki/Unicode_equivalence][Wikipedia page]]. Here we
+[Wikipedia page](http://en.wikipedia.org/wiki/Unicode_equivalence). Here we
focus on how normalization relates to Go.
-* What is normalization?
+## What is normalization?
There are often several ways to represent the same string. For example, an é
(e-acute) can be represented in a string as a single rune ("\u00e9") or an 'e'
@@ -46,12 +47,12 @@
.html normalization/table1.html
-* Go's approach to normalization
+## Go's approach to normalization
As mentioned in the strings blog post, Go does not guarantee that characters in
a string are normalized. However, the go.text packages can compensate. For
example, the
-[[https://godoc.org/code.google.com/p/go.text/collate][collate]] package, which
+[collate](https://godoc.org/code.google.com/p/go.text/collate) package, which
can sort strings in a language-specific way, works correctly even with
unnormalized strings. The packages in go.text do not always require normalized
input, but in general normalization may be necessary for consistent results.
@@ -59,7 +60,7 @@
Normalization isn't free but it is fast, particularly for collation and
searching or if a string is either in NFD or in NFC and can be converted to NFD
by decomposing without reordering its bytes. In practice,
-[[http://www.macchiato.com/unicode/nfc-faq#TOC-How-much-text-is-already-NFC-][99.98%]] of
+[99.98%](http://www.macchiato.com/unicode/nfc-faq#TOC-How-much-text-is-already-NFC-) of
the web's HTML page content is in NFC form (not counting markup, in which case
it would be more). By far most NFC can be decomposed to NFD without the need
for reordering (which requires allocation). Also, it is efficient to detect
@@ -78,7 +79,7 @@
Of course, we can also avoid the overhead outright if we know in advance that a
string is already normalized, which is often the case.
-* Why bother?
+## Why bother?
After all this discussion about avoiding normalization, you might ask why it's
worth worrying about at all. The reason is that there are cases where
@@ -87,7 +88,7 @@
Before discussing those, we must first clarify the concept of 'character'.
-* What is a character?
+## What is a character?
As was mentioned in the strings blog post, characters can span multiple runes.
For example, an 'e' and '◌́' (acute "\u0301") can combine to form 'é' ("e\u0301"
@@ -119,7 +120,7 @@
adopts this approach for all normalization algorithms. This decision gives up a
little conformance but gains a little safety.
-* Writing in normal form
+## Writing in normal form
Even if you don't need to normalize text within your Go code, you might still
want to do so when communicating to the outside world. For example, normalizing
@@ -129,7 +130,7 @@
in and output your text as NFC like the rest of the world.
To write your text as NFC, use the
-[[https://godoc.org/code.google.com/p/go.text/unicode/norm][unicode/norm]] package
+[unicode/norm](https://godoc.org/code.google.com/p/go.text/unicode/norm) package
to wrap your `io.Writer` of choice:
wc := norm.NFC.Writer(w)
@@ -144,7 +145,7 @@
Package norm provides various other methods for normalizing text.
Pick the one that suits your needs best.
-* Catching look-alikes
+## Catching look-alikes
Can you tell the difference between 'K' ("\u004B") and 'K' (Kelvin sign
"\u212A") or 'Ω' ("\u03a9") and 'Ω' (Ohm sign "\u2126")? It is easy to overlook
@@ -159,7 +160,7 @@
'o', Greek 'ο', and Cyrillic 'о' are still different characters as defined by
these forms.
-* Correct text modifications
+## Correct text modifications
The norm package might also come to the rescue when one needs to modify text.
Consider a case where you want to search and replace the word "cafe" with its
@@ -202,14 +203,14 @@
problems can be avoided by using search functionality that respects character
boundaries (such as the planned go.text/search package.)
-* Iteration
+## Iteration
Another tool provided by the norm package that may help dealing with character
boundaries is its iterator,
-[[https://godoc.org/code.google.com/p/go.text/unicode/norm#Iter][`norm.Iter`]].
+[`norm.Iter`](https://godoc.org/code.google.com/p/go.text/unicode/norm#Iter).
It iterates over characters one at a time in the normal form of choice.
-* Performing magic
+## Performing magic
As mentioned earlier, most text is in NFC form, where base characters and
modifiers are combined into a single rune whenever possible. For the purpose
@@ -240,16 +241,16 @@
This will, for example, convert any mention of "cafés" in the text to "cafes",
regardless of the normal form in which the original text was encoded.
-* Normalization info
+## Normalization info
As mentioned earlier, some packages precompute normalizations into their tables
to minimize the need for normalization at run time. The type `norm.Properties`
provides access to the per-rune information needed by these packages, most
notably the Canonical Combining Class and decomposition information. Read the
-[[https://godoc.org/code.google.com/p/go.text/unicode/norm/#Properties][documentation]]
+[documentation](https://godoc.org/code.google.com/p/go.text/unicode/norm/#Properties)
for this type if you want to dig deeper.
-* Performance
+## Performance
To give an idea of the performance of normalization, we compare it against the
performance of strings.ToLower. The sample in the first row is both lowercase
@@ -269,7 +270,7 @@
we may change the implementation at some point to speed up the common case for
small strings even further.
-* Conclusion
+## Conclusion
If you're dealing with text inside Go, you generally do not have to use the
unicode/norm package to normalize your text. The package may still be useful
diff --git a/content/open-source.article b/content/open-source.article
index 9ee5324..500f097 100644
--- a/content/open-source.article
+++ b/content/open-source.article
@@ -1,13 +1,14 @@
-Go, Open Source, Community
-08 Jul 2015
+# Go, Open Source, Community
+8 Jul 2015
Tags: community
+Summary: [This is the text of my opening keynote at Gophercon 2015. [The video is available here](https://www.youtube.com/watch?v=XvZOdpd_9tc).]
Russ Cox
-* Welcome
+## Welcome
[This is the text of my opening keynote at Gophercon 2015.
-[[https://www.youtube.com/watch?v=XvZOdpd_9tc][The video is available here]].]
+[The video is available here](https://www.youtube.com/watch?v=XvZOdpd_9tc).]
Thank you all for traveling to Denver to be here,
and thank you to everyone watching on video.
@@ -33,7 +34,7 @@
how I see the Go open source project
evolving.
-* Why Go?
+## Why Go?
To get started,
we have to go back to the beginning.
@@ -96,7 +97,7 @@
Here are two.
Last year, on RedMonk.com, Donnie Berkholz
wrote about
-“[[http://redmonk.com/dberkholz/2014/03/18/go-the-emerging-language-of-cloud-infrastructure/][Go as the emerging language of cloud infrastructure]],”
+“[Go as the emerging language of cloud infrastructure](http://redmonk.com/dberkholz/2014/03/18/go-the-emerging-language-of-cloud-infrastructure/),”
observing that
“[Go's] marquee projects ... are cloud-centric or otherwise
made for dealing with distributed systems
@@ -104,13 +105,13 @@
This year, on Texlution.com, the author
wrote an article titled
-“[[https://texlution.com/post/why-go-is-doomed-to-succeed/][Why Golang is doomed to succeed]],”
+“[Why Golang is doomed to succeed](https://texlution.com/post/why-go-is-doomed-to-succeed/),”
pointing out that this focus on large-scale development
was possibly even better suited to open source than
to Google itself: “This open source fitness is why I think
you are about to see more and more Go around ...”
-* The Go Balance
+## The Go Balance
How does Go accomplish those things?
@@ -131,7 +132,7 @@
Instead, we've tried to do just enough that you can build
your own custom solutions easily.
-The way I would summarize Go's chosen balance is this: *Do*Less.*Enable*More.*
+The way I would summarize Go's chosen balance is this: **Do Less. Enable More.**
Do less, but enable more.
@@ -147,7 +148,7 @@
and ideally can interoperate with
the solutions and tools built by others.
-** Examples
+### Examples
Let me illustrate this with some examples.
@@ -351,7 +352,7 @@
I'm going to return to that idea later.
-* Why is Go open source?
+## Why is Go open source?
But first, as I said earlier,
I want to explain how I see
@@ -434,7 +435,7 @@
while doing less.
Open source is a huge part of that.
-* Go's open source
+## Go's open source
What does open source mean?
The minimum requirement is to open the source code,
@@ -496,7 +497,7 @@
earlier:
Do Less, Enable More.
-* Google's role
+## Google's role
A natural question is:
What is the role
@@ -628,7 +629,7 @@
Everyone contributing to Go
should have the opportunity to be heard.
-** Examples
+### Examples
I want to share some evidence for this claim
that, over time,
@@ -861,7 +862,7 @@
This brings me to my last point.
-* Code of Conduct
+## Code of Conduct
I've argued that Go must be open,
and that Go needs your help.
@@ -1069,7 +1070,7 @@
We need all the help we can get.
We need a large, diverse Go community.
-* Thank You
+## Thank You
I consider the many people
releasing software for download using “go get,”
diff --git a/content/organizing-go-code.article b/content/organizing-go-code.article
index 5be76a0..ff87bf4 100644
--- a/content/organizing-go-code.article
+++ b/content/organizing-go-code.article
@@ -1,22 +1,23 @@
-Organizing Go code
+# Organizing Go code
16 Aug 2012
Tags: godoc, gopath, interface, libraries, tools, technical
+Summary: Go code is organized differently to that of other languages. This post discusses how to name and package the elements of your Go program to best serve its users.
Andrew Gerrand
-* Introduction
+## Introduction
Go code is organized differently to that of other languages.
This post discusses how to name and package the elements of your Go program
to best serve its users.
-* Choose good names
+## Choose good names
The names you choose affect how you think about your code,
so take care when naming your package and its exported identifiers.
A package's name provides context for its contents.
-For instance, the [[https://golang.org/pkg/bytes/][bytes package]] from
+For instance, the [bytes package](https://golang.org/pkg/bytes/) from
the standard library exports the `Buffer` type.
On its own, the name `Buffer` isn't very descriptive,
but when combined with its package name its meaning becomes clear: `bytes.Buffer`.
@@ -27,7 +28,7 @@
As you spend time with your program you will better understand how its pieces fit together and,
therefore, what their names should be.
There's no need to lock yourself into early decisions.
-(The [[https://golang.org/cmd/gofmt/][gofmt command]] has a `-r` flag that
+(The [gofmt command](https://golang.org/cmd/gofmt/) has a `-r` flag that
provides a syntax-aware search and replace,
making large-scale refactoring easier.)
@@ -36,7 +37,7 @@
A well-chosen name is therefore the starting point for good documentation.
Many of the following practices result organically from good naming.
-* Choose a good import path (make your package "go get"-able)
+## Choose a good import path (make your package "go get"-able)
An import path is the string with which users import a package.
It specifies the directory (relative to `$GOROOT/src/pkg` or `$GOPATH/src`)
@@ -48,7 +49,7 @@
The Go project owns the path `"github.com/golang"`,
so that path cannot be used by another author for a different package.
Because the repository URL and import path are one and the same,
-the `go`get` command can fetch and install the package automatically.
+the `go get` command can fetch and install the package automatically.
If you don't use a hosted source repository,
choose some unique prefix such as a domain,
@@ -68,10 +69,10 @@
such as `"src/my/package"`.
On one hand, this keeps the import paths short (`"my/package"` instead of
`"github.com/me/project/my/package"`),
-but on the other it breaks `go`get` and forces users to re-set their `GOPATH`
+but on the other it breaks `go get` and forces users to re-set their `GOPATH`
to use the package. Don't do this.
-* Minimize the exported interface
+## Minimize the exported interface
Your code is likely composed of many small pieces of useful code,
and so it is tempting to expose much of that functionality in your package's
@@ -88,7 +89,7 @@
If in doubt, leave it out!
-* What to put into a package
+## What to put into a package
It is easy to just throw everything into a "grab bag" package,
but this dilutes the meaning of the package name (as it must encompass a
@@ -102,9 +103,9 @@
Look to the Go standard libraries as a guide.
Some of its packages are large and some are small.
-For instance, the [[https://golang.org/pkg/net/http/][http package]] comprises
+For instance, the [http package](https://golang.org/pkg/net/http/) comprises
17 go source files (excluding tests) and exports 109 identifiers,
-and the [[https://golang.org/pkg/hash/][hash package]] consists of one file
+and the [hash package](https://golang.org/pkg/hash/) consists of one file
that exports just three declarations.
There is no hard and fast rule; both approaches are appropriate given their context.
@@ -112,10 +113,10 @@
Complex commands contain a lot of code that is of little use outside the
context of the executable,
and often it's simpler to just keep it all in the one place.
-For instance, the go tool is more than 12000 lines spread across [[https://golang.org/src/cmd/go/][34 files]].
+For instance, the go tool is more than 12000 lines spread across [34 files](https://golang.org/src/cmd/go/).
-* Document your code
+## Document your code
Good documentation is an essential quality of usable and maintainable code.
-Read the [[https://golang.org/doc/articles/godoc_documenting_go_code.html][Godoc: documenting Go code]]
+Read the [Godoc: documenting Go code](https://golang.org/doc/articles/godoc_documenting_go_code.html)
article to learn how to write good doc comments.
diff --git a/content/oscon.article b/content/oscon.article
index 8e929f8..00b705b 100644
--- a/content/oscon.article
+++ b/content/oscon.article
@@ -1,47 +1,48 @@
-Go will be at OSCON 2014
+# Go will be at OSCON 2014
15 Jul 2014
Tags: conference, oscon
+Summary: [OSCON](http://www.oscon.com), the Open Source Convention, is taking place from July 20th to the 29th in Portland, Oregon and Go will be central to many talks. If you are attending make sure you add these to your personal schedule.
Francesc Campoy
-* Go will be at OSCON 2014
+##
-[[http://www.oscon.com][OSCON]], the Open Source Convention, is taking place
+[OSCON](http://www.oscon.com), the Open Source Convention, is taking place
from July 20th to the 29th in Portland, Oregon and Go will be central to many
talks. If you are attending make sure you add these to your personal schedule.
On Monday you'll have the chance to learn Go in these two tutorials:
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34395][Getting Started with Go]]
- by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) at 9:00am on Monday, 07/21/2014
+ - [Getting Started with Go](http://www.oscon.com/oscon2014/public/schedule/detail/34395)
+ by [Steve Francia](http://twitter.com/spf13) (MongoDB) at 9:00am on Monday, 07/21/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34267][A Quick Introduction to System Tools Programming with Go]]
- by [[http://twitter.com/macmceniry][Chris McEniry]] (Sony Network Entertainment)
- at 1:30pm on Monday, 07/21/2014
+ - [A Quick Introduction to System Tools Programming with Go](http://www.oscon.com/oscon2014/public/schedule/detail/34267)
+ by [Chris McEniry](http://twitter.com/macmceniry) (Sony Network Entertainment)
+ at 1:30pm on Monday, 07/21/2014
During the rest of the week you can hear how different projects use Go:
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34371][A Recovering Java Developer Learns to Go]]
- by [[http://twitter.com/mstine][Matt Stine]] (Pivotal) at 1:40pm on Tuesday, 07/22/2014
+ - [A Recovering Java Developer Learns to Go](http://www.oscon.com/oscon2014/public/schedule/detail/34371)
+ by [Matt Stine](http://twitter.com/mstine) (Pivotal) at 1:40pm on Tuesday, 07/22/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34299][Painless Data Storage with MongoDB and Go]]
- by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) and [[http://twitter.com/gniemeyer][Gustavo Niemeyer]]
- (Canonical) at 1:40pm on Tuesday, 07/22/2014
+ - [Painless Data Storage with MongoDB and Go](http://www.oscon.com/oscon2014/public/schedule/detail/34299)
+ by [Steve Francia](http://twitter.com/spf13) (MongoDB) and [Gustavo Niemeyer](http://twitter.com/gniemeyer)
+ (Canonical) at 1:40pm on Tuesday, 07/22/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/37795][Gophers with Hammers: Fun with Parsing and Generating Go]]
- by [[http://twitter.com/offbymany][Josh Bleecher Snyder]] (PayPal) at 2:30pm
- on Tuesday, 07/22/2014
+ - [Gophers with Hammers: Fun with Parsing and Generating Go](http://www.oscon.com/oscon2014/public/schedule/detail/37795)
+ by [Josh Bleecher Snyder](http://twitter.com/offbymany) (PayPal) at 2:30pm
+ on Tuesday, 07/22/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34047][Go for Object Oriented Programmers (or OO Programming without Objects)]]
- by [[http://twitter.com/spf13][Steve Francia]] (MongoDB) at 4:10pm on
- Wednesday, 07/23/2014
+ - [Go for Object Oriented Programmers (or OO Programming without Objects)](http://www.oscon.com/oscon2014/public/schedule/detail/34047)
+ by [Steve Francia](http://twitter.com/spf13) (MongoDB) at 4:10pm on
+ Wednesday, 07/23/2014
-- [[http://www.oscon.com/oscon2014/public/schedule/detail/34509][Inside the Go Tour]]
- by [[http://twitter.com/francesc][Francesc Campoy Flores]] (Google Inc.)
- at 11:50am on Thursday, 07/24/2014
+ - [Inside the Go Tour](http://www.oscon.com/oscon2014/public/schedule/detail/34509)
+ by [Francesc Campoy Flores](http://twitter.com/francesc) (Google Inc.)
+ at 11:50am on Thursday, 07/24/2014
And if you have any questions come to the
-[[http://www.oscon.com/oscon2014/public/schedule/detail/37075][Go office hours]]
+[Go office hours](http://www.oscon.com/oscon2014/public/schedule/detail/37075)
on Wednesday or come anytime by the Google booth.
See you at OSCON!
diff --git a/content/osconreport.article b/content/osconreport.article
index 70b6fab..dfaf438 100644
--- a/content/osconreport.article
+++ b/content/osconreport.article
@@ -1,71 +1,72 @@
-Go at OSCON
+# Go at OSCON
20 Aug 2014
Tags: conference, oscon
+Summary: What happens in Portland in July? [OSCON](http://www.oscon.com/oscon2014)! At this year's conference, Go was more present than ever before, with five talks, two workshops, a [Birds of a Feather](http://en.wikipedia.org/wiki/Birds_of_a_feather_(computing)) session, and a meetup.
Francesc Campoy
-* Introduction
+## Introduction
-What happens in Portland in July? [[http://www.oscon.com/oscon2014][OSCON]]! At
+What happens in Portland in July? [OSCON](http://www.oscon.com/oscon2014)! At
this year's conference, Go was more present than ever before, with five talks,
two workshops, a
-[[http://en.wikipedia.org/wiki/Birds_of_a_feather_(computing)][Birds of a Feather]]
+[Birds of a Feather](http://en.wikipedia.org/wiki/Birds_of_a_feather_(computing))
session, and a meetup.
-* Talks
+## Talks
-[[http://twitter.com/mstine][Matt Stine]] talked about his experience switching
+[Matt Stine](http://twitter.com/mstine) talked about his experience switching
from Java to Go with
-[[http://www.slideshare.net/mstine/java-devlearnstogooscon][A recovering Java developer learns Go]]
-while [[https://twitter.com/spf13][Steve Francia]] presented
-[[http://spf13.com/presentation/MongoDB-and-Go][Painless Data Storage with MongoDB and Go]].
+[A recovering Java developer learns Go](http://www.slideshare.net/mstine/java-devlearnstogooscon)
+while [Steve Francia](https://twitter.com/spf13) presented
+[Painless Data Storage with MongoDB and Go](http://spf13.com/presentation/MongoDB-and-Go).
Steve also presented
-[[http://spf13.com/presentation/go-for-object-oriented-programmers][Go for Object Oriented Programmers]],
+[Go for Object Oriented Programmers](http://spf13.com/presentation/go-for-object-oriented-programmers),
where he explained how some object oriented concepts can be implemented in Go.
.image osconreport/talks.png _ 800
-Finally, [[http://twitter.com/offbymany][Josh Bleecher Snyder]] talked about his
+Finally, [Josh Bleecher Snyder](http://twitter.com/offbymany) talked about his
experience writing tools to work with Go source code in
-[[https://talks.golang.org/2014/hammers.slide#1][Gophers with hammers]],
-and [[http://twitter.com/francesc][Francesc Campoy]] talked about all the things
+[Gophers with hammers](https://talks.golang.org/2014/hammers.slide#1),
+and [Francesc Campoy](http://twitter.com/francesc) talked about all the things
that could have gone wrong and what the Go team did to prevent them
-[[https://talks.golang.org/2014/playground.slide][Inside the Go playground]].
+[Inside the Go playground](https://talks.golang.org/2014/playground.slide).
-* Workshops
+## Workshops
At the beginning of OSCON's workshop day, Steve Francia presented how to build a
web application and a CLI tool during
-[[http://spf13.com/presentation/first-go-app][Getting started with Go]] to a big
+[Getting started with Go](http://spf13.com/presentation/first-go-app) to a big
room full of Gophers.
.image osconreport/workshops.png _ 800
-In the afternoon, [[https://twitter.com/mmceniry][Chris McEniry]] gave his
-[[http://cdn.oreillystatic.com/en/assets/1/event/115/A%20Quick%20Introduction%20to%20System%20Tools%20Programming%20with%20Go%20Presentation.pdf][Quick introduction to system tools programming with Go]] where he went over some useful skills to
+In the afternoon, [Chris McEniry](https://twitter.com/mmceniry) gave his
+[Quick introduction to system tools programming with Go](http://cdn.oreillystatic.com/en/assets/1/event/115/A%20Quick%20Introduction%20to%20System%20Tools%20Programming%20with%20Go%20Presentation.pdf) where he went over some useful skills to
write system tools using Go and its standard library.
-* Additional events
+## Additional events
To take advantage of the increased Gopher population in Portland during OSCON, we
-organized two extra events: the first [[https://twitter.com/pdxgolang][PDXGolang]]
+organized two extra events: the first [PDXGolang](https://twitter.com/pdxgolang)
meetup and a
-[[http://www.oscon.com/oscon2014/public/schedule/detail/37775][Birds of a Feather session]].
+[Birds of a Feather session](http://www.oscon.com/oscon2014/public/schedule/detail/37775).
.image osconreport/meetup.png _ 800
At the meetup Francesc Campoy talked about
-[[https://talks.golang.org/2013/bestpractices.slide][Go Best Practices]] and
-[[https://twitter.com/kelseyhightower][Kelsey Hightower]] gave a great
-introduction to [[https://github.com/GoogleCloudPlatform/kubernetes][Kubernetes]],
+[Go Best Practices](https://talks.golang.org/2013/bestpractices.slide) and
+[Kelsey Hightower](https://twitter.com/kelseyhightower) gave a great
+introduction to [Kubernetes](https://github.com/GoogleCloudPlatform/kubernetes),
a container management system for clusters written in Go by Google. If you live
-in Portland, make sure you [[http://meetup.com/pdx-go][join the group]] and come
+in Portland, make sure you [join the group](http://meetup.com/pdx-go) and come
along to the next meeting.
The "Birds of a Feather" (or, more aptly, "Gophers of a Feather") was a lot of
fun for everyone involved. We hope to see more of you there next year.
-* In conclusion
+## In conclusion
.image osconreport/random.png _ 800
diff --git a/content/package-names.article b/content/package-names.article
index 2cd74d1..bf92642 100644
--- a/content/package-names.article
+++ b/content/package-names.article
@@ -1,10 +1,11 @@
-Package names
+# Package names
4 Feb 2015
Tags: package, names, style
+Summary: Go code is organized into packages. Within a package, code can refer to any identifier (name) defined within, while clients of the package may only reference the package's exported types, functions, constants, and variables. Such references always include the package name as a prefix: `foo.Bar` refers to the exported name `Bar` in the imported package named `foo`.
Sameer Ajmani
-* Introduction
+## Introduction
Go code is organized into packages.
Within a package, code can refer to any identifier (name) defined within, while
@@ -21,66 +22,66 @@
Well-named packages make it easier to find the code you need.
Effective Go provides
-[[https://golang.org/doc/effective_go.html#names][guidelines]] for naming
+[guidelines](https://golang.org/doc/effective_go.html#names) for naming
packages, types, functions, and variables.
This article expands on that discussion and surveys names found in the standard
library.
It also discusses bad package names and how to fix them.
-* Package names
+## Package names
Good package names are short and clear.
They are lower case, with no `under_scores` or `mixedCaps`.
They are often simple nouns, such as:
-- `time` (provides functionality for measuring and displaying time)
-- `list` (implements a doubly linked list)
-- `http` (provides HTTP client and server implementations)
+ - `time` (provides functionality for measuring and displaying time)
+ - `list` (implements a doubly linked list)
+ - `http` (provides HTTP client and server implementations)
The style of names typical of another language might not be idiomatic in a Go
program.
Here are two examples of names that might be good style in other languages but
do not fit well in Go:
-- `computeServiceClient`
-- `priority_queue`
+ - `computeServiceClient`
+ - `priority_queue`
A Go package may export several types and functions.
For example, a `compute` package could export a `Client` type with methods for
using the service as well as functions for partitioning a compute task across
several clients.
-*Abbreviate*judiciously.*
+**Abbreviate judiciously.**
Package names may be abbreviated when the abbreviation is familiar to the
programmer.
Widely-used packages often have compressed names:
-- `strconv` (string conversion)
-- `syscall` (system call)
-- `fmt` (formatted I/O)
+ - `strconv` (string conversion)
+ - `syscall` (system call)
+ - `fmt` (formatted I/O)
On the other hand, if abbreviating a package name makes it ambiguous or unclear,
don't do it.
-*Don't*steal*good*names*from*the*user.*
+**Don't steal good names from the user.**
Avoid giving a package a name that is commonly used in client code.
For example, the buffered I/O package is called `bufio`, not `buf`, since `buf`
is a good variable name for a buffer.
-* Naming package contents
+## Naming package contents
A package name and its contents' names are coupled, since client code uses them
together.
When designing a package, take the client's point of view.
-*Avoid*stutter.*
+**Avoid stutter.**
Since client code uses the package name as a prefix when referring to the
package contents, the names for those contents need not repeat the package name.
The HTTP server provided by the `http` package is called `Server`, not
`HTTPServer`.
Client code refers to this type as `http.Server`, so there is no ambiguity.
-*Simplify*function*names.*
+**Simplify function names.**
When a function in package pkg returns a value of type `pkg.Pkg` (or
`*pkg.Pkg`), the function name can often omit the type name without confusion:
@@ -116,7 +117,7 @@
This approach will yield packages that are easier for clients to understand and
for the package developers to maintain.
-* Package paths
+## Package paths
A Go package has both a name and a path.
The package name is specified in the package statement of its source files;
@@ -132,13 +133,13 @@
)
Build tools map package paths onto directories.
-The go tool uses the [[https://golang.org/doc/code.html#GOPATH][GOPATH]]
+The go tool uses the [GOPATH](https://golang.org/doc/code.html#GOPATH)
environment variable to find the source files for path `"github.com/user/hello"`
in directory `$GOPATH/src/github.com/user/hello`.
(This situation should be familiar, of course, but it's important to be clear
about the terminology and structure of packages.)
-*Directories.*
+**Directories.**
The standard library uses like directories `crypto`, `container`, `encoding`,
and `image` to group packages for related protocols and algorithms.
There is no actual relationship among the packages in one of these directories;
@@ -149,23 +150,23 @@
Just as types in different packages can have the same name without ambiguity,
packages in different directories can have the same name.
For example,
-[[https://golang.org/pkg/runtime/pprof][runtime/pprof]] provides profiling data
-in the format expected by the [[https://github.com/google/pprof][pprof]]
-profiling tool, while [[https://golang.org/pkg/net/http/pprof][net/http/pprof]]
+[runtime/pprof](https://golang.org/pkg/runtime/pprof) provides profiling data
+in the format expected by the [pprof](https://github.com/google/pprof)
+profiling tool, while [net/http/pprof](https://golang.org/pkg/net/http/pprof)
provides HTTP endpoints to present profiling data in this format.
Client code uses the package path to import the package, so there is no
confusion.
If a source file needs to import both `pprof` packages, it can
-[[https://golang.org/ref/spec#Import_declarations][rename]] one or both locally.
+[rename](https://golang.org/ref/spec#Import_declarations) one or both locally.
When renaming an imported package, the local name should follow the same
guidelines as package names (lower case, no `under_scores` or `mixedCaps`).
-* Bad package names
+## Bad package names
Bad package names make code harder to navigate and maintain.
Here are some guidelines for recognizing and fixing bad names.
-*Avoid*meaningless*package*names.*
+**Avoid meaningless package names.**
Packages named `util`, `common`, or `misc` provide clients with no sense of what
the package contains.
This makes it harder for clients to use the package and makes it harder for
@@ -176,7 +177,7 @@
other packages imported by client code, forcing clients to invent names to
distinguish them.
-*Break*up*generic*packages.*
+**Break up generic packages.**
To fix such packages, look for types and functions with common name elements and
pull them into their own package.
For example, if you have
@@ -217,7 +218,7 @@
The name of the package is a critical piece of its design.
Work to eliminate meaningless package names from your projects.
-*Don't*use*a*single*package*for*all*your*APIs.*
+**Don't use a single package for all your APIs.**
Many well-intentioned programmers put all the interfaces exposed by their
program into a single package named `api`, `types`, or `interfaces`, thinking it
makes it easier to find the entry points to their code base.
@@ -228,23 +229,23 @@
Break them up, perhaps using directories to separate public packages from
implementation.
-*Avoid*unnecessary*package*name*collisions.*
+**Avoid unnecessary package name collisions.**
While packages in different directories may have the same name, packages that
are frequently used together should have distinct names.
This reduces confusion and the need for local renaming in client code.
For the same reason, avoid using the same name as popular standard packages like
`io` or `http`.
-* Conclusion
+## Conclusion
Package names are central to good naming in Go programs.
Take the time to choose good package names and organize your code well.
This helps clients understand and use your packages and helps maintainers to
grow them gracefully.
-* Further reading
+## Further reading
-- [[https://golang.org/doc/effective_go.html][Effective Go]]
-- [[https://golang.org/doc/code.html][How to Write Go Code]]
-- [[https://blog.golang.org/organizing-go-code][Organizing Go Code (2012 blog post)]]
-- [[https://talks.golang.org/2014/organizeio.slide][Organizing Go Code (2014 Google I/O talk)]]
+ - [Effective Go](https://golang.org/doc/effective_go.html)
+ - [How to Write Go Code](https://golang.org/doc/code.html)
+ - [Organizing Go Code (2012 blog post)](https://blog.golang.org/organizing-go-code)
+ - [Organizing Go Code (2014 Google I/O talk)](https://talks.golang.org/2014/organizeio.slide)
diff --git a/content/pipelines.article b/content/pipelines.article
index 194b26c..f2fe186 100644
--- a/content/pipelines.article
+++ b/content/pipelines.article
@@ -1,26 +1,27 @@
-Go Concurrency Patterns: Pipelines and cancellation
+# Go Concurrency Patterns: Pipelines and cancellation
13 Mar 2014
Tags: concurrency, pipelines, cancellation
+Summary: Go's concurrency primitives make it easy to construct streaming data pipelines that make efficient use of I/O and multiple CPUs. This article presents examples of such pipelines, highlights subtleties that arise when operations fail, and introduces techniques for dealing with failures cleanly.
Sameer Ajmani
-* Introduction
+## Introduction
Go's concurrency primitives make it easy to construct streaming data pipelines
that make efficient use of I/O and multiple CPUs. This article presents
examples of such pipelines, highlights subtleties that arise when operations
fail, and introduces techniques for dealing with failures cleanly.
-* What is a pipeline?
+## What is a pipeline?
There's no formal definition of a pipeline in Go; it's just one of many kinds of
concurrent programs. Informally, a pipeline is a series of _stages_ connected
by channels, where each stage is a group of goroutines running the same
function. In each stage, the goroutines
-- receive values from _upstream_ via _inbound_ channels
-- perform some function on that data, usually producing new values
-- send values _downstream_ via _outbound_ channels
+ - receive values from _upstream_ via _inbound_ channels
+ - perform some function on that data, usually producing new values
+ - send values _downstream_ via _outbound_ channels
Each stage has any number of inbound and outbound channels, except the
first and last stages, which have only outbound or inbound channels,
@@ -30,7 +31,7 @@
We'll begin with a simple example pipeline to explain the ideas and techniques.
Later, we'll present a more realistic example.
-* Squaring numbers
+## Squaring numbers
Consider a pipeline with three stages.
@@ -59,7 +60,7 @@
.code pipelines/square2.go /func main/,/^}/
-* Fan-out, fan-in
+## Fan-out, fan-in
Multiple functions can read from the same channel until that channel is closed;
this is called _fan-out_. This provides a way to distribute work amongst a group
@@ -83,17 +84,17 @@
Sends on a closed channel panic, so it's important to ensure all sends
are done before calling close. The
-[[https://golang.org/pkg/sync/#WaitGroup][`sync.WaitGroup`]] type
+[`sync.WaitGroup`](https://golang.org/pkg/sync/#WaitGroup) type
provides a simple way to arrange this synchronization:
.code pipelines/sqfan.go /func merge/,/^}/
-* Stopping short
+## Stopping short
There is a pattern to our pipeline functions:
-- stages close their outbound channels when all the send operations are done.
-- stages keep receiving values from inbound channels until those channels are closed.
+ - stages close their outbound channels when all the send operations are done.
+ - stages keep receiving values from inbound channels until those channels are closed.
This pattern allows each receiving stage to be written as a `range` loop and
ensures that all goroutines exit once all values have been successfully sent
@@ -147,7 +148,7 @@
Instead, we need to provide a way for downstream stages to indicate to the
senders that they will stop accepting input.
-* Explicit cancellation
+## Explicit cancellation
When `main` decides to exit without receiving all the values from
`out`, it must tell the goroutines in the upstream stages to abandon
@@ -174,7 +175,7 @@
We need a way to tell an unknown and unbounded number of goroutines to
stop sending their values downstream. In Go, we can do this by
closing a channel, because
-[[https://golang.org/ref/spec#Receive_operator][a receive operation on a closed channel can always proceed immediately, yielding the element type's zero value.]]
+[a receive operation on a closed channel can always proceed immediately, yielding the element type's zero value.](https://golang.org/ref/spec#Receive_operator)
This means that `main` can unblock all the senders simply by closing
the `done` channel. This close is effectively a broadcast signal to
@@ -200,14 +201,14 @@
Here are the guidelines for pipeline construction:
-- stages close their outbound channels when all the send operations are done.
-- stages keep receiving values from inbound channels until those channels are closed or the senders are unblocked.
+ - stages close their outbound channels when all the send operations are done.
+ - stages keep receiving values from inbound channels until those channels are closed or the senders are unblocked.
Pipelines unblock senders either by ensuring there's enough buffer for all the
values that are sent or by explicitly signalling senders when the receiver may
abandon the channel.
-* Digesting a tree
+## Digesting a tree
Let's consider a more realistic pipeline.
@@ -234,14 +235,14 @@
.code pipelines/serial.go /func main/,/^}/
The `MD5All` function is the focus of our discussion. In
-[[pipelines/serial.go][serial.go]], the implementation uses no concurrency and
+[serial.go](pipelines/serial.go), the implementation uses no concurrency and
simply reads and sums each file as it walks the tree.
.code pipelines/serial.go /MD5All/,/^}/
-* Parallel digestion
+## Parallel digestion
-In [[pipelines/parallel.go][parallel.go]], we split `MD5All` into a two-stage
+In [parallel.go](pipelines/parallel.go), we split `MD5All` into a two-stage
pipeline. The first stage, `sumFiles`, walks the tree, digests each file in
a new goroutine, and sends the results on a channel with value type `result`:
@@ -259,14 +260,14 @@
.code pipelines/parallel.go /func MD5All/,/^}/ HLdone
-* Bounded parallelism
+## Bounded parallelism
-The `MD5All` implementation in [[pipelines/parallel.go][parallel.go]]
+The `MD5All` implementation in [parallel.go](pipelines/parallel.go)
starts a new goroutine for each file. In a directory with many large
files, this may allocate more memory than is available on the machine.
We can limit these allocations by bounding the number of files read in
-parallel. In [[pipelines/bounded.go][bounded.go]], we do this by
+parallel. In [bounded.go](pipelines/bounded.go), we do this by
creating a fixed number of goroutines for reading files. Our pipeline
now has three stages: walk the tree, read and digest the files, and
collect the digests.
@@ -296,7 +297,7 @@
.code pipelines/bounded.go /m := make/,/^}/ HLerrc
-* Conclusion
+## Conclusion
This article has presented techniques for constructing streaming data pipelines
in Go. Dealing with failures in such pipelines is tricky, since each stage in
@@ -307,12 +308,12 @@
Further reading:
-- [[https://talks.golang.org/2012/concurrency.slide#1][Go Concurrency Patterns]]
- ([[https://www.youtube.com/watch?v=f6kdp27TYZs][video]]) presents the basics
- of Go's concurrency primitives and several ways to apply them.
-- [[https://blog.golang.org/advanced-go-concurrency-patterns][Advanced Go Concurrency Patterns]]
- ([[http://www.youtube.com/watch?v=QDDwwePbDtw][video]]) covers more complex
- uses of Go's primitives,
- especially `select`.
-- Douglas McIlroy's paper [[https://swtch.com/~rsc/thread/squint.pdf][Squinting at Power Series]]
- shows how Go-like concurrency provides elegant support for complex calculations.
+ - [Go Concurrency Patterns](https://talks.golang.org/2012/concurrency.slide#1)
+ ([video](https://www.youtube.com/watch?v=f6kdp27TYZs)) presents the basics
+ of Go's concurrency primitives and several ways to apply them.
+ - [Advanced Go Concurrency Patterns](https://blog.golang.org/advanced-go-concurrency-patterns)
+ ([video](http://www.youtube.com/watch?v=QDDwwePbDtw)) covers more complex
+ uses of Go's primitives,
+ especially `select`.
+ - Douglas McIlroy's paper [Squinting at Power Series](https://swtch.com/~rsc/thread/squint.pdf)
+ shows how Go-like concurrency provides elegant support for complex calculations.
diff --git a/content/pkg.go.dev-2020.article b/content/pkg.go.dev-2020.article
index 06e9a4b..7399cb1 100644
--- a/content/pkg.go.dev-2020.article
+++ b/content/pkg.go.dev-2020.article
@@ -1,104 +1,105 @@
-Next steps for pkg.go.dev
+# Next steps for pkg.go.dev
31 Jan 2020
+Summary: In 2019, we launched [go.dev](https://go.dev), a new hub for Go developers.
Julie Qiu
julie@golang.org
-* Introduction
+## Introduction
-In 2019, we launched [[https://go.dev][go.dev]], a new hub for Go
+In 2019, we launched [go.dev](https://go.dev), a new hub for Go
developers.
-As part of the site, we also launched [[https://pkg.go.dev][pkg.go.dev]], a
+As part of the site, we also launched [pkg.go.dev](https://pkg.go.dev), a
central source of information about Go packages and modules. Like
-[[https://godoc.org][godoc.org]], pkg.go.dev serves Go
+[godoc.org](https://godoc.org), pkg.go.dev serves Go
documentation. However, it also understands modules and has information about
past versions of a package!
Throughout this year, we will be adding features to
-[[https://pkg.go.dev][pkg.go.dev]] to help our users better understand their
+[pkg.go.dev](https://pkg.go.dev) to help our users better understand their
dependencies and help them make better decisions around what libraries to
import.
-* Redirecting godoc.org requests to pkg.go.dev
+## Redirecting godoc.org requests to pkg.go.dev
To minimize confusion about which site to use, later this year we are planning
-to redirect traffic from [[https://godoc.org][godoc.org]] to the corresponding
-page on [[https://pkg.go.dev][pkg.go.dev]]. We need your help to ensure that
+to redirect traffic from [godoc.org](https://godoc.org) to the corresponding
+page on [pkg.go.dev](https://pkg.go.dev). We need your help to ensure that
pkg.go.dev addresses all of our users' needs. We encourage everyone to begin
using pkg.go.dev today for all of their needs and provide feedback.
Your feedback will inform our transition plan, with the goal of making
-[[https://pkg.go.dev][pkg.go.dev]] our primary source of information and
+[pkg.go.dev](https://pkg.go.dev) our primary source of information and
documentation for packages and modules. We’re sure there are things that you
want to see on pkg.go.dev, and we want to hear from you
about what those features are!
You can share your feedback with us on these channels:
-- Post on the [[https://golang.org/s/discovery-feedback][Go issue tracker]].
-- Email [[mailto:go-discovery-feedback@google.com][go-discovery-feedback@google.com]].
-- Click “Share Feedback” or “Report an Issue” in the go.dev footer.
+ - Post on the [Go issue tracker](https://golang.org/s/discovery-feedback).
+ - Email [go-discovery-feedback@google.com](mailto:go-discovery-feedback@google.com).
+ - Click “Share Feedback” or “Report an Issue” in the go.dev footer.
As part of this transition, we will also be discussing plans for API access to
-[[https://pkg.go.dev][pkg.go.dev]]. We will be posting updates on
-[[https://golang.org/s/discovery-updates][Go issue 33654]].
+[pkg.go.dev](https://pkg.go.dev). We will be posting updates on
+[Go issue 33654](https://golang.org/s/discovery-updates).
-* Frequently asked questions
+## Frequently asked questions
Since our launch in November, we’ve received tons of great feedback about
-[[https://pkg.go.dev][pkg.go.dev]] from Go users. For the remainder of this post, we thought it would
+[pkg.go.dev](https://pkg.go.dev) from Go users. For the remainder of this post, we thought it would
be helpful to answer some frequently asked questions.
-** My package doesn’t show up on pkg.go.dev! How do I add it?
+### My package doesn’t show up on pkg.go.dev! How do I add it?
-We monitor the [[https://index.golang.org/index][Go Module Index]] regularly for
-new packages to add to [[https://pkg.go.dev][pkg.go.dev]]. If you don’t see a
+We monitor the [Go Module Index](https://index.golang.org/index) regularly for
+new packages to add to [pkg.go.dev](https://pkg.go.dev). If you don’t see a
package on pkg.go.dev, you can add it by fetching the module version from
-[[https://proxy.golang.org][proxy.golang.org]]. See
-[[https://go.dev/about][go.dev/about]] for instructions.
+[proxy.golang.org](https://proxy.golang.org). See
+[go.dev/about](https://go.dev/about) for instructions.
-** My package has license restrictions. What’s wrong with it?
+### My package has license restrictions. What’s wrong with it?
We understand it can be a frustrating experience to not be able to see the
-package you want in its entirety on [[https://pkg.go.dev][pkg.go.dev]]. We
+package you want in its entirety on [pkg.go.dev](https://pkg.go.dev). We
appreciate your patience as we improve our license detection algorithm.
Since our launch in November, we've made the following improvements:
-- Updated our [[https://pkg.go.dev/license-policy][license policy]] to include the list of licenses that we detect and recognize
-- Worked with the [[https://github.com/google/licensecheck][licensecheck]] team to improve detection for copyright notices
-- Established a manual review process for special cases
+ - Updated our [license policy](https://pkg.go.dev/license-policy) to include the list of licenses that we detect and recognize
+ - Worked with the [licensecheck](https://github.com/google/licensecheck) team to improve detection for copyright notices
+ - Established a manual review process for special cases
As always, our license policy is at
-[[https://pkg.go.dev/license-policy][pkg.go.dev/license-policy]]. If you are
-having issues, feel free to [[https://golang.org/s/discovery-feedback][file an issue on the Go issue tracker]], or email
-[[mailto:go-discovery-feedback@google.com][go-discovery-feedback@google.com]]
+[pkg.go.dev/license-policy](https://pkg.go.dev/license-policy). If you are
+having issues, feel free to [file an issue on the Go issue tracker](https://golang.org/s/discovery-feedback), or email
+[go-discovery-feedback@google.com](mailto:go-discovery-feedback@google.com)
so that we can work with you directly!
-** Will pkg.go.dev be open-sourced so I can run it at work for my private code?
+### Will pkg.go.dev be open-sourced so I can run it at work for my private code?
We understand that corporations with private code want to run a documentation
server that provides module support. We want to help meet that need, but we
feel we don’t yet understand it as well as we need to.
-We’ve heard from users that running the [[https://godoc.org][godoc.org]] server
+We’ve heard from users that running the [godoc.org](https://godoc.org) server
is more complex than it should be, because it is designed for serving at public
internet scale instead of just within a company. We believe the current
-[[https://pkg.go.dev][pkg.go.dev]] server would have the same problem.
+[pkg.go.dev](https://pkg.go.dev) server would have the same problem.
We think a new server is more likely to be the right answer for use with
private code, instead of exposing every company to the complexity of running
-the internet-scale [[https://pkg.go.dev][pkg.go.dev]] codebase. In addition to
+the internet-scale [pkg.go.dev](https://pkg.go.dev) codebase. In addition to
serving documentation, a new server could also serve information to
-[[https://pkg.go.dev/golang.org/x/tools/cmd/goimports?tab=doc][goimports]] and
-[[https://pkg.go.dev/golang.org/x/tools/gopls][gopls]].
+[goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports?tab=doc) and
+[gopls](https://pkg.go.dev/golang.org/x/tools/gopls).
If you want to run such a server, please fill out this
-[[https://google.qualtrics.com/jfe/form/SV_6FHmaLveae6d8Bn][*3-5*minute*survey*]]
+[**3-5 minute survey**](https://google.qualtrics.com/jfe/form/SV_6FHmaLveae6d8Bn)
to help us better understand your needs. This survey will be available until
March 1st, 2020.
-We’re excited about the future of [[https://pkg.go.dev][pkg.go.dev]] in 2020,
+We’re excited about the future of [pkg.go.dev](https://pkg.go.dev) in 2020,
and we hope you are too! We look forward to hearing your feedback and working
with the Go community on this transition.
diff --git a/content/playground.article b/content/playground.article
index 657624d..3078132 100644
--- a/content/playground.article
+++ b/content/playground.article
@@ -1,25 +1,26 @@
-Inside the Go Playground
+# Inside the Go Playground
12 Dec 2013
Tags: playground
+Summary: In September 2010 we [introduced the Go Playground](https://blog.golang.org/introducing-go-playground), a web service that compiles and executes arbitrary Go code and returns the program output.
Andrew Gerrand
-* Introduction
+## Introduction
-In September 2010 we [[https://blog.golang.org/introducing-go-playground][introduced the Go Playground]],
+In September 2010 we [introduced the Go Playground](https://blog.golang.org/introducing-go-playground),
a web service that compiles and executes arbitrary Go code and returns the
program output.
If you're a Go programmer then you have probably already used the playground
-by using the [[https://play.golang.org][Go Playground]] directly,
-taking the [[https://tour.golang.org][Go Tour]],
-or running [[https://golang.org/pkg/strings/#pkg-examples][executable examples]]
+by using the [Go Playground](https://play.golang.org) directly,
+taking the [Go Tour](https://tour.golang.org),
+or running [executable examples](https://golang.org/pkg/strings/#pkg-examples)
from the Go documentation.
You may also have used it by clicking one of the "Run" buttons in a slide
-deck on [[https://talks.golang.org/][talks.golang.org]] or a post on this
+deck on [talks.golang.org](https://talks.golang.org/) or a post on this
very blog
-(such as the [[https://blog.golang.org/strings][recent article on Strings]]).
+(such as the [recent article on Strings](https://blog.golang.org/strings)).
In this article we will take a look at how the playground is implemented
and integrated with these services.
@@ -27,22 +28,22 @@
and our description here assumes you have some familiarity with systems
programming using Go.
-* Overview
+## Overview
.image playground/overview.png
The playground service has three parts:
-- A back end that runs on Google's servers.
- It receives RPC requests, compiles the user program using the gc tool chain,
- executes the user program, and returns the program output (or compilation
- errors) as the RPC response.
-- A front end that runs on [[https://cloud.google.com/appengine/docs/go/][Google App Engine]].
- It receives HTTP requests from the client and makes corresponding RPC requests to the back end.
- It also does some caching.
-- A JavaScript client that implements the user interface and makes HTTP requests to the front end.
+ - A back end that runs on Google's servers.
+ It receives RPC requests, compiles the user program using the gc tool chain,
+ executes the user program, and returns the program output (or compilation
+ errors) as the RPC response.
+ - A front end that runs on [Google App Engine](https://cloud.google.com/appengine/docs/go/).
+ It receives HTTP requests from the client and makes corresponding RPC requests to the back end.
+ It also does some caching.
+ - A JavaScript client that implements the user interface and makes HTTP requests to the front end.
-* The back end
+## The back end
The back end program itself is trivial, so we won't discuss its implementation
here. The interesting part is how we safely execute arbitrary user code in a
@@ -50,13 +51,13 @@
network, and the file system.
To isolate user programs from Google's infrastructure, the back end runs
-them under [[https://developers.google.com/native-client/][Native Client]]
+them under [Native Client](https://developers.google.com/native-client/)
(or "NaCl"), a technology developed by Google to permit the safe execution of
x86 programs inside web browsers. The back end uses a special version of the gc
tool chain that generates NaCl executables.
(This special tool chain was merged into Go 1.3.
-To learn more, read the [[https://golang.org/s/go13nacl][design document]].)
+To learn more, read the [design document](https://golang.org/s/go13nacl).)
NaCl limits the amount of CPU and RAM a program may consume, and it prevents
programs from accessing the network or file system.
@@ -73,14 +74,14 @@
return an `EINVALID` error.
A year ago we
-[[https://groups.google.com/d/msg/golang-nuts/JBsCrDEVyVE/30MaQsiQcWoJ][implemented fake time]]
+[implemented fake time](https://groups.google.com/d/msg/golang-nuts/JBsCrDEVyVE/30MaQsiQcWoJ)
in the playground, so that programs that sleep would behave correctly.
A more recent update to the playground introduced a fake network stack and a
fake file system, making the playground's tool chain similar to a normal
Go tool chain.
These facilities are described in the following sections.
-** Faking time
+### Faking time
Playground programs are limited in the amount of CPU time and memory they can
use, but they are also restricted in how much real time they can use.
@@ -90,10 +91,10 @@
predictable and defends us against denial of service attacks.
But these restrictions become stifling when running code that uses time.
-The [[https://talks.golang.org/2012/concurrency.slide][Go Concurrency Patterns]]
+The [Go Concurrency Patterns](https://talks.golang.org/2012/concurrency.slide)
talk demonstrates concurrency with examples that use timing functions like
-[[https://golang.org/pkg/time/#Sleep][`time.Sleep`]] and
-[[https://golang.org/pkg/time/#After][`time.After`]].
+[`time.Sleep`](https://golang.org/pkg/time/#Sleep) and
+[`time.After`](https://golang.org/pkg/time/#After).
When run under early versions of the playground, these programs' sleeps would
have no effect and their behavior would be strange (and sometimes wrong).
@@ -121,8 +122,8 @@
program believes that time has passed, when in fact the sleep was nearly
instantaneous.
-These changes to the scheduler can be found in [[https://golang.org/cl/73110043][`proc.c`]]
-and [[https://golang.org/cl/73110043][`time.goc`]].
+These changes to the scheduler can be found in [`proc.c`](https://golang.org/cl/73110043)
+and [`time.goc`](https://golang.org/cl/73110043).
Fake time fixes the issue of resource exhaustion on the back end, but what
about the program output? It would be odd to see a program that sleeps run to
@@ -141,7 +142,7 @@
locally.
The playground's `runtime` package provides a special
-[[https://github.com/golang/go/blob/go1.3/src/pkg/runtime/sys_nacl_amd64p32.s#L54][`write` function]]
+[`write` function](https://github.com/golang/go/blob/go1.3/src/pkg/runtime/sys_nacl_amd64p32.s#L54)
that includes a small "playback header" before each write.
The playback header comprises a magic string, the current time, and the
length of the write data. A write with a playback header has this structure:
@@ -179,7 +180,7 @@
events using the provided delay intervals.
To the user it appears that the program is running in real time.
-** Faking the file system
+### Faking the file system
Programs built with the Go's NaCl tool chain cannot access the local machine's
file system. Instead, the `syscall` package's file-related functions
@@ -200,24 +201,24 @@
lost.
There is also a provision to load a zip file into the file system at init time
-(see [[https://github.com/golang/go/blob/go1.3/src/pkg/syscall/unzip_nacl.go][`unzip_nacl.go`]]).
+(see [`unzip_nacl.go`](https://github.com/golang/go/blob/go1.3/src/pkg/syscall/unzip_nacl.go)).
So far we have only used the unzip facility to provide the data files required
to run the standard library tests, but we intend to provide playground programs
with a set of files that can be used in documentation examples, blog posts, and
the Go Tour.
The implementation can be found in the
-[[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go][`fs_nacl.go`]] and
-[[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go][`fd_nacl.go`]] files
+[`fs_nacl.go`](https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go) and
+[`fd_nacl.go`](https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go) files
(which, by virtue of their `_nacl` suffix, are built into package `syscall` only
when `GOOS` is set to `nacl`).
The file system itself is represented by the
-[[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L26][`fsys` struct]],
+[`fsys` struct](https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L26),
of which a global instance (named `fs`) is created during init time.
The various file-related functions then operate on `fs` instead of making the
actual system call.
-For instance, here is the [[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L473][`syscall.Open`]] function:
+For instance, here is the [`syscall.Open`](https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L473) function:
func Open(path string, openmode int, perm uint32) (fd int, err error) {
fs.mu.Lock()
@@ -230,18 +231,18 @@
}
File descriptors are tracked by a global slice named
-[[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L17][`files`]].
-Each file descriptor corresponds to a [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L23][`file`]]
-and each `file` provides a value that implements the [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L30][`fileImpl`]] interface.
+[`files`](https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L17).
+Each file descriptor corresponds to a [`file`](https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L23)
+and each `file` provides a value that implements the [`fileImpl`](https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L30) interface.
There are several implementations of the interface:
-- regular files and devices (such as `/dev/random`) are represented by [[https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L58][`fsysFile`]],
-- standard input, output, and error are instances of [[https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L216][`naclFile`]],
- which uses system calls to interact with the actual files (these are a playground
- program's only way to interact with the outside world),
-- network sockets have their own implementation, discussed in the next section.
+ - regular files and devices (such as `/dev/random`) are represented by [`fsysFile`](https://github.com/golang/go/blob/master/src/syscall/fs_nacl.go#L58),
+ - standard input, output, and error are instances of [`naclFile`](https://github.com/golang/go/blob/master/src/syscall/fd_nacl.go#L216),
+ which uses system calls to interact with the actual files (these are a playground
+ program's only way to interact with the outside world),
+ - network sockets have their own implementation, discussed in the next section.
-** Faking the network
+### Faking the network
Like the file system, the playground's network stack is an in-process fake
implemented by the `syscall` package. It permits playground projects to use
@@ -259,11 +260,11 @@
file system. It must simulate read and write timeouts, different address types
and protocols, and so on.
-The implementation can be found in [[https://github.com/golang/go/blob/master/src/syscall/net_nacl.go][`net_nacl.go`]].
-A good place to start reading is [[https://github.com/golang/go/blob/master/src/syscall/net_nacl.go#L461][`netFile`]],
+The implementation can be found in [`net_nacl.go`](https://github.com/golang/go/blob/master/src/syscall/net_nacl.go).
+A good place to start reading is [`netFile`](https://github.com/golang/go/blob/master/src/syscall/net_nacl.go#L461),
the network socket implementation of the `fileImpl` interface.
-* The front end
+## The front end
The playground front end is another simple program (shorter than 100 lines).
It receives HTTP requests from the client, makes RPC requests to the back end,
@@ -275,52 +276,52 @@
(for most clients this should be `"2"`).
When the front end receives a compilation request it first checks
-[[https://developers.google.com/appengine/docs/memcache/][memcache]]
+[memcache](https://developers.google.com/appengine/docs/memcache/)
to see if it has cached the results of a previous compilation of that source.
If found, it returns the cached response.
The cache prevents popular programs such as those on the
-[[https://golang.org/][Go home page]] from overloading the back ends.
+[Go home page](https://golang.org/) from overloading the back ends.
If there is no cached response, the front end makes an RPC request to the back
end, stores the response in memcache, parses the playback events, and returns
a JSON object to the client as the HTTP response (as described above).
-* The client
+## The client
The various sites that use the playground each share some common JavaScript
code for setting up the user interface (the code and output boxes, the run
button, and so on) and communicating with the playground front end.
This implementation is in the file
-[[https://github.com/golang/tools/blob/master/godoc/static/playground.js][`playground.js`]]
+[`playground.js`](https://github.com/golang/tools/blob/master/godoc/static/playground.js)
in the `go.tools` repository, which can be imported from the
-[[https://godoc.org/golang.org/x/tools/godoc/static][`golang.org/x/tools/godoc/static`]] package.
+[`golang.org/x/tools/godoc/static`](https://godoc.org/golang.org/x/tools/godoc/static) package.
Some of it is clean and some is a bit crufty, as it is the result of
consolidating several divergent implementations of the client code.
-The [[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L227][`playground`]]
+The [`playground`](https://github.com/golang/tools/blob/master/godoc/static/playground.js#L227)
function takes some HTML elements and turns them into an interactive
playground widget. You should use this function if you want to put the
playground on your own site (see 'Other clients' below).
-The [[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L6][`Transport`]]
+The [`Transport`](https://github.com/golang/tools/blob/master/godoc/static/playground.js#L6)
interface (not formally defined, this being JavaScript)
abstracts the user interface from the means of talking to the web front end.
-[[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L43][`HTTPTransport`]]
+[`HTTPTransport`](https://github.com/golang/tools/blob/master/godoc/static/playground.js#L43)
is an implementation of `Transport` that speaks the HTTP-based protocol
described earlier.
-[[https://github.com/golang/tools/blob/master/godoc/static/playground.js#L115][`SocketTransport`]]
+[`SocketTransport`](https://github.com/golang/tools/blob/master/godoc/static/playground.js#L115)
is another implementation that speaks WebSocket (see 'Playing offline' below).
-To comply with the [[https://en.wikipedia.org/wiki/Same-origin_policy][same-origin policy]],
+To comply with the [same-origin policy](https://en.wikipedia.org/wiki/Same-origin_policy),
the various web servers (godoc, for instance) proxy requests to
`/compile` through to the playground service at `https://golang.org/compile`.
-The common [[https://godoc.org/golang.org/x/tools/playground][`golang.org/x/tools/playground`]]
+The common [`golang.org/x/tools/playground`](https://godoc.org/golang.org/x/tools/playground)
package does this proxying.
-* Playing offline
+## Playing offline
-Both the [[https://tour.golang.org][Go Tour]] and the
-[[https://godoc.org/golang.org/x/tools/present][Present Tool]] can be
+Both the [Go Tour](https://tour.golang.org) and the
+[Present Tool](https://godoc.org/golang.org/x/tools/present) can be
run offline. This is great for people with limited internet connectivity
or presenters at conferences who cannot (and _should_ not) rely on a working
internet connection.
@@ -331,19 +332,19 @@
client.
The WebSocket back end implementation can be found in the
-[[https://godoc.org/golang.org/x/tools/playground/socket][`golang.org/x/tools/playground/socket`]] package.
-The [[https://talks.golang.org/2012/insidepresent.slide#1][Inside Present]] talk discusses this code in detail.
+[`golang.org/x/tools/playground/socket`](https://godoc.org/golang.org/x/tools/playground/socket) package.
+The [Inside Present](https://talks.golang.org/2012/insidepresent.slide#1) talk discusses this code in detail.
-* Other clients
+## Other clients
The playground service is used by more than just the official Go project
-([[https://gobyexample.com/][Go by Example]] is one other instance)
+([Go by Example](https://gobyexample.com/) is one other instance)
and we are happy for you to use it on your own site. All we ask is that
-you [[mailto:golang-dev@googlegroups.com][contact us first]],
+you [contact us first](mailto:golang-dev@googlegroups.com),
use a unique user agent in your requests (so we can identify you), and that
your service is of benefit to the Go community.
-* Conclusion
+## Conclusion
From godoc to the tour to this very blog, the playground has become an
essential part of our Go documentation story. With the recent additions
@@ -354,6 +355,6 @@
With Native Client support scheduled for Go 1.3,
we look forward to seeing what the community can do with it.
-_This_article_is_part_12_of_the_
-[[https://blog.gopheracademy.com/go-advent-2013][Go Advent Calendar]],
-_a_series_of_daily_blog_posts_throughout_December_._
+_This article is part 12 of the_
+[Go Advent Calendar](https://blog.gopheracademy.com/go-advent-2013),
+_a series of daily blog posts throughout December ._
diff --git a/content/preview-of-go-version-1.article b/content/preview-of-go-version-1.article
index 48a9224..e915225 100644
--- a/content/preview-of-go-version-1.article
+++ b/content/preview-of-go-version-1.article
@@ -1,10 +1,11 @@
-A preview of Go version 1
+# A preview of Go version 1
5 Oct 2011
Tags: go1, release
+Summary: We want to be able to provide a stable base for people using Go. People should be able to write Go programs and expect that they will continue to compile and run without change, on a timescale of years. Similarly, people should be able to write books about Go, be able to say which version of Go the book is describing, and have that version number still be meaningful much later. None of these properties is true for Go today.
Russ Cox
-* Introduction
+##
We want to be able to provide a stable base for people using Go.
People should be able to write Go programs and expect that they will continue
@@ -42,6 +43,6 @@
rather than delay them until after it is released and thereby introduce
divergence that contradicts our goals.
-Today, we are publishing our preliminary [[https://docs.google.com/document/pub?id=1ny8uI-_BHrDCZv_zNBSthNKAMX_fR_0dc6epA6lztRE][plan for Go 1]]
+Today, we are publishing our preliminary [plan for Go 1](https://docs.google.com/document/pub?id=1ny8uI-_BHrDCZv_zNBSthNKAMX_fR_0dc6epA6lztRE)
for feedback from the Go community.
-If you have feedback, please reply to the [[http://groups.google.com/group/golang-nuts/browse_thread/thread/badc4f323431a4f6][thread on the golang-nuts mailing list]].
+If you have feedback, please reply to the [thread on the golang-nuts mailing list](http://groups.google.com/group/golang-nuts/browse_thread/thread/badc4f323431a4f6).
diff --git a/content/profiling-go-programs.article b/content/profiling-go-programs.article
index 9959076..2876475 100644
--- a/content/profiling-go-programs.article
+++ b/content/profiling-go-programs.article
@@ -1,13 +1,14 @@
-Profiling Go Programs
+# Profiling Go Programs
24 Jun 2011
Tags: benchmark, pprof, profiling, technical
+Summary: At Scala Days 2011, Robert Hundt presented a paper titled [Loop Recognition in C++/Java/Go/Scala.](http://research.google.com/pubs/pub37122.html) The paper implemented a specific loop finding algorithm, such as you might use in a flow analysis pass of a compiler, in C++, Go, Java, Scala, and then used those programs to draw conclusions about typical performance concerns in these languages. The Go program presented in that paper runs quite slowly, making it an excellent opportunity to demonstrate how to use Go's profiling tools to take a slow program and make it faster.
Russ Cox, July 2011; updated by Shenghou Ma, May 2013
-* Introduction
+##
At Scala Days 2011, Robert Hundt presented a paper titled
-[[http://research.google.com/pubs/pub37122.html][Loop Recognition in C++/Java/Go/Scala.]]
+[Loop Recognition in C++/Java/Go/Scala.](http://research.google.com/pubs/pub37122.html)
The paper implemented a specific loop finding algorithm, such as you might use
in a flow analysis pass of a compiler, in C++, Go, Java, Scala, and then used
those programs to draw conclusions about typical performance concerns in these
@@ -16,7 +17,7 @@
an excellent opportunity to demonstrate how to use Go's profiling tools to take
a slow program and make it faster.
-_By_using_Go's_profiling_tools_to_identify_and_correct_specific_bottlenecks,_we_can_make_the_Go_loop_finding_program_run_an_order_of_magnitude_faster_and_use_6x_less_memory._
+_By using Go's profiling tools to identify and correct specific bottlenecks, we can make the Go loop finding program run an order of magnitude faster and use 6x less memory._
(Update: Due to recent optimizations of `libstdc++` in `gcc`, the memory reduction is now 3.7x.)
Hundt's paper does not specify which versions of the C++, Go, Java, and Scala
@@ -51,7 +52,7 @@
done
#
-We've taken [[https://github.com/hundt98847/multi-language-bench][Hundt's benchmark programs]]
+We've taken [Hundt's benchmark programs](https://github.com/hundt98847/multi-language-bench)
in C++ and Go, combined each into a single source file, and removed all but one
line of output.
We'll time the program using Linux's `time` utility with a format that shows user time,
@@ -84,7 +85,7 @@
results from the paper.)
To start tuning the Go program, we have to enable profiling.
-If the code used the [[https://golang.org/pkg/testing/][Go testing package]]'s
+If the code used the [Go testing package](https://golang.org/pkg/testing/)'s
benchmarking support, we could use gotest's standard `-cpuprofile` and `-memprofile`
flags.
In a standalone program like this one, we have to import `runtime/pprof` and add a few
@@ -105,12 +106,12 @@
...
The new code defines a flag named `cpuprofile`, calls the
-[[https://golang.org/pkg/flag/][Go flag library]] to parse the command line flags,
+[Go flag library](https://golang.org/pkg/flag/) to parse the command line flags,
and then, if the `cpuprofile` flag has been set on the command line,
-[[https://golang.org/pkg/runtime/pprof/#StartCPUProfile][starts CPU profiling]]
+[starts CPU profiling](https://golang.org/pkg/runtime/pprof/#StartCPUProfile)
redirected to that file.
The profiler requires a final call to
-[[https://golang.org/pkg/runtime/pprof/#StopCPUProfile][`StopCPUProfile`]] to
+[`StopCPUProfile`](https://golang.org/pkg/runtime/pprof/#StopCPUProfile) to
flush any pending writes to the file before the program exits; we use `defer`
to make sure this happens as `main` returns.
@@ -125,7 +126,7 @@
(pprof)
The `go tool pprof` program is a slight variant of
-[[https://github.com/gperftools/gperftools][Google's `pprof` C++ profiler]].
+[Google's `pprof` C++ profiler](https://github.com/gperftools/gperftools).
The most important command is `topN`, which shows the top `N` samples in the profile:
(pprof) top10
@@ -180,12 +181,12 @@
The `web` command writes a graph of the profile data in SVG format and opens it in a web
browser.
(There is also a `gv` command that writes PostScript and opens it in Ghostview.
-For either command, you need [[http://www.graphviz.org/][graphviz]] installed.)
+For either command, you need [graphviz](http://www.graphviz.org/) installed.)
(pprof) web
A small fragment of
-[[https://rawgit.com/rsc/benchgraffiti/master/havlak/havlak1.svg][the full graph]] looks like:
+[the full graph](https://rawgit.com/rsc/benchgraffiti/master/havlak/havlak1.svg) looks like:
.image profiling-go-programs_havlak1a-75.png
@@ -240,7 +241,7 @@
listing; when there are enough samples this can help you see which instructions are
expensive.
The `weblist` command mixes the two modes: it shows
-[[https://rawgit.com/rsc/benchgraffiti/master/havlak/havlak1.html][a source listing in which clicking a line shows the disassembly]].
+[a source listing in which clicking a line shows the disassembly](https://rawgit.com/rsc/benchgraffiti/master/havlak/havlak1.html).
Since we already know that the time is going into map lookups implemented by the
hash runtime functions, we care most about the second column.
@@ -265,7 +266,7 @@
16.55u 0.11s 16.69r 1321008kB ./havlak2
$
-(See the [[https://github.com/rsc/benchgraffiti/commit/58ac27bcac3ffb553c29d0b3fb64745c91c95948][diff between `havlak1` and `havlak2`]])
+(See the [diff between `havlak1` and `havlak2`](https://github.com/rsc/benchgraffiti/commit/58ac27bcac3ffb553c29d0b3fb64745c91c95948))
We can run the profiler again to confirm that `main.DFS` is no longer a significant
part of the run time:
@@ -317,7 +318,7 @@
./havlak3 -memprofile=havlak3.mprof
$
-(See the [[https://github.com/rsc/benchgraffiti/commit/b78dac106bea1eb3be6bb3ca5dba57c130268232][diff from havlak2]])
+(See the [diff from havlak2](https://github.com/rsc/benchgraffiti/commit/b78dac106bea1eb3be6bb3ca5dba57c130268232))
We use `go tool pprof` exactly the same way. Now the samples we are examining are
memory allocations, not clock ticks.
@@ -426,7 +427,7 @@
11.84u 0.08s 11.94r 810416kB ./havlak4
$
-(See the [[https://github.com/rsc/benchgraffiti/commit/245d899f7b1a33b0c8148a4cd147cb3de5228c8a][diff from havlak3]])
+(See the [diff from havlak3](https://github.com/rsc/benchgraffiti/commit/245d899f7b1a33b0c8148a4cd147cb3de5228c8a))
We're now at 2.11x faster than when we started. Let's look at a CPU profile again.
@@ -525,33 +526,33 @@
and then have `FindLoops` consult it as a replacement for allocation:
- if cache.size < size {
- cache.size = size
- cache.nonBackPreds = make([][]int, size)
- cache.backPreds = make([][]int, size)
- cache.number = make([]int, size)
- cache.header = make([]int, size)
- cache.types = make([]int, size)
- cache.last = make([]int, size)
- cache.nodes = make([]*UnionFindNode, size)
- for i := range cache.nodes {
- cache.nodes[i] = new(UnionFindNode)
- }
+ if cache.size < size {
+ cache.size = size
+ cache.nonBackPreds = make([][]int, size)
+ cache.backPreds = make([][]int, size)
+ cache.number = make([]int, size)
+ cache.header = make([]int, size)
+ cache.types = make([]int, size)
+ cache.last = make([]int, size)
+ cache.nodes = make([]*UnionFindNode, size)
+ for i := range cache.nodes {
+ cache.nodes[i] = new(UnionFindNode)
}
+ }
- nonBackPreds := cache.nonBackPreds[:size]
- for i := range nonBackPreds {
- nonBackPreds[i] = nonBackPreds[i][:0]
- }
- backPreds := cache.backPreds[:size]
- for i := range nonBackPreds {
- backPreds[i] = backPreds[i][:0]
- }
- number := cache.number[:size]
- header := cache.header[:size]
- types := cache.types[:size]
- last := cache.last[:size]
- nodes := cache.nodes[:size]
+ nonBackPreds := cache.nonBackPreds[:size]
+ for i := range nonBackPreds {
+ nonBackPreds[i] = nonBackPreds[i][:0]
+ }
+ backPreds := cache.backPreds[:size]
+ for i := range nonBackPreds {
+ backPreds[i] = backPreds[i][:0]
+ }
+ number := cache.number[:size]
+ header := cache.header[:size]
+ types := cache.types[:size]
+ last := cache.last[:size]
+ nodes := cache.nodes[:size]
Such a global variable is bad engineering practice, of course: it means that
concurrent calls to `FindLoops` are now unsafe.
@@ -568,7 +569,7 @@
8.03u 0.06s 8.11r 770352kB ./havlak5
$
-(See the [[https://github.com/rsc/benchgraffiti/commit/2d41d6d16286b8146a3f697dd4074deac60d12a4][diff from havlak4]])
+(See the [diff from havlak4](https://github.com/rsc/benchgraffiti/commit/2d41d6d16286b8146a3f697dd4074deac60d12a4))
There's more we can do to clean up the program and make it faster, but none of
it requires profiling techniques that we haven't already shown.
@@ -577,7 +578,7 @@
during that pass.
Similarly, the loop graph storage can be reused on each iteration instead of reallocated.
In addition to these performance changes, the
-[[https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.go][final version]]
+[final version](https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.go)
is written using idiomatic Go style, using data structures and methods.
The stylistic changes have only a minor effect on the run time: the algorithm and
constraints are unchanged.
@@ -605,7 +606,7 @@
program, which used inefficient data structures like `set`s where `vector`s would
be more appropriate.
As a sanity check, we translated the final Go program into
-[[https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.cc][equivalent C++ code]].
+[equivalent C++ code](https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.cc).
Its execution time is similar to the Go program's:
$ make havlak6cc
@@ -623,8 +624,8 @@
461 1441 9467 havlak6.go
$
-(See [[https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.cc][havlak6.cc]]
-and [[https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.go][havlak6.go]])
+(See [havlak6.cc](https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.cc)
+and [havlak6.go](https://github.com/rsc/benchgraffiti/blob/master/havlak/havlak6.go))
Benchmarks are only as good as the programs they measure.
We used `go tool pprof` to study an inefficient Go program and then to improve its
@@ -634,11 +635,11 @@
by inner loops.
The program sources, Linux x86-64 binaries, and profiles used to write this post
-are available in the [[https://github.com/rsc/benchgraffiti/][benchgraffiti project on GitHub]].
+are available in the [benchgraffiti project on GitHub](https://github.com/rsc/benchgraffiti/).
-As mentioned above, [[https://golang.org/cmd/go/#Test_packages][`go test`]] includes
+As mentioned above, [`go test`](https://golang.org/cmd/go/#Test_packages) includes
these profiling flags already: define a
-[[https://golang.org/pkg/testing/][benchmark function]] and you're all set.
+[benchmark function](https://golang.org/pkg/testing/) and you're all set.
There is also a standard HTTP interface to profiling data. In an HTTP server, adding
import _ "net/http/pprof"
diff --git a/content/publishing-go-modules.article b/content/publishing-go-modules.article
index 6036b70..eb92850 100644
--- a/content/publishing-go-modules.article
+++ b/content/publishing-go-modules.article
@@ -1,33 +1,34 @@
-Publishing Go Modules
+# Publishing Go Modules
26 Sep 2019
Tags: tools, versioning
+Summary: This post is part 3 in a series.
Tyler Bui-Palsulich
-* Introduction
+## Introduction
This post is part 3 in a series.
-- Part 1 — [[/using-go-modules][Using Go Modules]]
-- Part 2 — [[/migrating-to-go-modules][Migrating To Go Modules]]
-- *Part*3*—*Publishing*Go*Modules* (this post)
-- Part 4 — [[/v2-go-modules][Go Modules: v2 and Beyond]]
+ - Part 1 — [Using Go Modules](/using-go-modules)
+ - Part 2 — [Migrating To Go Modules](/migrating-to-go-modules)
+ - **Part 3 — Publishing Go Modules** (this post)
+ - Part 4 — [Go Modules: v2 and Beyond](/v2-go-modules)
This post discusses how to write and publish modules so other modules can depend
on them.
Please note: this post covers development up to and including `v1`. If you are
-interested in `v2`, please see [[/v2-go-modules][Go Modules: v2 and Beyond]].
+interested in `v2`, please see [Go Modules: v2 and Beyond](/v2-go-modules).
-This post uses [[https://git-scm.com/][Git]] in examples.
-[[https://www.mercurial-scm.org/][Mercurial]],
-[[http://wiki.bazaar.canonical.com/][Bazaar]], and others are supported as well.
+This post uses [Git](https://git-scm.com/) in examples.
+[Mercurial](https://www.mercurial-scm.org/),
+[Bazaar](http://wiki.bazaar.canonical.com/), and others are supported as well.
-* Project setup
+## Project setup
For this post, you'll need an existing project to use as an example. So, start
with the files from the end of the
-[[https://blog.golang.org/using-go-modules][Using Go Modules]] article:
+[Using Go Modules](https://blog.golang.org/using-go-modules) article:
$ cat go.mod
module example.com/hello
@@ -89,28 +90,28 @@
$ git commit -m "hello: initial commit"
$
-* Semantic versions and modules
+## Semantic versions and modules
Every required module in a `go.mod` has a
-[[https://semver.org][semantic version]], the minimum version of that dependency
+[semantic version](https://semver.org), the minimum version of that dependency
to use to build the module.
A semantic version has the form `vMAJOR.MINOR.PATCH`.
-- Increment the `MAJOR` version when you make a [[https://golang.org/doc/go1compat][backwards incompatible]]
- change to the public API of your module.
- This should only be done when absolutely necessary.
-- Increment the `MINOR` version when you make a backwards compatible change to the API,
- like changing dependencies or adding a new function,
- method, struct field, or type.
-- Increment the `PATCH` version after making minor changes that don't affect
- your module's public API or dependencies, like fixing a bug.
+ - Increment the `MAJOR` version when you make a [backwards incompatible](https://golang.org/doc/go1compat)
+ change to the public API of your module.
+ This should only be done when absolutely necessary.
+ - Increment the `MINOR` version when you make a backwards compatible change to the API,
+ like changing dependencies or adding a new function,
+ method, struct field, or type.
+ - Increment the `PATCH` version after making minor changes that don't affect
+ your module's public API or dependencies, like fixing a bug.
You can specify pre-release versions by appending a hyphen and dot separated
identifiers (for example, `v1.0.1-alpha` or `v2.2.2-beta.2`). Normal releases
are preferred by the `go` command over pre-release versions, so users must ask
for pre-release versions explicitly (for example,
-`go`get`example.com/hello@v1.0.1-alpha`) if your module has any normal releases.
+`go get example.com/hello@v1.0.1-alpha`) if your module has any normal releases.
`v0` major versions and pre-release versions do not guarantee backwards
compatibility. They let you refine your API before making stability commitments
@@ -119,7 +120,7 @@
The version referenced in a `go.mod` may be an explicit release tagged in the
repository (for example, `v1.5.2`), or it may be a
-[[https://golang.org/cmd/go/#hdr-Pseudo_versions][pseudo-version]] based on a
+[pseudo-version](https://golang.org/cmd/go/#hdr-Pseudo_versions) based on a
specific commit (for example, `v0.0.0-20170915032832-14c0d48ead0c`).
Pseudo-versions are a special type of pre-release version. Pseudo-versions are
useful when a user needs to depend on a project that has not published any
@@ -130,7 +131,7 @@
Once you start tagging your repo with versions, it's important to keep tagging
new releases as you develop your module. When users request a new version of
-your module (with `go`get`-u` or `go`get`example.com/hello`), the `go` command
+your module (with `go get -u` or `go get example.com/hello`), the `go` command
will choose the greatest semantic release version available, even if that
version is several years old and many changes behind the primary branch.
Continuing to tag new releases will make your ongoing improvements available to
@@ -140,11 +141,11 @@
with a version, release a new version. If people depend on a version that you
have deleted, their builds may fail. Similarly, once you release a version, do
not change or overwrite it. The
-[[https://blog.golang.org/module-mirror-launch][module mirror and checksum database]]
+[module mirror and checksum database](https://blog.golang.org/module-mirror-launch)
store modules, their versions, and signed cryptographic hashes to ensure that
the build of a given version remains reproducible over time.
-* v0: the initial, unstable version
+## v0: the initial, unstable version
Let's tag the module with a `v0` semantic version. A `v0` version does not make
any stability guarantees, so nearly all projects should start with `v0` as they
@@ -152,11 +153,11 @@
Tagging a new version has a few steps:
-1. Run `go`mod`tidy`, which removes any dependencies the module might have accumulated that are no longer necessary.
+1. Run `go mod tidy`, which removes any dependencies the module might have accumulated that are no longer necessary.
-2. Run `go`test`./...` a final time to make sure everything is working.
+2. Run `go test ./...` a final time to make sure everything is working.
-3. Tag the project with a new version using [[https://git-scm.com/docs/git-tag][`git`tag`]].
+3. Tag the project with a new version using [`git tag`](https://git-scm.com/docs/git-tag).
4. Push the new tag to the origin repository.
@@ -170,7 +171,7 @@
$
Now other projects can depend on `v0.1.0` of `example.com/hello`. For your own
-module, you can run `go`list`-m`example.com/hello@v0.1.0` to confirm the latest
+module, you can run `go list -m example.com/hello@v0.1.0` to confirm the latest
version is available (this example module does not exist, so no versions are
available). If you don't see the latest version immediately and you're using the
Go module proxy (the default since Go 1.13), try again in a few minutes to give
@@ -184,7 +185,7 @@
If you fix a bug in an existing version, increment the `PATCH` version. For
example, the next release after `v0.1.0` would be `v0.1.1`.
-* v1: the first stable version
+## v1: the first stable version
Once you are absolutely sure your module's API is stable, you can release
`v1.0.0`. A `v1` major version communicates to users that no incompatible
@@ -202,26 +203,26 @@
The standard library's `strings` package is a prime example of maintaining
backwards compatibility at the cost of API consistency.
-- [[https://godoc.org/strings#Split][`Split`]] slices a string into all
- substrings separated by a separator and returns a slice of the substrings
- between those separators.
-- [[https://godoc.org/strings#SplitN][`SplitN`]] can be used to control the number of substrings to return.
+ - [`Split`](https://godoc.org/strings#Split) slices a string into all
+ substrings separated by a separator and returns a slice of the substrings
+ between those separators.
+ - [`SplitN`](https://godoc.org/strings#SplitN) can be used to control the number of substrings to return.
-However, [[https://godoc.org/strings#Replace][`Replace`]] took a count of how
+However, [`Replace`](https://godoc.org/strings#Replace) took a count of how
many instances of the string to replace from the beginning (unlike `Split`).
Given `Split` and `SplitN`, you would expect functions like `Replace` and
`ReplaceN`. But, we couldn't change the existing `Replace` without breaking
callers, which we promised not to do. So, in Go 1.12, we added a new function,
-[[https://godoc.org/strings#ReplaceAll][`ReplaceAll`]]. The resulting API is a
+[`ReplaceAll`](https://godoc.org/strings#ReplaceAll). The resulting API is a
little odd, since `Split` and `Replace` behave differently, but that
inconsistency is better than a breaking change.
Let's say you're happy with the API of `example.com/hello` and you want to
release `v1` as the first stable version.
-Tagging `v1` uses the same process as tagging a `v0` version: run `go`mod`tidy`
-and `go`test`./...`, tag the version, and push the tag to the origin repository:
+Tagging `v1` uses the same process as tagging a `v0` version: run `go mod tidy`
+and `go test ./...`, tag the version, and push the tag to the origin repository:
$ go mod tidy
$ go test ./...
@@ -236,14 +237,14 @@
communicates to everyone that our API is stable and they should feel comfortable
using it.
-* Conclusion
+## Conclusion
This post walked through the process of tagging a module with semantic versions
and when to release `v1`. A future post will cover how to maintain and publish
modules at `v2` and beyond.
To provide feedback and help shape the future of dependency management in Go,
-please send us [[https://golang.org/issue/new][bug reports]] or
-[[https://golang.org/wiki/ExperienceReports][experience reports]].
+please send us [bug reports](https://golang.org/issue/new) or
+[experience reports](https://golang.org/wiki/ExperienceReports).
Thanks for all your feedback and help improving Go modules.
diff --git a/content/qihoo.article b/content/qihoo.article
index 7f90ed8..7ac2ebc 100644
--- a/content/qihoo.article
+++ b/content/qihoo.article
@@ -1,13 +1,14 @@
-Qihoo 360 and Go
+# Qihoo 360 and Go
6 Jul 2015
+Summary: _This guest blog post was written by Yang Zhou, Software Engineer at Qihoo 360._
Yang Zhou
-* Introduction
+##
-_This_guest_blog_post_was_written_by_Yang_Zhou,_Software_Engineer_at_Qihoo_360._
+_This guest blog post was written by Yang Zhou, Software Engineer at Qihoo 360._
-[[http://www.360safe.com/][Qihoo 360]] is a major provider of Internet and
+[Qihoo 360](http://www.360safe.com/) is a major provider of Internet and
mobile security products and services in China, and operates a major
Android-based mobile distribution platform. At the end of June 2014, Qihoo had
about 500 million monthly active PC Internet users and over 640 million mobile
@@ -46,28 +47,28 @@
Here are a few tweaks we made and key take-aways:
-- Replace short connections with persistent ones (using a connection pool),
- to reduce creation of buffers and objects during communication.
-- Use Objects and Memory pools appropriately, to reduce the load on the GC.
+ - Replace short connections with persistent ones (using a connection pool),
+ to reduce creation of buffers and objects during communication.
+ - Use Objects and Memory pools appropriately, to reduce the load on the GC.
.image qihoo/image00.png
-- Use a Task Pool, a mechanism with a group of long-lived goroutines consuming
- global task or message queues sent by connection goroutines,
- to replace short-lived goroutines.
+ - Use a Task Pool, a mechanism with a group of long-lived goroutines consuming
+ global task or message queues sent by connection goroutines,
+ to replace short-lived goroutines.
-- Monitor and control goroutine numbers in the program.
- The lack of control can cause unbearable burden on the GC,
- imposed by surges in goroutines due to uninhibited acceptance of external requests,
- as RPC invocations sent to inner servers may block goroutines recently created.
+ - Monitor and control goroutine numbers in the program.
+ The lack of control can cause unbearable burden on the GC,
+ imposed by surges in goroutines due to uninhibited acceptance of external requests,
+ as RPC invocations sent to inner servers may block goroutines recently created.
-- Remember to add [[https://golang.org/pkg/net/#Conn][read and write deadlines]]
- to connections when under a mobile network;
- otherwise, it may lead to goroutine blockage.
- Apply it properly and with caution when under a LAN network,
- otherwise your RPC communication efficiency will be hurt.
+ - Remember to add [read and write deadlines](https://golang.org/pkg/net/#Conn)
+ to connections when under a mobile network;
+ otherwise, it may lead to goroutine blockage.
+ Apply it properly and with caution when under a LAN network,
+ otherwise your RPC communication efficiency will be hurt.
-- Use Pipeline (under Full Duplex feature of TCP) to enhance the communication efficiency of RPC framework.
+ - Use Pipeline (under Full Duplex feature of TCP) to enhance the communication efficiency of RPC framework.
As a result, we successfully launched three iterations of our architecture,
and two iterations of our RPC framework even with limited human resources.
@@ -103,7 +104,7 @@
obsolete one day, as Go continues to evolve.
This is why I want to conclude my sharing by extending my sincere appreciation
-to the opportunity to attend [[http://gopherchina.org/][Gopher China]].
+to the opportunity to attend [Gopher China](http://gopherchina.org/).
It was a gala for us to learn, to share and for offering a window showcasing
Go’s popularity and prosperity in China. Many other teams within Qihoo have
already either got to know Go, or tried to use Go.
diff --git a/content/race-detector.article b/content/race-detector.article
index 1a284f2..3ebc9fb 100644
--- a/content/race-detector.article
+++ b/content/race-detector.article
@@ -1,14 +1,15 @@
-Introducing the Go Race Detector
+# Introducing the Go Race Detector
26 Jun 2013
Tags: concurrency, technical
+Summary: [Race conditions](http://en.wikipedia.org/wiki/Race_condition) are among the most insidious and elusive programming errors. They typically cause erratic and mysterious failures, often long after the code has been deployed to production. While Go's concurrency mechanisms make it easy to write clean concurrent code, they don't prevent race conditions. Care, diligence, and testing are required. And tools can help.
Dmitry Vyukov
Andrew Gerrand
-* Introduction
+## Introduction
-[[http://en.wikipedia.org/wiki/Race_condition][Race conditions]] are among the
+[Race conditions](http://en.wikipedia.org/wiki/Race_condition) are among the
most insidious and elusive programming errors. They typically cause erratic and
mysterious failures, often long after the code has been deployed to production.
While Go's concurrency mechanisms make it easy to write clean concurrent code,
@@ -16,28 +17,28 @@
And tools can help.
We're happy to announce that Go 1.1 includes a
-[[https://golang.org/doc/articles/race_detector.html][race detector]],
+[race detector](https://golang.org/doc/articles/race_detector.html),
a new tool for finding race conditions in Go code.
It is currently available for Linux, OS X, and Windows systems
with 64-bit x86 processors.
The race detector is based on the C/C++
-[[https://github.com/google/sanitizers][ThreadSanitizer runtime library]],
+[ThreadSanitizer runtime library](https://github.com/google/sanitizers),
which has been used to detect many errors in Google's internal code base and in
-[[http://www.chromium.org/][Chromium]].
+[Chromium](http://www.chromium.org/).
The technology was integrated with Go in September 2012; since then it has detected
-[[https://github.com/golang/go/issues?utf8=%E2%9C%93&q=ThreadSanitizer][42 races]]
+[42 races](https://github.com/golang/go/issues?utf8=%E2%9C%93&q=ThreadSanitizer)
in the standard library. It is now part of our continuous build process,
where it continues to catch race conditions as they arise.
-* How it works
+## How it works
The race detector is integrated with the go tool chain. When the
`-race` command-line flag is set, the compiler instruments all memory accesses
with code that records when and how the memory was accessed, while the runtime
library watches for unsynchronized accesses to shared variables.
When such "racy" behavior is detected, a warning is printed.
-(See [[https://github.com/google/sanitizers/wiki/ThreadSanitizerAlgorithm][this article]]
+(See [this article](https://github.com/google/sanitizers/wiki/ThreadSanitizerAlgorithm)
for the details of the algorithm.)
Because of its design, the race detector can detect race conditions only when
@@ -51,7 +52,7 @@
Another approach using production workloads is to deploy a single race-enabled
instance within a pool of running servers.
-* Using the race detector
+## Using the race detector
The race detector is fully integrated with the Go tool chain.
To build your code with the race detector enabled, just add the
@@ -67,18 +68,18 @@
$ go get -race golang.org/x/blog/support/racy
$ racy
-* Examples
+## Examples
Here are two examples of real issues caught by the race detector.
-** Example 1: Timer.Reset
+### Example 1: Timer.Reset
The first example is a simplified version of an actual bug found by the race
detector. It uses a timer to print a message after a random duration between 0
and 1 second. It does so repeatedly for five seconds.
-It uses [[https://golang.org/pkg/time/#AfterFunc][`time.AfterFunc`]] to create a
-[[https://golang.org/pkg/time/#Timer][`Timer`]] for the first message and then
-uses the [[https://golang.org/pkg/time/#Timer.Reset][`Reset`]] method to
+It uses [`time.AfterFunc`](https://golang.org/pkg/time/#AfterFunc) to create a
+[`Timer`](https://golang.org/pkg/time/#Timer) for the first message and then
+uses the [`Reset`](https://golang.org/pkg/time/#Timer.Reset) method to
schedule the next message, re-using the `Timer` each time.
.play -numbers race-detector/timer.go /func main/,$
@@ -132,19 +133,19 @@
a thread-safe way.
A simpler but less efficient approach is to
-[[http://play.golang.org/p/kuWTrY0pS4][avoid reusing timers]].
+[avoid reusing timers](http://play.golang.org/p/kuWTrY0pS4).
-** Example 2: ioutil.Discard
+### Example 2: ioutil.Discard
The second example is more subtle.
The `ioutil` package's
-[[https://golang.org/pkg/io/ioutil/#Discard][`Discard`]] object implements
-[[https://golang.org/pkg/io/#Writer][`io.Writer`]],
+[`Discard`](https://golang.org/pkg/io/ioutil/#Discard) object implements
+[`io.Writer`](https://golang.org/pkg/io/#Writer),
but discards all the data written to it.
Think of it like `/dev/null`: a place to send data that you need to read but
don't want to store.
-It is commonly used with [[https://golang.org/pkg/io/#Copy][`io.Copy`]]
+It is commonly used with [`io.Copy`](https://golang.org/pkg/io/#Copy)
to drain a reader, like this:
io.Copy(ioutil.Discard, reader)
@@ -165,22 +166,22 @@
writer.ReadFrom(reader)
We
-[[https://golang.org/cl/4817041][added a ReadFrom method]]
+[added a ReadFrom method](https://golang.org/cl/4817041)
to Discard's underlying type, which has an internal buffer that is shared
between all its users.
We knew this was theoretically a race condition, but since all writes to the
buffer should be thrown away we didn't think it was important.
When the race detector was implemented it immediately
-[[https://golang.org/issue/3970][flagged this code]] as racy.
+[flagged this code](https://golang.org/issue/3970) as racy.
Again, we considered that the code might be problematic, but decided that the
race condition wasn't "real".
To avoid the "false positive" in our build we implemented
-[[https://golang.org/cl/6624059][a non-racy version]]
+[a non-racy version](https://golang.org/cl/6624059)
that is enabled only when the race detector is running.
-But a few months later [[https://bradfitz.com/][Brad]] encountered a
-[[https://golang.org/issue/4589][frustrating and strange bug]].
+But a few months later [Brad](https://bradfitz.com/) encountered a
+[frustrating and strange bug](https://golang.org/issue/4589).
After a few days of debugging, he narrowed it down to a real race condition
caused by `ioutil.Discard`.
@@ -232,11 +233,11 @@
}
The bug was finally
-[[https://golang.org/cl/7011047][fixed]]
+[fixed](https://golang.org/cl/7011047)
by giving a unique buffer to each use of `ioutil.Discard`, eliminating the race
condition on the shared buffer.
-* Conclusions
+## Conclusions
The race detector is a powerful tool for checking the correctness of concurrent
programs. It will not issue false positives, so take its warnings seriously.
@@ -244,4 +245,4 @@
exercise the concurrent properties of your code so that the race detector can
do its job.
-What are you waiting for? Run `"go`test`-race"` on your code today!
+What are you waiting for? Run `"go test -race"` on your code today!
diff --git a/content/real-go-projects-smarttwitter-and-webgo.article b/content/real-go-projects-smarttwitter-and-webgo.article
index 2c79ac7..4881648 100644
--- a/content/real-go-projects-smarttwitter-and-webgo.article
+++ b/content/real-go-projects-smarttwitter-and-webgo.article
@@ -1,27 +1,28 @@
-Real Go Projects: SmartTwitter and web.go
+# Real Go Projects: SmartTwitter and web.go
19 Oct 2010
Tags: guest
+Summary: _This week's article is written by_ [_Michael Hoisie_](http://www.hoisie.com/). _A programmer based in San Francisco, he is one of Go's early adopters and the author of several popular Go libraries. He describes his experiences using Go:_
Michael Hoisie
-* Introduction
+##
-_This_week's_article_is_written_by_ [[http://www.hoisie.com/][_Michael_Hoisie_]].
-_A_programmer_based_in_San_Francisco,_he_is_one_of_Go's_early_adopters_and_the_author_of_several_popular_Go_libraries._He_describes_his_experiences_using_Go:_
+_This week's article is written by_ [_Michael Hoisie_](http://www.hoisie.com/).
+_A programmer based in San Francisco, he is one of Go's early adopters and the author of several popular Go libraries. He describes his experiences using Go:_
-I was introduced to Go by a post on [[http://news.ycombinator.com/][Hacker News]].
+I was introduced to Go by a post on [Hacker News](http://news.ycombinator.com/).
About an hour later I was hooked. At the time I was working at a web start-up,
and had been developing internal testing apps in Python.
Go offered speed, better concurrency support,
and sane Unicode handling, so I was keen to port my programs to the language.
At that time there wasn't an easy way to write web apps in Go,
so I decided to build a simple web framework,
-[[http://github.com/hoisie/web.go][web.go]].
+[web.go](http://github.com/hoisie/web.go).
It was modeled after a popular Python framework,
-[[http://webpy.org/][web.py]], which I had worked with previously.
+[web.py](http://webpy.org/), which I had worked with previously.
While working on web.go I got involved in the Go community,
submitted a bunch of bug reports, and hacked on some standard library packages
-(mainly [[https://golang.org/pkg/http/][http]] and [[https://golang.org/pkg/json/][json]]).
+(mainly [http](https://golang.org/pkg/http/) and [json](https://golang.org/pkg/json/)).
After a few weeks I noticed that web.go was getting attention at Github.
This was surprising because I'd never really promoted the project.
@@ -34,10 +35,10 @@
but it re-posts everything, creating noise in your Facebook feed.
My application allowed you to filter retweets,
mentions, hashtags, replies, and more.
-This turned into [[http://www.facebook.com/apps/application.php?id=135488932982][Smart Twitter]],
+This turned into [Smart Twitter](http://www.facebook.com/apps/application.php?id=135488932982),
which currently has nearly 90,000 users.
-The entire program is written in Go, and uses [[https://redis.io/][Redis]]
+The entire program is written in Go, and uses [Redis](https://redis.io/)
as its storage back-end.
It is very fast and robust. It currently processes about two dozen tweets per second,
and makes heavy use of Go's channels.
@@ -51,9 +52,9 @@
or re-posting incoming tweets.
Smart Twitter also spawned other open-source Go projects:
-[[http://github.com/hoisie/mustache.go][mustache.go]],
-[[http://github.com/hoisie/redis.go][redis.go]],
-and [[http://github.com/hoisie/twitterstream][twitterstream]].
+[mustache.go](http://github.com/hoisie/mustache.go),
+[redis.go](http://github.com/hoisie/redis.go),
+and [twitterstream](http://github.com/hoisie/twitterstream).
I see a lot of work left to do on web.go.
For instance, I'd like to add better support for streaming connections,
diff --git a/content/share-memory-by-communicating.article b/content/share-memory-by-communicating.article
index 01c7426..12bff79 100644
--- a/content/share-memory-by-communicating.article
+++ b/content/share-memory-by-communicating.article
@@ -1,10 +1,11 @@
-Share Memory By Communicating
+# Share Memory By Communicating
13 Jul 2010
Tags: concurrency, technical
+Summary: Traditional threading models (commonly used when writing Java, C++, and Python programs, for example) require the programmer to communicate between threads using shared memory. Typically, shared data structures are protected by locks, and threads will contend over those locks to access the data. In some cases, this is made easier by the use of thread-safe data structures such as Python's Queue.
Andrew Gerrand
-* Introduction
+##
Traditional threading models (commonly used when writing Java,
C++, and Python programs, for example) require the programmer to communicate
@@ -16,15 +17,15 @@
Go's concurrency primitives - goroutines and channels - provide an elegant
and distinct means of structuring concurrent software.
-(These concepts have an [[https://swtch.com/~rsc/thread/][interesting history]] that begins with C.
-A. R. Hoare's [[http://www.usingcsp.com/][Communicating Sequential Processes]].)
+(These concepts have an [interesting history](https://swtch.com/~rsc/thread/) that begins with C.
+A. R. Hoare's [Communicating Sequential Processes](http://www.usingcsp.com/).)
Instead of explicitly using locks to mediate access to shared data,
Go encourages the use of channels to pass references to data between goroutines.
This approach ensures that only one goroutine has access to the data at a given time.
-The concept is summarized in the document [[https://golang.org/doc/effective_go.html][Effective Go]]
+The concept is summarized in the document [Effective Go](https://golang.org/doc/effective_go.html)
(a must-read for any Go programmer):
-_Do_not_communicate_by_sharing_memory;_instead,_share_memory_by_communicating._
+_Do not communicate by sharing memory; instead, share memory by communicating._
Consider a program that polls a list of URLs.
In a traditional threading environment, one might structure its data like so:
@@ -102,4 +103,4 @@
There are many omissions from the above code snippets.
For a walkthrough of a complete, idiomatic Go program that uses these ideas,
-see the Codewalk [[https://golang.org/doc/codewalk/sharemem/][_Share_Memory_By_Communicating_]].
+see the Codewalk [_Share Memory By Communicating_](https://golang.org/doc/codewalk/sharemem/).
diff --git a/content/slices.article b/content/slices.article
index 324e8e1..d129ccd 100644
--- a/content/slices.article
+++ b/content/slices.article
@@ -1,20 +1,21 @@
-Arrays, slices (and strings): The mechanics of 'append'
+# Arrays, slices (and strings): The mechanics of 'append'
26 Sep 2013
Tags: array, slice, string, copy, append
+Summary: One of the most common features of procedural programming languages is the concept of an array. Arrays seem like simple things but there are many questions that must be answered when adding them to a language, such as:
Rob Pike
-* Introduction
+## Introduction
One of the most common features of procedural programming languages is
the concept of an array.
Arrays seem like simple things but there are many questions that must be
answered when adding them to a language, such as:
-- fixed-size or variable-size?
-- is the size part of the type?
-- what do multidimensional arrays look like?
-- does the empty array have meaning?
+ - fixed-size or variable-size?
+ - is the size part of the type?
+ - what do multidimensional arrays look like?
+ - does the empty array have meaning?
The answers to these questions affect whether arrays are just
a feature of the language or a core part of its design.
@@ -30,7 +31,7 @@
We'll do so by building up the pieces to explain how the `append` built-in function
works, and why it works the way it does.
-* Arrays
+## Arrays
Arrays are an important building block in Go, but like the foundation of a building
they are often hidden below more visible components.
@@ -68,14 +69,14 @@
matrix for instance—but their most common purpose in Go is to hold storage
for a slice.
-* Slices: The slice header
+## Slices: The slice header
Slices are where the action is, but to use them well one must understand
exactly what they are and what they do.
A slice is a data structure describing a contiguous section of an array
stored separately from the slice variable itself.
-_A_slice_is_not_an_array_.
+_A slice is not an array_.
A slice _describes_ a piece of an array.
Given our `buffer` array variable from the previous section, we could create
@@ -153,7 +154,7 @@
You'll often hear experienced Go programmers talk about the "slice header"
because that really is what's stored in a slice variable.
For instance, when you call a function that takes a slice as an argument, such as
-[[https://golang.org/pkg/bytes/#IndexRune][bytes.IndexRune]], that header is
+[bytes.IndexRune](https://golang.org/pkg/bytes/#IndexRune), that header is
what gets passed to the function.
In this call,
@@ -166,7 +167,7 @@
but first let's see what the existence of the slice header means when you
program with slices.
-* Passing slices to functions
+## Passing slices to functions
It's important to understand that even though a slice contains a pointer,
it is itself a value.
@@ -212,7 +213,7 @@
The `slice` variable is unchanged but the returned value has the new length,
which is then stored in `newSlice`,
-* Pointers to slices: Method receivers
+## Pointers to slices: Method receivers
Another way to have a function modify the slice header is to pass a pointer to it.
Here's a variant of our previous example that does this:
@@ -248,7 +249,7 @@
[Advanced exercise: Convert the `ToUpper` method to handle Unicode letters, not just ASCII.]
-* Capacity
+## Capacity
Look at the following function that extends its argument slice of `ints` by one element:
@@ -293,7 +294,7 @@
fmt.Println("slice is full!")
}
-* Make
+## Make
What if we want to grow the slice beyond its capacity?
You can't!
@@ -329,7 +330,7 @@
the `gophers` slice has both its length and capacity set to 10.
-* Copy
+## Copy
When we doubled the capacity of our slice in the previous section,
we wrote a loop to copy the old data to the new slice.
@@ -376,7 +377,7 @@
.play -edit slices/prog100.go /make/,/OMIT/
-* Append: An example
+## Append: An example
A few sections back, we wrote an `Extend` function that extends a slice by one element.
It was buggy, though, because if the slice's capacity was too small, the function would
@@ -445,7 +446,7 @@
.play -edit slices/prog140.go /START/,/END/
-* Append: The built-in function
+## Append: The built-in function
And so we arrive at the motivation for the design of the `append` built-in function.
It does exactly what our `Append` example does, with equivalent efficiency, but it
@@ -469,9 +470,9 @@
There are lots more examples of `append`, `copy`, and other ways to use slices
on the community-built
-[[https://golang.org/wiki/SliceTricks]["Slice Tricks" Wiki page]].
+["Slice Tricks" Wiki page](https://golang.org/wiki/SliceTricks).
-* Nil
+## Nil
As an aside, with our newfound knowledge we can see what the representation of a `nil` slice is.
Naturally, it is the zero value of the slice header:
@@ -502,7 +503,7 @@
As an example, look at the one-liner above that copies a slice by appending
to a `nil` slice.
-* Strings
+## Strings
Now a brief section about strings in Go in the context of slices.
@@ -549,9 +550,9 @@
the benchmarks saw huge speedups as a result.
There's much more to strings, of course, and a
-[[https://blog.golang.org/strings][separate blog post]] covers them in greater depth.
+[separate blog post](https://blog.golang.org/strings) covers them in greater depth.
-* Conclusion
+## Conclusion
To understand how slices work, it helps to understand how they are implemented.
There is a little data structure, the slice header, that is the item associated with the slice
@@ -563,15 +564,15 @@
powerful and expressive, especially with the help of the `copy` and `append`
built-in functions.
-* More reading
+## More reading
There's lots to find around the intertubes about slices in Go.
As mentioned earlier,
-the [[https://golang.org/wiki/SliceTricks]["Slice Tricks" Wiki page]]
+the ["Slice Tricks" Wiki page](https://golang.org/wiki/SliceTricks)
has many examples.
-The [[https://blog.golang.org/go-slices-usage-and-internals][Go Slices]] blog post
+The [Go Slices](https://blog.golang.org/go-slices-usage-and-internals) blog post
describes the memory layout details with clear diagrams.
-Russ Cox's [[https://research.swtch.com/godata][Go Data Structures]] article includes
+Russ Cox's [Go Data Structures](https://research.swtch.com/godata) article includes
a discussion of slices along with some of Go's other internal data structures.
There is much more material available, but the best way to learn about slices is to use them.
diff --git a/content/spotlight-on-external-go-libraries.article b/content/spotlight-on-external-go-libraries.article
index 75500cc..e92bdf4 100644
--- a/content/spotlight-on-external-go-libraries.article
+++ b/content/spotlight-on-external-go-libraries.article
@@ -1,57 +1,58 @@
-Spotlight on external Go libraries
+# Spotlight on external Go libraries
3 Jun 2011
Tags: community, libraries
+Summary: While the Go authors have been working hard at improving Go's standard library, the greater community has created a growing ecosystem of external libraries. In this post we look at some popular Go libraries and how they can be used.
Andrew Gerrand
-* Introduction
+##
While the Go authors have been working hard at improving Go's standard library,
the greater community has created a growing ecosystem of external libraries.
In this post we look at some popular Go libraries and how they can be used.
-[[http://labix.org/mgo][Mgo]] (pronounced "mango") is a MongoDB database driver.
-[[http://www.mongodb.org/][MongoDB]] is a [[http://en.wikipedia.org/wiki/Document-oriented_database][document-oriented database]]
-with a long list of features suitable for [[http://www.mongodb.org/display/DOCS/Use%2BCases][a broad range of uses]].
+[Mgo](http://labix.org/mgo) (pronounced "mango") is a MongoDB database driver.
+[MongoDB](http://www.mongodb.org/) is a [document-oriented database](http://en.wikipedia.org/wiki/Document-oriented_database)
+with a long list of features suitable for [a broad range of uses](http://www.mongodb.org/display/DOCS/Use%2BCases).
The mgo package provides a rich, idiomatic Go API for working with MongoDB,
from basic operations such as inserting and updating records to the more
-advanced [[http://www.mongodb.org/display/DOCS/MapReduce][MapReduce]] and
-[[http://www.mongodb.org/display/DOCS/GridFS][GridFS]] features.
+advanced [MapReduce](http://www.mongodb.org/display/DOCS/MapReduce) and
+[GridFS](http://www.mongodb.org/display/DOCS/GridFS) features.
Mgo has a bunch of cool features including automated cluster discovery and
-result pre-fetching - see the [[http://labix.org/mgo][mgo homepage]] for
+result pre-fetching - see the [mgo homepage](http://labix.org/mgo) for
details and example code.
For working with large data sets Go, MongoDB,
and mgo are a powerful combination.
-[[https://github.com/dchest/authcookie][Authcookie]] is a web library for
+[Authcookie](https://github.com/dchest/authcookie) is a web library for
generating and verifying user authentication cookies.
It allows web servers to hand out cryptographically secure tokens tied to
a specific user that will expire after a specified time period.
It has a simple API that makes it straightforward to add authentication
to existing web applications.
-See the [[https://github.com/dchest/authcookie/blob/master/README.md][README file]]
+See the [README file](https://github.com/dchest/authcookie/blob/master/README.md)
for details and example code.
-[[http://code.google.com/p/go-charset][Go-charset]] provides support for
+[Go-charset](http://code.google.com/p/go-charset) provides support for
converting between Go's standard UTF-8 encoding and a variety of character sets.
The go-charset package implements a translating io.Reader and io.Writer
so you can wrap existing Readers and Writers (such as network connections
or file descriptors),
making it easy to communicate with systems that use other character encodings.
-[[https://github.com/madari/go-socket.io][Go-socket.io]] is a Go implementation
-of [[http://socket.io/][Socket.IO]],
+[Go-socket.io](https://github.com/madari/go-socket.io) is a Go implementation
+of [Socket.IO](http://socket.io/),
a client/server API that allows web servers to push messages to web browsers.
Depending on the capabilities of the user's browser,
Socket.IO uses the best transport for the connection,
be it modern websockets, AJAX long polling,
-or some [[http://socket.io/#transports][other mechanism]].
+or some [other mechanism](http://socket.io/#transports).
Go-socket.io bridges the gap between Go servers and rich JavaScript clients
for a wide range of browsers.
-To get a feel for go-socket.io see the [[https://github.com/madari/go-socket.io/blob/master/example/example.go][chat server example]].
+To get a feel for go-socket.io see the [chat server example](https://github.com/madari/go-socket.io/blob/master/example/example.go).
-It's worth mentioning that these packages are [[https://golang.org/cmd/goinstall/][goinstallable]].
-With an up-to-date Go [[https://golang.org/doc/install.html][installation]]
+It's worth mentioning that these packages are [goinstallable](https://golang.org/cmd/goinstall/).
+With an up-to-date Go [installation](https://golang.org/doc/install.html)
you can install them all with a single command:
goinstall launchpad.net/mgo \
@@ -69,10 +70,10 @@
)
Also, as they are now a part of the local Go system,
-we can inspect their documentation with [[https://golang.org/cmd/godoc/][godoc]]:
+we can inspect their documentation with [godoc](https://golang.org/cmd/godoc/):
godoc launchpad.net/mgo Database # see docs for Database type
Of course, this is just the tip of the iceberg;
-there are more great Go libraries listed on the [[http://godashboard.appspot.com/package][package dashboard]]
+there are more great Go libraries listed on the [package dashboard](http://godashboard.appspot.com/package)
and many more to come.
diff --git a/content/store.article b/content/store.article
index f295fa4..7dee6cf 100644
--- a/content/store.article
+++ b/content/store.article
@@ -1,25 +1,26 @@
-Announcing The New Go Store
+# Announcing The New Go Store
18 Jul 2019
+Summary: **October 1, 2019, Update:** _The Go Store is currently offline._ _We are sorry for any inconvenience._ _We will update this post with any status changes._
Cassandra Salisbury
-* Introduction
+##
-*October*1,*2019,*Update:* _The_Go_Store_is_currently_offline._
-_We_are_sorry_for_any_inconvenience._
-_We_will_update_this_post_with_any_status_changes._
+**October 1, 2019, Update:** _The Go Store is currently offline._
+_We are sorry for any inconvenience._
+_We will update this post with any status changes._
We are excited to launch the new Go official swag and merch store, shipping worldwide.
-We are even more excited to announce that *100%*of*the*proceeds* from the Go store go directly to GoBridge.
-[[https://github.com/gobridge/about-us][GoBridge]] is a non-profit organization focused on building bridges to educate underrepresented groups by teaching technical skills and fostering diversity in the Go community.
+We are even more excited to announce that **100% of the proceeds** from the Go store go directly to GoBridge.
+[GoBridge](https://github.com/gobridge/about-us) is a non-profit organization focused on building bridges to educate underrepresented groups by teaching technical skills and fostering diversity in the Go community.
.image store/gophers.jpg
-At the *Go*store* you’ll find our beloved gopher plushies and vinyls as well as new merchandise.
-Visit the store for 20% off with code *Gopher20* through Sunday, July 21st at 11:59 PM PST.
+At the **Go store** you’ll find our beloved gopher plushies and vinyls as well as new merchandise.
+Visit the store for 20% off with code **Gopher20** through Sunday, July 21st at 11:59 PM PST.
We plan on adding stock to current items and bringing on new ones to the store.
If we are out of stock when you go to place an order, check back again soon.
-Follow the [[https://twitter.com/golang][Twitter account]] for updates, we plan on adding new goodies for all our Go fans out there, so keep an eye out!
+Follow the [Twitter account](https://twitter.com/golang) for updates, we plan on adding new goodies for all our Go fans out there, so keep an eye out!
Happy shopping!
diff --git a/content/strings.article b/content/strings.article
index 0a9bd8f..122ba7c 100644
--- a/content/strings.article
+++ b/content/strings.article
@@ -1,12 +1,13 @@
-Strings, bytes, runes and characters in Go
+# Strings, bytes, runes and characters in Go
23 Oct 2013
Tags: strings, bytes, runes, characters
+Summary: The [previous blog post](https://blog.golang.org/slices) explained how slices work in Go, using a number of examples to illustrate the mechanism behind their implementation. Building on that background, this post discusses strings in Go. At first, strings might seem too simple a topic for a blog post, but to use them well requires understanding not only how they work, but also the difference between a byte, a character, and a rune, the difference between Unicode and UTF-8, the difference between a string and a string literal, and other even more subtle distinctions.
Rob Pike
-* Introduction
+## Introduction
-The [[https://blog.golang.org/slices][previous blog post]] explained how slices
+The [previous blog post](https://blog.golang.org/slices) explained how slices
work in Go, using a number of examples to illustrate the mechanism behind
their implementation.
Building on that background, this post discusses strings in Go.
@@ -25,16 +26,16 @@
An excellent introduction to some of these issues, independent of Go,
is Joel Spolsky's famous blog post,
-[[http://www.joelonsoftware.com/articles/Unicode.html][The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!)]].
+[The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!)](http://www.joelonsoftware.com/articles/Unicode.html).
Many of the points he raises will be echoed here.
-* What is a string?
+## What is a string?
Let's start with some basics.
In Go, a string is in effect a read-only slice of bytes.
If you're at all uncertain about what a slice of bytes is or how it works,
-please read the [[https://blog.golang.org/slices][previous blog post]];
+please read the [previous blog post](https://blog.golang.org/slices);
we'll assume here that you have.
It's important to state right up front that a string holds _arbitrary_ bytes.
@@ -48,7 +49,7 @@
.code strings/basic.go /const sample/
-* Printing strings
+## Printing strings
Because some of the bytes in our sample string are not valid ASCII, not even
valid UTF-8, printing the string directly will produce ugly output.
@@ -145,7 +146,7 @@
[Exercise: Loop over the string using the `%q` format on each byte.
What does the output tell you?]
-* UTF-8 and string literals
+## UTF-8 and string literals
As we saw, indexing a string yields its bytes, not its characters: a string is just a
bunch of bytes.
@@ -189,7 +190,7 @@
data the editor placed in the file.
In short, Go source code is UTF-8, so
-_the_source_code_for_the_string_literal_is_UTF-8_text_.
+_the source code for the string literal is UTF-8 text_.
If that string literal contains no escape sequences, which a raw
string cannot, the constructed string will hold exactly the
source text between the quotes.
@@ -210,7 +211,7 @@
To summarize, strings can contain arbitrary bytes, but when constructed
from string literals, those bytes are (almost always) UTF-8.
-* Code points, characters, and runes
+## Code points, characters, and runes
We've been very careful so far in how we use the words "byte" and "character".
That's partly because strings hold bytes, and partly because the idea of "character"
@@ -219,7 +220,7 @@
by a single value.
The code point U+2318, with hexadecimal value 2318, represents the symbol ⌘.
(For lots more information about that code point, see
-[[http://unicode.org/cldr/utility/character.jsp?a=2318][its Unicode page]].)
+[its Unicode page](http://unicode.org/cldr/utility/character.jsp?a=2318).)
To pick a more prosaic example, the Unicode code point U+0061 is the lower
case Latin letter 'A': a.
@@ -247,7 +248,7 @@
The Go language defines the word `rune` as an alias for the type `int32`, so
programs can be clear when an integer value represents a code point.
Moreover, what you might think of as a character constant is called a
-_rune_constant_ in Go.
+_rune constant_ in Go.
The type and value of the expression
'⌘'
@@ -256,13 +257,13 @@
To summarize, here are the salient points:
-- Go source code is always UTF-8.
-- A string holds arbitrary bytes.
-- A string literal, absent byte-level escapes, always holds valid UTF-8 sequences.
-- Those sequences represent Unicode code points, called runes.
-- No guarantee is made in Go that characters in strings are normalized.
+ - Go source code is always UTF-8.
+ - A string holds arbitrary bytes.
+ - A string literal, absent byte-level escapes, always holds valid UTF-8 sequences.
+ - Those sequences represent Unicode code points, called runes.
+ - No guarantee is made in Go that characters in strings are normalized.
-* Range loops
+## Range loops
Besides the axiomatic detail that Go source code is UTF-8,
there's really only one way that Go treats UTF-8 specially, and that is when using
@@ -287,14 +288,14 @@
[Exercise: Put an invalid UTF-8 byte sequence into the string. (How?)
What happens to the iterations of the loop?]
-* Libraries
+## Libraries
Go's standard library provides strong support for interpreting UTF-8 text.
If a `for` `range` loop isn't sufficient for your purposes,
chances are the facility you need is provided by a package in the library.
The most important such package is
-[[https://golang.org/pkg/unicode/utf8/][`unicode/utf8`]],
+[`unicode/utf8`](https://golang.org/pkg/unicode/utf8/),
which contains
helper routines to validate, disassemble, and reassemble UTF-8 strings.
Here is a program equivalent to the `for` `range` example above,
@@ -310,11 +311,11 @@
exactly the same iteration sequence.
Look at the
-[[https://golang.org/pkg/unicode/utf8/][documentation]]
+[documentation](https://golang.org/pkg/unicode/utf8/)
for the `unicode/utf8` package to see what
other facilities it provides.
-* Conclusion
+## Conclusion
To answer the question posed at the beginning: Strings are built from bytes
so indexing them yields bytes, not characters.
diff --git a/content/subtests.article b/content/subtests.article
index e3c212d..54b3eb7 100644
--- a/content/subtests.article
+++ b/content/subtests.article
@@ -1,20 +1,21 @@
-Using Subtests and Sub-benchmarks
-03 Oct 2016
+# Using Subtests and Sub-benchmarks
+3 Oct 2016
Tags: testing, hierarchy, table-driven, subtests, sub-benchmarks
+Summary: In Go 1.7, the `testing` package introduces a Run method on the [`T`](https://golang.org/pkg/testing/#T.Run) and [`B`](https://golang.org/pkg/testing/#B.Run) types that allows for the creation of subtests and sub-benchmarks. The introduction of subtests and sub-benchmarks enables better handling of failures, fine-grained control of which tests to run from the command line, control of parallelism, and often results in simpler and more maintainable code.
Marcel van Lohuizen
-* Introduction
+## Introduction
In Go 1.7, the `testing` package introduces a Run method on the
-[[https://golang.org/pkg/testing/#T.Run][`T`]] and
-[[https://golang.org/pkg/testing/#B.Run][`B`]] types
+[`T`](https://golang.org/pkg/testing/#T.Run) and
+[`B`](https://golang.org/pkg/testing/#B.Run) types
that allows for the creation of subtests and sub-benchmarks.
The introduction of subtests and sub-benchmarks enables better handling of
failures, fine-grained control of which tests to run from the command line,
control of parallelism, and often results in simpler and more maintainable code.
-* Table-driven tests basics
+## Table-driven tests basics
Before digging into the details, let's first discuss a common
way of writing tests in Go.
@@ -47,7 +48,7 @@
of repetitive code compared to repeating the same code for each test
and makes it straightforward to add more test cases.
-* Table-driven benchmarks
+## Table-driven benchmarks
Before Go 1.7 it was not possible to use the same table-driven approach for
benchmarks.
@@ -111,7 +112,7 @@
Moreover, common setup code is now shared between runs while eliminating the
need to reset the timer.
-* Table-driven tests using subtests
+## Table-driven tests using subtests
Go 1.7 also introduces a `Run` method for creating subtests.
This test is a rewritten version of our earlier example using subtests:
@@ -167,10 +168,10 @@
There are several other benefits to using subtests or sub-benchmarks,
as clarified by the following sections.
-* Running specific tests or benchmarks
+## Running specific tests or benchmarks
Both subtests and sub-benchmarks can be singled out on the command line using
-the [[https://golang.org/cmd/go/#hdr-Description_of_testing_flags][`-run` or `-bench` flag]].
+the [`-run` or `-bench` flag](https://golang.org/cmd/go/#hdr-Description_of_testing_flags).
Both flags take a slash-separated list of regular expressions that match the
corresponding parts of the full name of the subtest or sub-benchmark.
@@ -234,7 +235,7 @@
if there is no obvious naming scheme for subtests and the subtests
can easily be identified by their sequence number.
-* Setup and Tear-down
+## Setup and Tear-down
Subtests and sub-benchmarks can be used to manage common setup and tear-down code:
@@ -254,7 +255,7 @@
and will run at most once.
This applies even if any of the subtests calls `Skip`, `Fail`, or `Fatal`.
-* Control of Parallelism
+## Control of Parallelism
Subtests allow fine-grained control over parallelism.
To understand how to use subtests in the way
@@ -278,7 +279,7 @@
In fact, under the hood top-level tests are implemented as subtests of
a hidden master test.
-** Run a group of tests in parallel
+### Run a group of tests in parallel
The above semantics allows for running a group of tests in parallel with
each other but not with other parallel tests:
@@ -303,7 +304,7 @@
Note that we need to capture the range variable to ensure that `tc` gets bound to
the correct instance.
-** Cleaning up after a group of parallel tests
+### Cleaning up after a group of parallel tests
In the previous example we used the semantics to wait on a group of parallel
tests to complete before commencing other tests.
@@ -324,7 +325,7 @@
The behavior of waiting on a group of parallel tests is identical to that
of the previous example.
-* Conclusion
+## Conclusion
Go 1.7's addition of subtests and sub-benchmarks allows you to write structured
tests and benchmarks in a natural way that blends nicely into the existing
diff --git a/content/survey2016-results.article b/content/survey2016-results.article
index b5756cf..ec0b316 100644
--- a/content/survey2016-results.article
+++ b/content/survey2016-results.article
@@ -1,16 +1,17 @@
-Go 2016 Survey Results
-06 Mar 2017
+# Go 2016 Survey Results
+6 Mar 2017
Tags: survey, community
+Summary: This post summarizes the result of our December 2016 user survey along with our commentary and insights. We are grateful to everyone who provided their feedback through the survey to help shape the future of Go.
Steve Francia, for the Go team
spf@golang.org
-* Thank you
+## Thank you
This post summarizes the result of our December 2016 user survey along with our commentary and insights.
We are grateful to everyone who provided their feedback through the survey to help shape the future of Go.
-* Programming background
+## Programming background
Of the 3,595 survey respondents, 89% said they program in Go at work or outside of work,
with 39% using Go both at home and at work, 27% using Go only at home, and 23% using Go only at work.
@@ -34,7 +35,7 @@
.html survey2016/background.html
-* Go usage
+## Go usage
Users are overwhelmingly happy with Go:
they agree that they would recommend Go to others by a ratio of 19:1,
@@ -66,7 +67,7 @@
.html survey2016/usage.html
-* Development and deployment
+## Development and deployment
When asked which operating systems they develop Go on,
63% of respondents say they use Linux, 44% use MacOS, and 19% use Windows,
@@ -78,7 +79,7 @@
.html survey2016/dev.html
-* Working Effectively
+## Working Effectively
We asked how strongly people agreed or disagreed with various statements about Go.
Users most agreed that Go’s performance meets their needs (57:1 ratio agree versus disagree),
@@ -103,7 +104,7 @@
.html survey2016/effective.html
-* The Go Project
+## The Go Project
55% of respondents expressed interest in contributing in some way to the Go community and projects.
Unfortunately, relatively few agreed that they felt welcome to do so (3.3:1)
@@ -123,7 +124,7 @@
.html survey2016/project.html
-* Community
+## Community
At the end of the survey, we asked some demographic questions.
The country distribution of responses roughly matches the country distribution of site visits to golang.org,
diff --git a/content/survey2016.article b/content/survey2016.article
index 6a26bca..66923ba 100644
--- a/content/survey2016.article
+++ b/content/survey2016.article
@@ -1,51 +1,52 @@
-Participate in the 2016 Go User Survey and Company Questionnaire
+# Participate in the 2016 Go User Survey and Company Questionnaire
13 Dec 2016
Tags: survey, community
+Summary: The Go project wants to hear from you! Our goal is to create the best language for developing simple, reliable, scalable software. We are asking you to help by participating in a survey and if applicable, a company questionnaire.
Steve Francia
spf@golang.org
-* The Go project wants to hear from you!
+## The Go project wants to hear from you!
The Go project wants to hear from you! Our goal is to create the best language
for developing simple, reliable, scalable software. We are asking you to help
by participating in a survey and if applicable, a company questionnaire.
-* The Go User Survey
+## The Go User Survey
-*Who:* If you use Go, have ever used Go, have ever stopped using Go, or have
+**Who:** If you use Go, have ever used Go, have ever stopped using Go, or have
any interest in the language, please help by sharing your feedback to improve
Go for you and your fellow Gophers.
-*Where:* Please take this 20-minute survey by December 22nd: [[https://goo.gl/NJgrHT][Go User Survey 2016]]
+**Where:** Please take this 20-minute survey by December 22nd: [Go User Survey 2016](https://goo.gl/NJgrHT)
The survey is anonymous and confidential.
-*Why:* The Go project leadership depends on your feedback to guide the future
+**Why:** The Go project leadership depends on your feedback to guide the future
of the Go project. Your responses will help to understand how we are doing and
help plan improvements for the Go language, libraries, and tools.
After the survey closes, we will publish the anonymous aggregate results to the Go blog.
-* The Go Company Questionnaire
+## The Go Company Questionnaire
-*Who:* If you are in a position to share details like “company name”, “if your
+**Who:** If you are in a position to share details like “company name”, “if your
company is hiring Go developers”, and “reasons your team or company adopted Go”
then please help us by taking this questionnaire. We only need one response per
company (or department for larger companies).
-*Where:* Please take this 5-minute questionnaire by December 22nd: [[https://goo.gl/Epya2q][Go Company Questionnaire 2016]]
+**Where:** Please take this 5-minute questionnaire by December 22nd: [Go Company Questionnaire 2016](https://goo.gl/Epya2q)
The questionnaire is confidential, but not anonymous.
-*Why:* The Go project would like to better understand the companies using Go.
+**Why:** The Go project would like to better understand the companies using Go.
After the questionnaire closes the Go project leadership will use this
information to better understand how companies are utilizing Go and in what
ways the project can improve their experience. If you participate we may reach
out for further information.
-* Spread the word!
+## Spread the word!
Please help us spread the word by sharing this post on your social network
feeds, at meetups, around your office and in other communities.
diff --git a/content/survey2017-results.article b/content/survey2017-results.article
index 59ebc9a..ef71648 100644
--- a/content/survey2017-results.article
+++ b/content/survey2017-results.article
@@ -1,18 +1,19 @@
-Go 2017 Survey Results
+# Go 2017 Survey Results
26 Feb 2018
Tags: survey, community
+Summary: This post summarizes the result of our 2017 user survey along with commentary and insights. It also draws key comparisons between the results of the 2016 and 2017 survey.
Steve Francia
spf@golang.org
-* Thank you
+## Thank you
This post summarizes the result of our 2017 user survey along with commentary
and insights. It also draws key comparisons between the results of the 2016 and
2017 survey.
This year we had 6,173 survey respondents, 70% more than the 3,595 we had in the
-[[https://blog.golang.org/survey2016-results][Go 2016 User Survey]]. In
+[Go 2016 User Survey](https://blog.golang.org/survey2016-results). In
addition, it also had a slightly higher completion rate (84% → 87%) and a
higher response rate to most of the questions. We believe that survey length is
the main cause of this improvement as the 2017 survey was shortened in response
@@ -21,7 +22,7 @@
We are grateful to everyone who provided their feedback through the survey to
help shape the future of Go.
-* Programming background
+## Programming background
For the first time, more survey respondents say they are paid to write Go
than say they write it outside work. This indicates a significant shift in
@@ -45,7 +46,7 @@
.html survey2017/background.html
-* Go usage
+## Go usage
In nearly every question around the usage and perception of Go, Go has
demonstrated improvement over our prior survey. Users are happier using Go, and
@@ -56,10 +57,10 @@
their two biggest issues, consistent with 2016. In 2017 we laid a foundation to
be able to address these issues. We improved our proposal and development
process with the addition of
-[[https://golang.org/wiki/ExperienceReports][Experience Reports]] which is
+[Experience Reports](https://golang.org/wiki/ExperienceReports) which is
enabling the project to gather and obtain feedback critical to making these
significant changes. We also made
-[[https://golang.org/doc/go1.10#build][sigificant changes]] under the hood in
+[sigificant changes](https://golang.org/doc/go1.10#build) under the hood in
how Go obtains, and builds packages. This is foundational work essential to
addressing our dependency management needs.
@@ -76,7 +77,7 @@
.html survey2017/usage.html
-* Development and deployment
+## Development and deployment
We asked programmers which operating systems they develop Go on; the ratios of
their responses remain consistent with last year. 64% of respondents say
@@ -99,12 +100,12 @@
.html survey2017/dev.html
-* Working Effectively
+## Working Effectively
We asked how strongly people agreed or disagreed with various statements about
Go. All questions are repeated from last year with the addition of one new
question which we introduced to add further clarifaction around how users are
-able to both find and *use* Go libraries.
+able to both find and **use** Go libraries.
All responses either indicated a small improvement or are comparable to 2016.
@@ -122,7 +123,7 @@
.html survey2017/effective.html
-* The Go Project
+## The Go Project
59% of respondents expressed interest in contributing in some way to the Go
community and projects, up from 55% last year. Respondents also indicated that
@@ -140,13 +141,13 @@
forward. We will continue to work to improve our understanding of user needs and
approachability.
-We tried some [[https://blog.golang.org/8years#TOC_1.3.][new ways]] to engage
+We tried some [new ways](https://blog.golang.org/8years#TOC_1.3.) to engage
with users in 2017 and while progress was made, we are still working on making these
solutions scalable for our growing community.
.html survey2017/project.html
-* Community
+## Community
At the end of the survey, we asked some demographic questions.
diff --git a/content/survey2017.article b/content/survey2017.article
index 8c29489..3f1f758 100644
--- a/content/survey2017.article
+++ b/content/survey2017.article
@@ -1,39 +1,40 @@
-Participate in the 2017 Go User Survey
+# Participate in the 2017 Go User Survey
16 Nov 2017
Tags: survey, community
+Summary: Last year we conducted the first ever [Go user survey](https://blog.golang.org/survey2016-results). Thanks to all of you, it was an overwhelming success with over 3500 responses. The survey provided key insights and helped us better plan and prioritize.
Steve Francia
spf@golang.org
-* The Go project wants to hear from you (again)!
+## The Go project wants to hear from you (again)!
Last year we conducted the first ever
-[[https://blog.golang.org/survey2016-results][Go user survey]]. Thanks to all of you,
+[Go user survey](https://blog.golang.org/survey2016-results). Thanks to all of you,
it was an overwhelming success with over 3500 responses. The survey provided key insights
and helped us better plan and prioritize.
-We invite you to participate in the [[https://goo.gl/n9M7SB][2017 Go User Survey]].
+We invite you to participate in the [2017 Go User Survey](https://goo.gl/n9M7SB).
-* The Go User Survey
+## The Go User Survey
-*Who:* If you currently use Go, have used Go in the past, or have any interest in the language,
+**Who:** If you currently use Go, have used Go in the past, or have any interest in the language,
please help by sharing your feedback to improve Go for you and your fellow
Gophers.
-*Where:* Please take this 15-minute survey by *Friday*December*8th*: [[https://goo.gl/n9M7SB][2017 Go User Survey]]
+**Where:** Please take this 15-minute survey by **Friday December 8th**: [2017 Go User Survey](https://goo.gl/n9M7SB)
The survey is anonymous and confidential.
-*Why:* The Go project leadership depends on your feedback to guide the future
+**Why:** The Go project leadership depends on your feedback to guide the future
of the Go project. Your responses will help to understand what's going well
and what's not, as well as help us prioritize improvements for the Go
language, libraries and tools.
A few weeks after the survey closes, we will publish the anonymous aggregate results to
-the Go blog. See the [[https://blog.golang.org/survey2016-results][2016 Go user survey results]]
+the Go blog. See the [2016 Go user survey results](https://blog.golang.org/survey2016-results)
to learn what insights were gained from last year's survey.
-* Spread the word!
+## Spread the word!
Please help us spread the word by sharing this post on your social network
-feeds, at meetups, around your office and in other communities.
\ No newline at end of file
+feeds, at meetups, around your office and in other communities.
diff --git a/content/survey2018-results.article b/content/survey2018-results.article
index f8ff4f5..f1e7e3b 100644
--- a/content/survey2018-results.article
+++ b/content/survey2018-results.article
@@ -1,48 +1,49 @@
-Go 2018 Survey Results
+# Go 2018 Survey Results
28 Mar 2019
Tags: survey, community
+Summary: This post summarizes the results of our 2018 user survey and draws comparisons between the results of our prior surveys from [2016](https://blog.golang.org/survey2016-results) and [2017](https://blog.golang.org/survey2017-results).
Todd Kulesza, Steve Francia
tkulesza@google.com, spf@golang.org
-* Thank you
+## Thank you
.html survey2018/style.html
This post summarizes the results of our 2018 user survey and draws comparisons
-between the results of our prior surveys from [[https://blog.golang.org/survey2016-results][2016]]
-and [[https://blog.golang.org/survey2017-results][2017]].
+between the results of our prior surveys from [2016](https://blog.golang.org/survey2016-results)
+and [2017](https://blog.golang.org/survey2017-results).
This year we had 5,883 survey respondents from 103 different countries.
We are grateful to everyone who provided their feedback through this survey
to help shape the future of Go. Thank you!
-* Summary of findings
+## Summary of findings
-- For the first time, *half*of*survey*respondents*are*now*using*Go*as*part*of*their*daily*routine*.
- This year also saw significant increases in the number of respondents who
- develop in Go as part of their jobs and use Go outside of work responsibilities.
-- The most *common*uses*for*Go*remain*API/RPC*services*and*CLI*tools*.
- Automation tasks, while not as common as CLI tools and API services,
- are a fast-growing area for Go.
-- *Web*development*remains*the*most*common*domain* that survey respondents work in,
- but *DevOps*showed*the*highest*year-over-year*growth* and is now the second most common domain.
-- A large majority of survey respondents said *Go*is*their*most-preferred*programming*language*,
- despite generally feeling less proficient with it than at least one other language.
-- *VS*Code*and*GoLand*are*surging*in*popularity* and are now the most popular code editors among survey respondents.
-- Highlighting the portable nature of Go,
- *many*Go*developers*use*more*than*one*primary*OS* for development.
- Linux and macOS are particularly popular,
- with a large majority of survey respondents using one or both of these operating
- systems to write Go code.
-- Survey respondents appear to be *shifting*away*from*on-prem*Go*deployments*
- and moving towards containers and serverless cloud deployments.
-- The majority of respondents said they feel welcome in the Go community,
- and most ideas for improving the Go community specifically focus on *improving*the*experience*of*newcomers*.
+ - For the first time, **half of survey respondents are now using Go as part of their daily routine**.
+ This year also saw significant increases in the number of respondents who
+ develop in Go as part of their jobs and use Go outside of work responsibilities.
+ - The most **common uses for Go remain API/RPC services and CLI tools**.
+ Automation tasks, while not as common as CLI tools and API services,
+ are a fast-growing area for Go.
+ - **Web development remains the most common domain** that survey respondents work in,
+ but **DevOps showed the highest year-over-year growth** and is now the second most common domain.
+ - A large majority of survey respondents said **Go is their most-preferred programming language**,
+ despite generally feeling less proficient with it than at least one other language.
+ - **VS Code and GoLand are surging in popularity** and are now the most popular code editors among survey respondents.
+ - Highlighting the portable nature of Go,
+ **many Go developers use more than one primary OS** for development.
+ Linux and macOS are particularly popular,
+ with a large majority of survey respondents using one or both of these operating
+ systems to write Go code.
+ - Survey respondents appear to be **shifting away from on-prem Go deployments**
+ and moving towards containers and serverless cloud deployments.
+ - The majority of respondents said they feel welcome in the Go community,
+ and most ideas for improving the Go community specifically focus on **improving the experience of newcomers**.
Read on for all of the details.
-* Programming background
+## Programming background
This year's results show a significant increase in the number of survey
respondents who are paid to write Go as part of their jobs (68% → 72%),
@@ -72,7 +73,7 @@
who do not view software engineering as a day job:
they also choose to hack on code outside of work responsibilities,
and (as evidenced by 85% of respondents saying they'd prefer Go for their next project,
-see section _Attitudes_towards_Go_ below) Go is the top language they'd
+see section _Attitudes towards Go_ below) Go is the top language they'd
prefer to use for these non-work-related projects.
.image survey2018/fig4.svg _ 600
@@ -98,31 +99,31 @@
language as their most preferred/understood (the darkest blue bars),
which highlights three interesting bits:
-- While about ⅓ of respondents consider Go to be the language in which
- they have the most expertise,
- twice that many respondents consider it their most preferred programming language.
- So even though many respondents feel they haven't become as proficient with
- Go as with some other language,
- they still frequently prefer to develop with Go.
-- Few survey respondents rank Rust as a language in which they have expertise (6.8%),
- yet 19% rank it as a top preferred language,
- indicating a high level of interest in Rust among this audience.
-- Only three languages have more respondents who say they prefer the language
- than say they have expertise with it:
- Rust (2.41:1 ratio of preference:expertise),
- Kotlin (1.95:1), and Go (1.02:1).
- Higher preference than expertise implies interest—but little direct experience—in a language,
- while lower preference than expertise numbers suggests barriers to proficient use.
- Ratios near 1.0 suggest that most developers are able to work effectively
- _and_ enjoyably with a given language.
- This data is corroborated by [[https://insights.stackoverflow.com/survey/2018/#most-loved-dreaded-and-wanted][Stack Overflow's 2018 developer survey]],
- which also found Rust, Kotlin, and Go to be among the most-preferred programming languages.
+ - While about ⅓ of respondents consider Go to be the language in which
+ they have the most expertise,
+ twice that many respondents consider it their most preferred programming language.
+ So even though many respondents feel they haven't become as proficient with
+ Go as with some other language,
+ they still frequently prefer to develop with Go.
+ - Few survey respondents rank Rust as a language in which they have expertise (6.8%),
+ yet 19% rank it as a top preferred language,
+ indicating a high level of interest in Rust among this audience.
+ - Only three languages have more respondents who say they prefer the language
+ than say they have expertise with it:
+ Rust (2.41:1 ratio of preference:expertise),
+ Kotlin (1.95:1), and Go (1.02:1).
+ Higher preference than expertise implies interest—but little direct experience—in a language,
+ while lower preference than expertise numbers suggests barriers to proficient use.
+ Ratios near 1.0 suggest that most developers are able to work effectively
+ _and_ enjoyably with a given language.
+ This data is corroborated by [Stack Overflow's 2018 developer survey](https://insights.stackoverflow.com/survey/2018/#most-loved-dreaded-and-wanted),
+ which also found Rust, Kotlin, and Go to be among the most-preferred programming languages.
.image survey2018/fig6.svg _ 600
.image survey2018/fig7.svg _ 600
.html survey2018/reading.html
-* Development domains
+## Development domains
Survey respondents reported working on a median of three different domains,
with a large majority (72%) working in 2-5 different areas.
@@ -156,10 +157,10 @@
To better understand the contexts in which developers are using Go,
we added a question about Go adoption across different industries.
Perhaps unsurprisingly for a relatively new language,
-over half of survey respondents work in companies in the _Internet/web_services_
+over half of survey respondents work in companies in the _Internet/web services_
and _Software_ categories (i.e., tech companies).
-The only other industries with >3% responses were _Finance,_banking,_or_insurance_
-and _Media,_advertising,_publishing,_or_entertainment_.
+The only other industries with >3% responses were _Finance, banking, or insurance_
+and _Media, advertising, publishing, or entertainment_.
(In the chart below, we've condensed all of the categories with response
rates below 3% into the "Other" category.) We'll continue tracking Go's
adoption across industries to better understand developer needs outside
@@ -167,10 +168,10 @@
.image survey2018/fig10.svg _ 600
-* Attitudes towards Go
+## Attitudes towards Go
This year we added a question asking "How likely are you to recommend Go
-to a friend or colleague?" to calculate our [[https://en.wikipedia.org/wiki/Net_Promoter][Net Promoter Score]].
+to a friend or colleague?" to calculate our [Net Promoter Score](https://en.wikipedia.org/wiki/Net_Promoter).
This score attempts to measure how many more "promoters" a product has than
"detractors" and ranges from -100 to 100;
a positive value suggests most people are likely to recommend using a product,
@@ -189,8 +190,8 @@
while a plurality feel that Go is at least somewhat critical to their company's success (44%).
While all of these metrics showed an increase in 2017,
they remained mostly stable this year.
-(The wording of the first question changed in 2018 from "_I_would_recommend_using_Go_to_others_"
-to "_Overall,_I'm_happy_with_Go_",
+(The wording of the first question changed in 2018 from "_I would recommend using Go to others_"
+to "_Overall, I'm happy with Go_",
so those results are not directly comparable.)
.image survey2018/fig12.svg _ 600
@@ -209,16 +210,16 @@
counting the number of responses that supported each theme.
The top three major challenges we identified are:
-- Package management (e.g., "Keeping up with vendoring",
- "dependency / packet [sic] management / vendoring not unified")
-- Differences from more familiar programming languages (e.g.,
- "syntax close to C-languages with slightly different semantics makes me
- look up references somewhat more than I'd like",
- "coworkers who come from non-Go backgrounds trying to use Go as a version
- of their previous language but with channels and Goroutines")
-- Lack of generics (e.g., "Lack of generics makes it difficult to persuade
- people who have not tried Go that they would find it efficient.",
- "Hard to build richer abstractions (want generics)")
+ - Package management (e.g., "Keeping up with vendoring",
+ "dependency / packet [sic] management / vendoring not unified")
+ - Differences from more familiar programming languages (e.g.,
+ "syntax close to C-languages with slightly different semantics makes me
+ look up references somewhat more than I'd like",
+ "coworkers who come from non-Go backgrounds trying to use Go as a version
+ of their previous language but with channels and Goroutines")
+ - Lack of generics (e.g., "Lack of generics makes it difficult to persuade
+ people who have not tried Go that they would find it efficient.",
+ "Hard to build richer abstractions (want generics)")
.image survey2018/fig13.svg _ 600
.image survey2018/fig14.svg _ 600
@@ -252,7 +253,7 @@
.image survey2018/fig15.svg _ 600
.image survey2018/fig29.svg _ 600
-* Development environments
+## Development environments
We asked respondents which operating systems they primarily use when writing Go code.
A majority (65%) of respondents said they use Linux,
@@ -282,10 +283,10 @@
Like the "biggest challenge" question above,
participants could write in their own response rather than select from a
multiple-choice list.
-A thematic analysis on the responses revealed that _improved_debugging_support_ (e.g.,
+A thematic analysis on the responses revealed that _improved debugging support_ (e.g.,
"Live debugging", "Integrated debugging",
"Even better debugging") was the most-common request,
-followed by _improved_code_completion_ (e.g.,
+followed by _improved code completion_ (e.g.,
"autocomplete performance and quality", "smarter autocomplete").
Other requests include better integration with Go's CLI toolchain,
better support for modules/packages, and general performance improvements.
@@ -306,7 +307,7 @@
.image survey2018/fig19.svg _ 600
-* Deployments and services
+## Deployments and services
For 2018 we see a continuation of the trend from on-prem to cloud hosting
for both Go and non-Go deployments.
@@ -338,7 +339,7 @@
.image survey2018/fig21.svg _ 600
-* Go community
+## Go community
The top community sources for finding answers to Go questions continue to
be Stack Overflow (23% of respondents marked it as their top source),
@@ -377,7 +378,7 @@
For 2018, we saw a similar percentage of respondents (12%) identify as part
of an under-represented group,
and this was paired with a significant decrease in the percentage of respondents
-who do *not* identify as part of an under-represented group.
+who do **not** identify as part of an under-represented group.
In 2017, for every person who identified as part of an under-represented group,
3.5 people identified as not part of an under-represented group (3.5:1 ratio).
In 2018 that ratio improved to 3.08:1. This suggests that the Go community
@@ -406,15 +407,15 @@
"What changes would make the Go community more welcoming?".
Respondents' comments can be broadly grouped into four categories:
-- Reduce a perception of elitism, especially for newcomers to Go (e.g.,
- "less dismissiveness", "Less defensiveness and hubris")
-- Increase transparency at the leadership level (e.g.,
- "Future direction and planning discussions",
- "Less top down leadership", "More democratic")
-- Increase introductory resources (e.g., "A more clear introduction for contributors",
- "Fun challenges to learn best practices")
-- More events and meetups, with a focus on covering a larger geographic area (e.g.,
- "More meetups & social events", "Events in more cities")
+ - Reduce a perception of elitism, especially for newcomers to Go (e.g.,
+ "less dismissiveness", "Less defensiveness and hubris")
+ - Increase transparency at the leadership level (e.g.,
+ "Future direction and planning discussions",
+ "Less top down leadership", "More democratic")
+ - Increase introductory resources (e.g., "A more clear introduction for contributors",
+ "Fun challenges to learn best practices")
+ - More events and meetups, with a focus on covering a larger geographic area (e.g.,
+ "More meetups & social events", "Events in more cities")
This feedback is very helpful and gives us concrete areas we can focus on
to improve the experience of being a Go developer.
@@ -424,7 +425,7 @@
.image survey2018/fig22.svg _ 600
.image survey2018/fig23.svg _ 600
-* Conclusion
+## Conclusion
We hope you've enjoyed seeing the results of our 2018 developer survey.
These results are impacting our 2019 planning,
diff --git a/content/survey2018.article b/content/survey2018.article
index 2ef3189..2085f82 100644
--- a/content/survey2018.article
+++ b/content/survey2018.article
@@ -1,31 +1,32 @@
-Participate in the 2018 Go User Survey
+# Participate in the 2018 Go User Survey
8 Nov 2018
Tags: survey, community
+Summary: In [2017](https://blog.golang.org/survey2017-results) & [2016](https://blog.golang.org/survey2016-results), thousands of you helped the project by lending your voice via the Go user survey. In October, hundreds of companies helped us understand how enterprises are using Go by taking the Go company questionnaire. These surveys and questionnaires have played an enormous role in driving changes to our language and community, from [our new code of conduct](https://blog.golang.org/conduct-2018), to our [latest release Go 1.11](https://blog.golang.org/go1.11).
Ran Tao, Steve Francia
spf@golang.org
-* The Go project wants to hear from you, the Go community!
+## The Go project wants to hear from you, the Go community!
-In [[https://blog.golang.org/survey2017-results][2017]] &
-[[https://blog.golang.org/survey2016-results][2016]], thousands of you helped the
+In [2017](https://blog.golang.org/survey2017-results) &
+[2016](https://blog.golang.org/survey2016-results), thousands of you helped the
project by lending your voice via the Go user survey. In October, hundreds of
companies helped us understand how enterprises are using Go by taking the Go company
questionnaire. These surveys and questionnaires have played an enormous role in
driving changes to our language and community, from
-[[https://blog.golang.org/conduct-2018][our new code of conduct]], to our
-[[https://blog.golang.org/go1.11][latest release Go 1.11]].
+[our new code of conduct](https://blog.golang.org/conduct-2018), to our
+[latest release Go 1.11](https://blog.golang.org/go1.11).
-Today we are conducting the 2018 Go user survey. We’d like to hear from *all* Go
+Today we are conducting the 2018 Go user survey. We’d like to hear from **all** Go
users in order to help us to create the best programming language that fits the
needs and desires of the people closest to it. Please help us shape the future of Go
by participating in the 15-minute 2018 Go user survey by November 30th:
-[[https://goo.gl/8Vzquh][*Go*User*Survey*2018*]].
+[**Go User Survey 2018**](https://goo.gl/8Vzquh).
-This survey is _confidential_and_anonymous_. For more information,
-please refer to Google’s privacy policy [[https://policies.google.com/privacy][here]].
+This survey is _confidential and anonymous_. For more information,
+please refer to Google’s privacy policy [here](https://policies.google.com/privacy).
-* Spread the word!
+## Spread the word!
We need as many Gophers as possible to participate in this survey to help us better
understand our global user base. We’d be grateful if you would spread the word by
diff --git a/content/survey2019.article b/content/survey2019.article
index 1d8ef4a..243bbec 100644
--- a/content/survey2019.article
+++ b/content/survey2019.article
@@ -1,21 +1,22 @@
-Announcing the 2019 Go Developer Survey
+# Announcing the 2019 Go Developer Survey
20 Nov 2019
Tags: survey, community
+Summary: Since 2016, thousands of Gophers around the world have helped the Go project by sharing your thoughts via our annual Go Developer Survey. Your feedback has played an enormous role in driving changes to our language, ecosystem, and community, including [the gopls language server](https://about.sourcegraph.com/go/gophercon-2019-go-pls-stop-breaking-my-editor), new [error-handling mechanics](https://blog.golang.org/go1.13-errors), the [module mirror](https://blog.golang.org/module-mirror-launch), and so much more from the latest [Go 1.13 release](https://blog.golang.org/go1.13). And of course, we publicly share [each](https://blog.golang.org/survey2016-results) [year's](https://blog.golang.org/survey2017-results) [results](https://blog.golang.org/survey2018-results), so we can all benefit from the community's insights.
Todd Kulesza
tkulesza@google.com
-* Help shape the future of Go
+## Help shape the future of Go
Since 2016, thousands of Gophers around the world have helped the Go project
by sharing your thoughts via our annual Go Developer Survey.
Your feedback has played an enormous role in driving changes to our language,
-ecosystem, and community, including [[https://about.sourcegraph.com/go/gophercon-2019-go-pls-stop-breaking-my-editor][the gopls language server]],
-new [[https://blog.golang.org/go1.13-errors][error-handling mechanics]],
-the [[https://blog.golang.org/module-mirror-launch][module mirror]],
-and so much more from the latest [[https://blog.golang.org/go1.13][Go 1.13 release]].
-And of course, we publicly share [[https://blog.golang.org/survey2016-results][each]]
-[[https://blog.golang.org/survey2017-results][year's]] [[https://blog.golang.org/survey2018-results][results]],
+ecosystem, and community, including [the gopls language server](https://about.sourcegraph.com/go/gophercon-2019-go-pls-stop-breaking-my-editor),
+new [error-handling mechanics](https://blog.golang.org/go1.13-errors),
+the [module mirror](https://blog.golang.org/module-mirror-launch),
+and so much more from the latest [Go 1.13 release](https://blog.golang.org/go1.13).
+And of course, we publicly share [each](https://blog.golang.org/survey2016-results)
+[year's](https://blog.golang.org/survey2017-results) [results](https://blog.golang.org/survey2018-results),
so we can all benefit from the community's insights.
Today we are launching the 2019 Go Developer Survey.
@@ -24,9 +25,9 @@
to help ensure the language, community, and ecosystem fit the needs of the
people closest to it.
Please help us shape Go's future by participating in this 15-minute survey by December 15th:
-[[https://google.qualtrics.com/jfe/form/SV_b1xqnBCMpZAhJZ3][Take the 2019 Go Developer Survey]].
+[Take the 2019 Go Developer Survey](https://google.qualtrics.com/jfe/form/SV_b1xqnBCMpZAhJZ3).
-* Spread the word!
+## Spread the word!
We need as many Gophers as possible to participate in this survey to help
us better understand our global user base.
diff --git a/content/the-app-engine-sdk-and-workspaces-gopath.article b/content/the-app-engine-sdk-and-workspaces-gopath.article
index 73ae7d9..df53b35 100644
--- a/content/the-app-engine-sdk-and-workspaces-gopath.article
+++ b/content/the-app-engine-sdk-and-workspaces-gopath.article
@@ -1,27 +1,28 @@
-The App Engine SDK and workspaces (GOPATH)
+# The App Engine SDK and workspaces (GOPATH)
9 Jan 2013
Tags: appengine, tools, gopath
+Summary: When we released Go 1 we introduced the [go tool](https://golang.org/cmd/go/) and, with it, the concept of workspaces. Workspaces (specified by the GOPATH environment variable) are a convention for organizing code that simplifies fetching, building, and installing Go packages. If you're not familiar with workspaces, please read [this article](https://golang.org/doc/code.html) or watch [this screencast](http://www.youtube.com/watch?v=XCsL89YtqCs) before reading on.
Andrew Gerrand
-* Introduction
+## Introduction
-When we released Go 1 we introduced the [[https://golang.org/cmd/go/][go tool]] and,
+When we released Go 1 we introduced the [go tool](https://golang.org/cmd/go/) and,
with it, the concept of workspaces.
Workspaces (specified by the GOPATH environment variable) are a convention
for organizing code that simplifies fetching,
building, and installing Go packages.
-If you're not familiar with workspaces, please read [[https://golang.org/doc/code.html][this article]]
-or watch [[http://www.youtube.com/watch?v=XCsL89YtqCs][this screencast]] before reading on.
+If you're not familiar with workspaces, please read [this article](https://golang.org/doc/code.html)
+or watch [this screencast](http://www.youtube.com/watch?v=XCsL89YtqCs) before reading on.
Until recently, the tools in the App Engine SDK were not aware of workspaces.
-Without workspaces the "[[https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies][go get]]"
+Without workspaces the "[go get](https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies)"
command cannot function,
and so app authors had to install and update their app dependencies manually. It was a pain.
This has all changed with version 1.7.4 of the App Engine SDK.
-The [[https://developers.google.com/appengine/docs/go/tools/devserver][dev_appserver]]
-and [[https://developers.google.com/appengine/docs/go/tools/uploadinganapp][appcfg]]
+The [dev\_appserver](https://developers.google.com/appengine/docs/go/tools/devserver)
+and [appcfg](https://developers.google.com/appengine/docs/go/tools/uploadinganapp)
tools are now workspace-aware.
When running locally or uploading an app,
these tools now search for dependencies in the workspaces specified by the
@@ -32,76 +33,76 @@
For example, let's say you want to build an app that uses OAuth 2.0 to authenticate
with a remote service.
-A popular OAuth 2.0 library for Go is the [[https://godoc.org/golang.org/x/oauth2][oauth2]] package,
+A popular OAuth 2.0 library for Go is the [oauth2](https://godoc.org/golang.org/x/oauth2) package,
which you can install to your workspace with this command:
- go get golang.org/x/oauth2
+ go get golang.org/x/oauth2
When writing your App Engine app, import the oauth package just as you would in a regular Go program:
- import "golang.org/x/oauth2"
+ import "golang.org/x/oauth2"
-Now, whether running your app with the dev_appserver or deploying it with appcfg,
+Now, whether running your app with the dev\_appserver or deploying it with appcfg,
the tools will find the oauth package in your workspace. It just works.
-* Hybrid stand-alone/App Engine apps
+## Hybrid stand-alone/App Engine apps
-The Go App Engine SDK builds on Go's standard [[https://golang.org/pkg/net/http/][net/http]]
+The Go App Engine SDK builds on Go's standard [net/http](https://golang.org/pkg/net/http/)
package to serve web requests and,
as a result, many Go web servers can be run on App Engine with only a few changes.
-For example, [[https://golang.org/cmd/godoc/][godoc]] is included in the
+For example, [godoc](https://golang.org/cmd/godoc/) is included in the
Go distribution as a stand-alone program,
-but it can also run as an App Engine app (godoc serves [[https://golang.org/][golang.org]] from App Engine).
+but it can also run as an App Engine app (godoc serves [golang.org](https://golang.org/) from App Engine).
But wouldn't it be nice if you could write a program that is both a stand-alone
-web server and an App Engine app? By using [[https://golang.org/pkg/go/build/#hdr-Build_Constraints][build constraints]], you can.
+web server and an App Engine app? By using [build constraints](https://golang.org/pkg/go/build/#hdr-Build_Constraints), you can.
Build constraints are line comments that determine whether a file should
be included in a package.
They are most often used in code that handles a variety of operating systems
or processor architectures.
-For instance, the [[https://golang.org/pkg/path/filepath/][path/filepath]]
-package includes the file [[https://golang.org/src/pkg/path/filepath/symlink.go][symlink.go]],
+For instance, the [path/filepath](https://golang.org/pkg/path/filepath/)
+package includes the file [symlink.go](https://golang.org/src/pkg/path/filepath/symlink.go),
which specifies a build constraint to ensure that it is not built on Windows
systems (which do not have symbolic links):
- // +build !windows
+ // +build !windows
The App Engine SDK introduces a new build constraint term: "appengine". Files that specify
- // +build appengine
+ // +build appengine
will be built by the App Engine SDK and ignored by the go tool. Conversely, files that specify
- // +build !appengine
+ // +build !appengine
are ignored by the App Engine SDK, while the go tool will happily build them.
-The [[http://code.google.com/p/goprotobuf/][goprotobuf]] library uses this
+The [goprotobuf](http://code.google.com/p/goprotobuf/) library uses this
mechanism to provide two implementations of a key part of its encode/decode machinery:
-[[http://code.google.com/p/goprotobuf/source/browse/proto/pointer_unsafe.go][pointer_unsafe.go]]
+[pointer\_unsafe.go](http://code.google.com/p/goprotobuf/source/browse/proto/pointer_unsafe.go)
is the faster version that cannot be used on App Engine because it uses
-the [[https://golang.org/pkg/unsafe/][unsafe package]],
-while [[http://code.google.com/p/goprotobuf/source/browse/proto/pointer_reflect.go][pointer_reflect.go]]
-is a slower version that avoids unsafe by using the [[https://golang.org/pkg/reflect/][reflect package]] instead.
+the [unsafe package](https://golang.org/pkg/unsafe/),
+while [pointer\_reflect.go](http://code.google.com/p/goprotobuf/source/browse/proto/pointer_reflect.go)
+is a slower version that avoids unsafe by using the [reflect package](https://golang.org/pkg/reflect/) instead.
Let's take a simple Go web server and turn it into a hybrid app. This is main.go:
- package main
+ package main
- import (
- "fmt"
- "net/http"
- )
+ import (
+ "fmt"
+ "net/http"
+ )
- func main() {
- http.HandleFunc("/", handler)
- http.ListenAndServe("localhost:8080", nil)
- }
+ func main() {
+ http.HandleFunc("/", handler)
+ http.ListenAndServe("localhost:8080", nil)
+ }
- func handler(w http.ResponseWriter, r *http.Request) {
- fmt.Fprint(w, "Hello!")
- }
+ func handler(w http.ResponseWriter, r *http.Request) {
+ fmt.Fprint(w, "Hello!")
+ }
Build this with the go tool and you'll get a stand-alone web server executable.
@@ -110,20 +111,20 @@
To convert main.go to an App Engine app, drop the call to ListenAndServe
and register the handler in an init function (which runs before main). This is app.go:
- package main
+ package main
- import (
- "fmt"
- "net/http"
- )
+ import (
+ "fmt"
+ "net/http"
+ )
- func init() {
- http.HandleFunc("/", handler)
- }
+ func init() {
+ http.HandleFunc("/", handler)
+ }
- func handler(w http.ResponseWriter, r *http.Request) {
- fmt.Fprint(w, "Hello!")
- }
+ func handler(w http.ResponseWriter, r *http.Request) {
+ fmt.Fprint(w, "Hello!")
+ }
To make this a hybrid app, we need to split it into an App Engine-specific part,
an stand-alone binary-specific part, and the parts common to both versions.
@@ -137,19 +138,19 @@
main.go runs the web server. It includes the "!appengine" build constraint,
as it must only included when building the stand-alone binary.
- // +build !appengine
+ // +build !appengine
- package main
+ package main
- import "net/http"
+ import "net/http"
- func main() {
- http.ListenAndServe("localhost:8080", nil)
- }
+ func main() {
+ http.ListenAndServe("localhost:8080", nil)
+ }
-To see a more complex hybrid app, take a look at the [[https://godoc.org/golang.org/x/tools/present][present tool]].
+To see a more complex hybrid app, take a look at the [present tool](https://godoc.org/golang.org/x/tools/present).
-* Conclusions
+## Conclusions
We hope these changes will make it easier to work on apps with external dependencies,
and to maintain code bases that contain both stand-alone programs and App Engine apps.
diff --git a/content/the-path-to-go-1.article b/content/the-path-to-go-1.article
index 1bb1f5f..15eb3ee 100644
--- a/content/the-path-to-go-1.article
+++ b/content/the-path-to-go-1.article
@@ -1,12 +1,13 @@
-The path to Go 1
+# The path to Go 1
14 Mar 2013
Tags: talk, video, go1
+Summary: In July 2012, Rob Pike and I presented a talk at OSCON titled _The path to Go 1_. In it we explain how Go 1 came to be, and outline the process by which Go was refined and stabilized to become the clean, consistent programming environment that it is today. We present the major highlights of the release and discuss the details behind some specific libraries and tools.
Andrew Gerrand
-* Introduction
+##
-In July 2012, Rob Pike and I presented a talk at OSCON titled _The_path_to_Go_1_.
+In July 2012, Rob Pike and I presented a talk at OSCON titled _The path to Go 1_.
In it we explain how Go 1 came to be, and outline the process by which Go
was refined and stabilized to become the clean,
consistent programming environment that it is today.
@@ -15,7 +16,7 @@
.iframe //www.youtube.com/embed/bj9T2c2Xk_s 309 550
-The slides for the talk are [[https://talks.golang.org/2012/go1.slide][available here]].
+The slides for the talk are [available here](https://talks.golang.org/2012/go1.slide).
It's almost a year since we cut Go 1.0 and we are now busy preparing Go 1.1.
The release will include performance improvements to the gc compiler,
diff --git a/content/third-party-libraries-goprotobuf-and.article b/content/third-party-libraries-goprotobuf-and.article
index b356e81..e58c132 100644
--- a/content/third-party-libraries-goprotobuf-and.article
+++ b/content/third-party-libraries-goprotobuf-and.article
@@ -1,13 +1,14 @@
-Third-party libraries: goprotobuf and beyond
+# Third-party libraries: goprotobuf and beyond
20 Apr 2010
Tags: protobuf, community
+Summary: On March 24, Rob Pike announced [goprotobuf](http://code.google.com/p/goprotobuf/), the Go bindings of Google's data interchange format [Protocol Buffers](http://code.google.com/apis/protocolbuffers/docs/overview.html), called protobufs for short. With this announcement, Go joins C++, Java, and Python as languages providing official protobuf implementations. This marks an important milestone in enabling the interoperability between existing systems and those built in Go.
Andrew Gerrand
-* Introduction
+##
-On March 24, Rob Pike announced [[http://code.google.com/p/goprotobuf/][goprotobuf]],
-the Go bindings of Google's data interchange format [[http://code.google.com/apis/protocolbuffers/docs/overview.html][Protocol Buffers]],
+On March 24, Rob Pike announced [goprotobuf](http://code.google.com/p/goprotobuf/),
+the Go bindings of Google's data interchange format [Protocol Buffers](http://code.google.com/apis/protocolbuffers/docs/overview.html),
called protobufs for short.
With this announcement, Go joins C++, Java,
and Python as languages providing official protobuf implementations.
@@ -20,27 +21,27 @@
and a Go package that implements run-time support for encoding (marshaling),
decoding (unmarshaling), and accessing protocol buffers.
-To use goprotobuf, you first need to have both Go and [[http://code.google.com/p/protobuf/][protobuf]] installed.
-You can then install the 'proto' package with [[https://golang.org/cmd/goinstall/][goinstall]]:
+To use goprotobuf, you first need to have both Go and [protobuf](http://code.google.com/p/protobuf/) installed.
+You can then install the 'proto' package with [goinstall](https://golang.org/cmd/goinstall/):
goinstall goprotobuf.googlecode.com/hg/proto
And then install the protobuf compiler plugin:
- cd $GOROOT/src/pkg/goprotobuf.googlecode.com/hg/compiler
- make install
+ cd $GOROOT/src/pkg/goprotobuf.googlecode.com/hg/compiler
+ make install
-For more detail see the project's [[http://code.google.com/p/goprotobuf/source/browse/README][README]] file.
+For more detail see the project's [README](http://code.google.com/p/goprotobuf/source/browse/README) file.
-This is one of a growing list of third-party [[http://godashboard.appspot.com/package][Go projects]].
+This is one of a growing list of third-party [Go projects](http://godashboard.appspot.com/package).
Since the announcement of goprotobuf, the X Go bindings have been spun off
-from the standard library to the [[http://code.google.com/p/x-go-binding/][x-go-binding]] project,
-and work has begun on a [[http://www.freetype.org/][Freetype]] port,
-[[http://code.google.com/p/freetype-go/][freetype-go]].
+from the standard library to the [x-go-binding](http://code.google.com/p/x-go-binding/) project,
+and work has begun on a [Freetype](http://www.freetype.org/) port,
+[freetype-go](http://code.google.com/p/freetype-go/).
Other popular third-party projects include the lightweight web framework
-[[http://github.com/hoisie/web.go][web.go]],
-and the Go GTK bindings [[http://github.com/mattn/go-gtk][gtk-go]].
+[web.go](http://github.com/hoisie/web.go),
+and the Go GTK bindings [gtk-go](http://github.com/mattn/go-gtk).
We wish to encourage the development of other useful packages by the open source community.
If you're working on something, don't keep it to yourself - let us know
-through our mailing list [[http://groups.google.com/group/golang-nuts][golang-nuts]].
+through our mailing list [golang-nuts](http://groups.google.com/group/golang-nuts).
diff --git a/content/toward-go2.article b/content/toward-go2.article
index 584883e..c097242 100644
--- a/content/toward-go2.article
+++ b/content/toward-go2.article
@@ -1,13 +1,14 @@
-Toward Go 2
+# Toward Go 2
13 Jul 2017
Tags: community
+Summary: [This is the text of [my talk today](https://www.youtube.com/watch?v=0Zbh_vmAKvk) at Gophercon 2017, asking for the entire Go community's help as we discuss and plan Go 2.]
Russ Cox
-* Introduction
+## Introduction
[This is the text of
-[[https://www.youtube.com/watch?v=0Zbh_vmAKvk][my talk today]]
+[my talk today](https://www.youtube.com/watch?v=0Zbh_vmAKvk)
at Gophercon 2017, asking for the entire Go community's
help as we discuss and plan Go 2.]
@@ -21,7 +22,7 @@
The next year, Ian Lance Taylor and I joined the team, and together
the five of us built two compilers and a standard library, leading up
-to the [[https://opensource.googleblog.com/2009/11/hey-ho-lets-go.html][open-source release]] on November 10, 2009.
+to the [open-source release](https://opensource.googleblog.com/2009/11/hey-ho-lets-go.html) on November 10, 2009.
.html toward-go2/div-indent.html
.image toward-go2/tweet.png _ 467
@@ -29,14 +30,14 @@
For the next two years, with the help of the new Go open source
community, we experimented with changes large and small, refining Go
-and leading to the [[https://blog.golang.org/preview-of-go-version-1][plan for Go 1]], proposed on October 5, 2011.
+and leading to the [plan for Go 1](https://blog.golang.org/preview-of-go-version-1), proposed on October 5, 2011.
.html toward-go2/div-indent.html
.image toward-go2/go1-preview.png _ 560
.html toward-go2/div-end.html
With more help from the Go community, we revised and implemented that
-plan, eventually [[https://blog.golang.org/go-version-1-is-released][releasing Go 1]] on March 28, 2012.
+plan, eventually [releasing Go 1](https://blog.golang.org/go-version-1-is-released) on March 28, 2012.
.html toward-go2/div-indent.html
.image toward-go2/go1-release.png _ 556
@@ -51,7 +52,7 @@
programs nearly every week. We understood that this was keeping Go
from use in production settings, where programs could not be rewritten
weekly to keep up with language changes.
-As the [[https://blog.golang.org/go-version-1-is-released][blog post announcing Go 1]] says, the driving motivation was to provide a stable foundation
+As the [blog post announcing Go 1](https://blog.golang.org/go-version-1-is-released) says, the driving motivation was to provide a stable foundation
for creating reliable products, projects, and publications (blogs,
tutorials, conference talks, and books), to make users confident that
their programs would continue to compile and run without change for
@@ -63,7 +64,7 @@
own projects and improving the implementation: we ported Go to many
new systems, we rewrote nearly every performance-critical piece to
make Go run more efficiently, and we added key tools like the
-[[https://blog.golang.org/race-detector][race detector]].
+[race detector](https://blog.golang.org/race-detector).
Now we have five years of experience using Go to build large,
production-quality systems. We have developed a sense of what works
@@ -79,7 +80,7 @@
problems we might try to solve; the possible kinds of solutions; how
we will deliver Go 2; and how all of you can help.
-* Goals
+## Goals
The goals we have for Go today are the same as in 2007. We want to
make programmers more effective at managing two kinds of scale:
@@ -99,15 +100,15 @@
scale.
(For more about these goals, see
-Rob Pike's 2012 article “[[https://talks.golang.org/2012/splash.article][Go at Google: Language Design in the Service of Software Engineering]]”
-and my GopherCon 2015 talk “[[https://blog.golang.org/open-source][Go, Open Source, Community]].”)
+Rob Pike's 2012 article “[Go at Google: Language Design in the Service of Software Engineering](https://talks.golang.org/2012/splash.article)”
+and my GopherCon 2015 talk “[Go, Open Source, Community](https://blog.golang.org/open-source).”)
-* Constraints
+## Constraints
The goals for Go have not changed since the beginning, but the
constraints on Go certainly have. The most important constraint is
existing Go usage. We estimate that there are at least
-[[https://research.swtch.com/gophercount][half a million Go developers worldwide]],
+[half a million Go developers worldwide](https://research.swtch.com/gophercount),
which means there are millions of Go source files and at
least a billion of lines of Go code. Those programmers and that source
code represent Go's success, but they are also the main constraint on
@@ -144,7 +145,7 @@
topics not yet suggested. We can do only a few of those major changes.
We will have to choose carefully.
-* Process
+## Process
That raises an important question. What is the process for developing
Go?
@@ -202,12 +203,12 @@
(For more about the development of Go 1 and the shift away from
language changes, see Rob Pike and Andrew Gerrand's
-OSCON 2012 talk “[[https://blog.golang.org/the-path-to-go-1][The Path to Go 1]].”
+OSCON 2012 talk “[The Path to Go 1](https://blog.golang.org/the-path-to-go-1).”
For more about the proposal process, see
-Andrew Gerrand's GopherCon 2015 talk “[[https://www.youtube.com/watch?v=0ht89TxZZnk][How Go was Made]]” and the
-[[https://golang.org/s/proposal][proposal process documentation]].)
+Andrew Gerrand's GopherCon 2015 talk “[How Go was Made](https://www.youtube.com/watch?v=0ht89TxZZnk)” and the
+[proposal process documentation](https://golang.org/s/proposal).)
-* Explaining Problems
+## Explaining Problems
.html toward-go2/div-indent.html
.image toward-go2/process2.png _ 410
@@ -263,7 +264,7 @@
want to look at two recent examples that show this clearly, at least
in hindsight.
-** Example: Leap seconds
+### Example: Leap seconds
My first example is about time.
@@ -279,7 +280,7 @@
elapsed := end.Sub(start) // 10 ms
-This obvious procedure can fail during a [[https://en.wikipedia.org/wiki/Leap_second][leap second]]. When our clocks
+This obvious procedure can fail during a [leap second](https://en.wikipedia.org/wiki/Leap_second). When our clocks
are not quite in sync with the daily rotation of the Earth, a leap
second—officially 11:59pm and 60 seconds—is inserted just before
midnight. Unlike leap years, leap seconds follow no predictable
@@ -307,7 +308,7 @@
benefit of being useful for telling time, so for simplicity Go 1’s
time APIs expose only the time-of-day clock.
-In October 2015, a [[https://golang.org/issue/12914][bug report]] noted that Go programs could not time
+In October 2015, a [bug report](https://golang.org/issue/12914) noted that Go programs could not time
events correctly across clock resets, especially a typical leap second.
The suggested fix was also the original issue title: “add a new API to access a
monotonic clock source.” I argued that this problem was not
@@ -315,7 +316,7 @@
mid-2015 leap second, Akamai, Amazon, and Google had slowed their
clocks a tiny amount for the entire day, absorbing the extra second
without turning their clocks backward. It seemed like eventual
-widespread adoption of this “[[https://developers.google.com/time/smear][leap smear]]” approach would eliminate
+widespread adoption of this “[leap smear](https://developers.google.com/time/smear)” approach would eliminate
leap-second clock resets as a problem on production systems. In
contrast, adding new API to Go would add new problems: we would have
to explain the two kinds of clocks, educate users about when to use
@@ -327,7 +328,7 @@
understanding of the problem and also more time to find a good
solution. In this case, waiting added to our understanding of the
significance of the problem, in the form of a thankfully
-[[https://www.theregister.co.uk/2017/01/04/cloudflare_trips_over_leap_second/][minor outage at Cloudflare]].
+[minor outage at Cloudflare](https://www.theregister.co.uk/2017/01/04/cloudflare_trips_over_leap_second/).
Their Go code timed DNS requests during the end-of-2016
leap second as taking around negative 990 milliseconds, which caused
simultaneous panics across their servers, breaking 0.2% of DNS queries
@@ -337,22 +338,22 @@
and they had a production outage based on Go not being able to time
events correctly. Then, and this is the key point, Cloudflare reported
their experience in a blog post by John Graham-Cumming titled
-“[[https://blog.cloudflare.com/how-and-why-the-leap-second-affected-cloudflare-dns/][How and why the leap second affected Cloudflare DNS]].” By sharing concrete
+“[How and why the leap second affected Cloudflare DNS](https://blog.cloudflare.com/how-and-why-the-leap-second-affected-cloudflare-dns/).” By sharing concrete
details of their experience with Go in production, John and Cloudflare helped us
understand that the problem of accurate timing across leap second
clock resets was too significant to leave unfixed. Two months after
that article was published, we had designed and implemented a solution
-that will [[https://beta.golang.org/doc/go1.9#monotonic-time][ship in Go 1.9]]
-(and in fact we did it with [[https://golang.org/design/12914-monotonic][no new API]]).
+that will [ship in Go 1.9](https://beta.golang.org/doc/go1.9#monotonic-time)
+(and in fact we did it with [no new API](https://golang.org/design/12914-monotonic)).
-** Example: Alias declarations
+### Example: Alias declarations
My second example is support for alias declarations in Go.
Over the past few years, Google has established a team focused on
large-scale code changes, meaning API migration and bug fixes applied
across our
-[[http://cacm.acm.org/magazines/2016/7/204032-why-google-stores-billions-of-lines-of-code-in-a-single-repository/pdf][codebase of millions of source files and billions of lines of code]]
+[codebase of millions of source files and billions of lines of code](http://cacm.acm.org/magazines/2016/7/204032-why-google-stores-billions-of-lines-of-code-in-a-single-repository/pdf)
written in C++, Go, Java, Python, and other languages. One
thing I've learned from that team's work is the importance, when
changing an API from using one name to another, of being able to
@@ -370,7 +371,7 @@
alias declarations, which are exactly the needed forwarding mechanism.
At this point, I felt very good about the way Go was evolving. We'd
talked about aliases since the early days of Go—in fact, the first
-spec draft has [[https://go.googlesource.com/go/+/18c5b488a3b2e218c0e0cf2a7d4820d9da93a554/doc/go_spec#1182][an example using alias declarations]]—but each time we'd
+spec draft has [an example using alias declarations](https://go.googlesource.com/go/+/18c5b488a3b2e218c0e0cf2a7d4820d9da93a554/doc/go_spec#1182)—but each time we'd
discussed aliases, and later type aliases, we had no clear use case
for them, so we left them out. Now we were proposing to add aliases
not because they were an elegant concept but because they solved a
@@ -378,8 +379,8 @@
software development. I hoped this would serve as a model for future
changes to Go.
-Later in the spring, Robert and Rob wrote [[https://golang.org/design/16339-alias-decls][a proposal]],
-and Robert presented it in a [[https://www.youtube.com/watch?v=t-w6MyI2qlU][Gophercon 2016 lightning talk]]. The next few months
+Later in the spring, Robert and Rob wrote [a proposal](https://golang.org/design/16339-alias-decls),
+and Robert presented it in a [Gophercon 2016 lightning talk](https://www.youtube.com/watch?v=t-w6MyI2qlU). The next few months
did not go smoothly, and they were definitely not a model for future
changes to Go. One of the many lessons we learned was the importance
of describing the significance of a problem.
@@ -398,16 +399,16 @@
convey to the broader Go community the significance of handling
gradual code migration and repair during large-scale changes.
-In the fall we started over. I gave a [[https://www.youtube.com/watch?v=h6Cw9iCDVcU][talk]] and wrote
-[[https://talks.golang.org/2016/refactor.article][an article presenting the problem]]
+In the fall we started over. I gave a [talk](https://www.youtube.com/watch?v=h6Cw9iCDVcU) and wrote
+[an article presenting the problem](https://talks.golang.org/2016/refactor.article)
using multiple concrete examples drawn from
open source codebases, showing how this problem arises everywhere, not
just inside Google. Now that more people understood the problem and
-could see its significance, we had a [[https://golang.org/issue/18130][productive discussion]] about what
-kind of solution would be best. The outcome is that [[https://golang.org/design/18130-type-alias][type aliases]] will
-be [[https://beta.golang.org/doc/go1.9#language][included in Go 1.9]] and will help Go scale to ever-larger codebases.
+could see its significance, we had a [productive discussion](https://golang.org/issue/18130) about what
+kind of solution would be best. The outcome is that [type aliases](https://golang.org/design/18130-type-alias) will
+be [included in Go 1.9](https://beta.golang.org/doc/go1.9#language) and will help Go scale to ever-larger codebases.
-** Experience reports
+### Experience reports
The lesson here is that it is difficult but essential to describe the
significance of a problem in a way that someone working in a different
@@ -416,8 +417,8 @@
significance of any problem we want to solve. The clearest way to do
that is by showing how the problem affects real programs and real
production systems, like in
-[[https://blog.cloudflare.com/how-and-why-the-leap-second-affected-cloudflare-dns/][Cloudflare's blog post]] and in
-[[https://talks.golang.org/2016/refactor.article][my refactoring article]].
+[Cloudflare's blog post](https://blog.cloudflare.com/how-and-why-the-leap-second-affected-cloudflare-dns/) and in
+[my refactoring article](https://talks.golang.org/2016/refactor.article).
Experience reports like these turn an abstract problem into a concrete
one and help us understand its significance. They also serve as test
@@ -450,14 +451,14 @@
experiences with Go. There are half a million of you, working in a
broad range of environments, and not that many of us.
Write a post on your own blog,
-or write a [[https://www.medium.com/][Medium]] post,
-or write a [[https://gist.github.com/][Github Gist]] (add a `.md` file extension for Markdown),
-or write a [[https://docs.google.com/][Google doc]],
+or write a [Medium](https://www.medium.com/) post,
+or write a [Github Gist](https://gist.github.com/) (add a `.md` file extension for Markdown),
+or write a [Google doc](https://docs.google.com/),
or use any other publishing mechanism you like.
After you've posted, please add the post to our new wiki page,
-[[https://golang.org/wiki/ExperienceReports][golang.org/wiki/ExperienceReports]].
+[golang.org/wiki/ExperienceReports](https://golang.org/wiki/ExperienceReports).
-* Solutions
+## Solutions
.html toward-go2/div-indent.html
.image toward-go2/process34.png _ 410
@@ -472,12 +473,12 @@
provide direct access to those results. In 2013, Robert proposed that
we might extend the idea of two-result (“comma-ok”) expressions to
basic arithmetic. For example, if x and y are, say, uint32 values,
-`lo,`hi`=`x`*`y`
+`lo, hi = x * y`
would return not only the usual low 32 bits but also the high 32 bits
of the product. This problem didn't seem particularly significant, so
-we [[https://golang.org/issue/6815][recorded the potential solution]] but didn't implement it. We waited.
+we [recorded the potential solution](https://golang.org/issue/6815) but didn't implement it. We waited.
-More recently, we designed for Go 1.9 a [[https://beta.golang.org/doc/go1.9#math-bits][math/bits package]] that
+More recently, we designed for Go 1.9 a [math/bits package](https://beta.golang.org/doc/go1.9#math-bits) that
contains various bit manipulation functions:
package bits // import "math/bits"
@@ -508,14 +509,14 @@
write or at least to compile a program with a data race. How to fit
that into a language like Go is still an open question in the
programming language world. Instead we added a tool to the main
-distribution and made it trivial to use: that tool, the [[https://blog.golang.org/race-detector][race detector]], has become
+distribution and made it trivial to use: that tool, the [race detector](https://blog.golang.org/race-detector), has become
an indispensible part of the Go experience. Here the best solution was
a runtime and tooling change, not a language change.
There will be language changes as well, of course, but not all
problems are best solved in the language.
-* Shipping Go 2
+## Shipping Go 2
.html toward-go2/div-indent.html
.image toward-go2/process5.png _ 410
@@ -523,10 +524,10 @@
Finally, how will we ship and deliver Go 2?
-I think the best plan would be to ship the [[https://golang.org/doc/go1compat][backwards-compatible parts]]
+I think the best plan would be to ship the [backwards-compatible parts](https://golang.org/doc/go1compat)
of Go 2 incrementally, feature by feature, as part of the Go 1 release
sequence. This has a few important properties. First, it keeps the Go
-1 releases on the [[https://golang.org/wiki/Go-Release-Cycle][usual schedule]], to continue the timely bug fixes and
+1 releases on the [usual schedule](https://golang.org/wiki/Go-Release-Cycle), to continue the timely bug fixes and
improvements that users now depend on. Second, it avoids splitting
development effort between Go 1 and Go 2. Third, it avoids divergence
between Go 1 and Go 2, to ease everyone's eventual migration. Fourth,
@@ -553,9 +554,9 @@
abandoning Go 1, and that in fact we will bring Go 1 along to the
greatest extent possible.
-* Help Wanted
+## Help Wanted
-*We*need*your*help.*
+**We need your help.**
The conversation for Go 2 starts today, and it's one that will happen
in the open, in public forums like the mailing list and the issue
@@ -564,7 +565,7 @@
Today, what we need most is experience reports. Please tell us how Go
is working for you, and more importantly not working for you. Write a
blog post, include real examples, concrete detail, and real
-experience. And link it on our [[https://golang.org/wiki/ExperienceReports][wiki page]].
+experience. And link it on our [wiki page](https://golang.org/wiki/ExperienceReports).
That's how we'll start talking about what we, the Go community,
might want to change about Go.
diff --git a/content/two-go-talks-lexical-scanning-in-go-and.article b/content/two-go-talks-lexical-scanning-in-go-and.article
index 2965af0..cf276b9 100644
--- a/content/two-go-talks-lexical-scanning-in-go-and.article
+++ b/content/two-go-talks-lexical-scanning-in-go-and.article
@@ -1,32 +1,33 @@
-Two Go Talks: "Lexical Scanning in Go" and "Cuddle: an App Engine Demo"
+# Two Go Talks: "Lexical Scanning in Go" and "Cuddle: an App Engine Demo"
1 Sep 2011
Tags: appengine, lexer, talk, video
+Summary: On Tuesday night Rob Pike and Andrew Gerrand each presented at the [Sydney Google Technology User Group](http://www.sydney-gtug.org/).
Andrew Gerrand
-* Introduction
+##
-On Tuesday night Rob Pike and Andrew Gerrand each presented at the [[http://www.sydney-gtug.org/][Sydney Google Technology User Group]].
+On Tuesday night Rob Pike and Andrew Gerrand each presented at the [Sydney Google Technology User Group](http://www.sydney-gtug.org/).
-Rob's talk, "[[http://www.youtube.com/watch?v=HxaD_trXwRE][Lexical Scanning in Go]]",
+Rob's talk, "[Lexical Scanning in Go](http://www.youtube.com/watch?v=HxaD_trXwRE)",
discusses the design of a particularly interesting and idiomatic piece of Go code,
-the lexer component of the new [[https://golang.org/pkg/exp/template/][template package.]]
+the lexer component of the new [template package.](https://golang.org/pkg/exp/template/)
.iframe //www.youtube.com/embed/HxaD_trXwRE 345 560
-The slides are [[http://cuddle.googlecode.com/hg/talk/lex.html][available here]].
-The new template package is available as [[https://golang.org/pkg/exp/template/][exp/template]] in Go release r59.
+The slides are [available here](http://cuddle.googlecode.com/hg/talk/lex.html).
+The new template package is available as [exp/template](https://golang.org/pkg/exp/template/) in Go release r59.
In a future release it will replace the old template package.
-Andrew's talk, "[[http://www.youtube.com/watch?v=HQtLRqqB-Kk][Cuddle: an App Engine Demo]]",
+Andrew's talk, "[Cuddle: an App Engine Demo](http://www.youtube.com/watch?v=HQtLRqqB-Kk)",
describes the construction of a simple real-time chat application that uses
-App Engine's [[http://code.google.com/appengine/docs/go/datastore/overview.html][Datastore]],
-[[http://code.google.com/appengine/docs/go/channel/overview.html][Channel]],
-and [[http://code.google.com/appengine/docs/go/datastore/memcache.html][Memcache]] APIs.
-It also includes a question and answer session that covers [[http://code.google.com/appengine/docs/go/gettingstarted/][Go for App Engine]]
+App Engine's [Datastore](http://code.google.com/appengine/docs/go/datastore/overview.html),
+[Channel](http://code.google.com/appengine/docs/go/channel/overview.html),
+and [Memcache](http://code.google.com/appengine/docs/go/datastore/memcache.html) APIs.
+It also includes a question and answer session that covers [Go for App Engine](http://code.google.com/appengine/docs/go/gettingstarted/)
and Go more generally.
.iframe //www.youtube.com/embed/HQtLRqqB-Kk 345 560
-The slides are [[http://cuddle.googlecode.com/hg/talk/index.html][available here]].
-The code is available at the [[http://code.google.com/p/cuddle/][cuddle Google Code project]].
+The slides are [available here](http://cuddle.googlecode.com/hg/talk/index.html).
+The code is available at the [cuddle Google Code project](http://code.google.com/p/cuddle/).
diff --git a/content/two-recent-go-articles.article b/content/two-recent-go-articles.article
index f6acc05..04ec33a 100644
--- a/content/two-recent-go-articles.article
+++ b/content/two-recent-go-articles.article
@@ -1,19 +1,20 @@
-Two recent Go articles
+# Two recent Go articles
6 Mar 2013
Tags: google, talk, ethos
+Summary: In today's blog post I'd like to highlight a couple of recent articles about Go.
Andrew Gerrand
-* Introduction
+## Introduction
In today's blog post I'd like to highlight a couple of recent articles about Go.
-* Go at Google
+## Go at Google
-In October last year, Rob Pike presented a keynote at the ACM [[http://splashcon.org/2012/][SPLASH]] conference in Tucson.
-The talk, titled [[https://talks.golang.org/2012/splash.slide][Go at Google]],
+In October last year, Rob Pike presented a keynote at the ACM [SPLASH](http://splashcon.org/2012/) conference in Tucson.
+The talk, titled [Go at Google](https://talks.golang.org/2012/splash.slide),
was a comprehensive discussion of the motivations behind Go.
-Rob later expanded on his talk to produce an essay titled [[http://talks.golang.org/2012/splash.article][Go at Google: Language Design in the Service of Software Engineering]].
+Rob later expanded on his talk to produce an essay titled [Go at Google: Language Design in the Service of Software Engineering](http://talks.golang.org/2012/splash.article).
Here is the abstract:
The Go programming language was conceived in late 2007 as an
@@ -44,17 +45,17 @@
Examples and explanations will be taken from the real-world problems faced at Google.
If you have wondered about the design decisions behind Go,
-you may find your questions answered by [[https://talks.golang.org/2012/splash.article][the essay]].
+you may find your questions answered by [the essay](https://talks.golang.org/2012/splash.article).
It is recommended reading for both new and experienced Go programmers.
-* Go at the Google Developers Academy
+## Go at the Google Developers Academy
-At Google I/O 2012 the Google Developers team [[http://googledevelopers.blogspot.com.au/2012/06/google-launches-new-developer-education.html][launched]] the [[https://developers.google.com/academy/][Google Developers Academy]],
+At Google I/O 2012 the Google Developers team [launched](http://googledevelopers.blogspot.com.au/2012/06/google-launches-new-developer-education.html) the [Google Developers Academy](https://developers.google.com/academy/),
a program that provides training materials on Google technologies.
Go is one of those technologies and we're pleased to announce the first
GDA article featuring Go front and center:
-[[https://developers.google.com/appengine/training/go-plus-appengine/][Getting Started with Go, App Engine and Google+ API]] is
+[Getting Started with Go, App Engine and Google+ API](https://developers.google.com/appengine/training/go-plus-appengine/) is
an introduction to writing web applications in Go.
It demonstrates how to build and deploy App Engine applications and make
calls to the Google+ API using the Google APIs Go Client.
diff --git a/content/two-recent-go-talks.article b/content/two-recent-go-talks.article
index 0ae7120..80de1e2 100644
--- a/content/two-recent-go-talks.article
+++ b/content/two-recent-go-talks.article
@@ -1,20 +1,21 @@
-Two recent Go talks
+# Two recent Go talks
2 Jan 2013
Tags: talk, video, ethos
+Summary: Late last year I wrote a couple of Go talks and presented them at [Strange Loop](http://thestrangeloop.com/), [Øredev](http://oredev.com), and various other venues. The talks are designed to give insight into the practice of Go programming, each describing the construction of a real program and demonstrating the power and depth of the Go language and its libraries and tools.
Andrew Gerrand
-* Introduction
+## Introduction
-Late last year I wrote a couple of Go talks and presented them at [[http://thestrangeloop.com/][Strange Loop]],
-[[http://oredev.com][Øredev]], and various other venues.
+Late last year I wrote a couple of Go talks and presented them at [Strange Loop](http://thestrangeloop.com/),
+[Øredev](http://oredev.com), and various other venues.
The talks are designed to give insight into the practice of Go programming,
each describing the construction of a real program and demonstrating the
power and depth of the Go language and its libraries and tools.
The following videos are, in my opinion, the best recordings of these talks.
-* Go: a simple programming environment
+## Go: a simple programming environment
Go is a general-purpose language that bridges the gap between efficient
statically typed languages and productive dynamic language.
@@ -27,9 +28,9 @@
.iframe //player.vimeo.com/video/53221558?badge=0 281 500
-See the [[https://talks.golang.org/2012/simple.slide][slide deck]] (use the left and right arrows to navigate).
+See the [slide deck](https://talks.golang.org/2012/simple.slide) (use the left and right arrows to navigate).
-* Go: code that grows with grace
+## Go: code that grows with grace
One of Go's key design goals is code adaptability;
that it should be easy to take a simple design and build upon it in a clean and natural way.
@@ -42,4 +43,4 @@
.iframe //player.vimeo.com/video/53221560?badge=0 281 500
-See the [[https://talks.golang.org/2012/chat.slide][slide deck]] (use the left and right arrows to navigate).
+See the [slide deck](https://talks.golang.org/2012/chat.slide) (use the left and right arrows to navigate).
diff --git a/content/upcoming-google-io-go-events.article b/content/upcoming-google-io-go-events.article
index 472ea34..a206498 100644
--- a/content/upcoming-google-io-go-events.article
+++ b/content/upcoming-google-io-go-events.article
@@ -1,17 +1,18 @@
-Upcoming Google I/O Go Events
+# Upcoming Google I/O Go Events
12 May 2010
+Summary: [Google I/O 2010](https://googleblog.blogspot.com/2010/01/google-io-2010-now-open-for.html) is happening next week at the Moscone Centre in San Francisco. Those of you with tickets will be able to catch some of the Go team both at I/O and at Bootcamp. In reverse-chronological order:
Andrew Gerrand
-* Introduction
+##
-[[https://googleblog.blogspot.com/2010/01/google-io-2010-now-open-for.html][Google I/O 2010]]
+[Google I/O 2010](https://googleblog.blogspot.com/2010/01/google-io-2010-now-open-for.html)
is happening next week at the Moscone Centre in San Francisco.
Those of you with tickets will be able to catch some of the Go team both
at I/O and at Bootcamp.
In reverse-chronological order:
-Rob Pike and Russ Cox will be presenting a [[https://www.youtube.com/watch?v=jgVhBThJdXc][Go Programming]]
+Rob Pike and Russ Cox will be presenting a [Go Programming](https://www.youtube.com/watch?v=jgVhBThJdXc)
talk on Thursday at 10.15am.
This session takes a detailed look at how Go differs from other languages
in a practical sense.
diff --git a/content/using-go-modules.article b/content/using-go-modules.article
index 8d2774a..193e3ef 100644
--- a/content/using-go-modules.article
+++ b/content/using-go-modules.article
@@ -1,39 +1,40 @@
-Using Go Modules
+# Using Go Modules
19 Mar 2019
Tags: tools, versioning
+Summary: This post is part 1 in a series.
Tyler Bui-Palsulich
Eno Compton
-* Introduction
+## Introduction
This post is part 1 in a series.
-- *Part*1*—*Using*Go*Modules* (this post)
-- Part 2 — [[/migrating-to-go-modules][Migrating To Go Modules]]
-- Part 3 — [[/publishing-go-modules][Publishing Go Modules]]
-- Part 4 — [[/v2-go-modules][Go Modules: v2 and Beyond]]
+ - **Part 1 — Using Go Modules** (this post)
+ - Part 2 — [Migrating To Go Modules](/migrating-to-go-modules)
+ - Part 3 — [Publishing Go Modules](/publishing-go-modules)
+ - Part 4 — [Go Modules: v2 and Beyond](/v2-go-modules)
Go 1.11 and 1.12 include preliminary
-[[https://golang.org/doc/go1.11#modules][support for modules]],
+[support for modules](https://golang.org/doc/go1.11#modules),
Go’s
-[[https://blog.golang.org/versioning-proposal][new dependency management system]]
+[new dependency management system](https://blog.golang.org/versioning-proposal)
that makes dependency version information explicit
and easier to manage.
This blog post is an introduction to the basic operations needed
to get started using modules.
A module is a collection of
-[[https://golang.org/ref/spec#Packages][Go packages]]
+[Go packages](https://golang.org/ref/spec#Packages)
stored in a file tree with a `go.mod` file at its root.
-The `go.mod` file defines the module’s _module_path_,
+The `go.mod` file defines the module’s _module path_,
which is also the import path used for the root directory,
-and its _dependency_requirements_,
+and its _dependency requirements_,
which are the other modules needed for a successful build.
Each dependency requirement is
written as a module path and a specific
-[[http://semver.org/][semantic version]].
+[semantic version](http://semver.org/).
As of Go 1.11, the go command enables the use of modules
when the current directory or any parent directory has a `go.mod`,
@@ -41,21 +42,21 @@
(Inside `$GOPATH/src`, for compatibility, the go command
still runs in the old GOPATH mode, even if a `go.mod` is found.
See the
-[[https://golang.org/cmd/go/#hdr-Preliminary_module_support][go command documentation]]
+[go command documentation](https://golang.org/cmd/go/#hdr-Preliminary_module_support)
for details.)
Starting in Go 1.13, module mode will be the default for all development.
This post walks through a sequence of common operations
that arise when developing Go code with modules:
-- Creating a new module.
-- Adding a dependency.
-- Upgrading dependencies.
-- Adding a dependency on a new major version.
-- Upgrading a dependency to a new major version.
-- Removing unused dependencies.
+ - Creating a new module.
+ - Adding a dependency.
+ - Upgrading dependencies.
+ - Adding a dependency on a new major version.
+ - Upgrading a dependency to a new major version.
+ - Removing unused dependencies.
-* Creating a new module
+## Creating a new module
Let's create a new module.
@@ -83,7 +84,7 @@
At this point, the directory contains a package, but not a module,
because there is no `go.mod` file.
-If we were working in `/home/gopher/hello` and ran `go`test` now,
+If we were working in `/home/gopher/hello` and ran `go test` now,
we'd see:
$ go test
@@ -99,7 +100,7 @@
on the directory name: `_/home/gopher/hello`.
Let's make the current directory the root of a module
-by using `go`mod`init` and then try `go`test` again:
+by using `go mod init` and then try `go test` again:
$ go mod init example.com/hello
go: creating new go.mod: module example.com/hello
@@ -110,7 +111,7 @@
Congratulations! You’ve written and tested your first module.
-The `go`mod`init` command wrote a `go.mod` file:
+The `go mod init` command wrote a `go.mod` file:
$ cat go.mod
module example.com/hello
@@ -122,12 +123,12 @@
Packages in subdirectories have import paths consisting of
the module path plus the path to the subdirectory.
For example, if we created a subdirectory `world`,
-we would not need to (nor want to) run `go`mod`init` there.
+we would not need to (nor want to) run `go mod init` there.
The package would automatically be recognized as part of the
`example.com/hello` module, with import path
`example.com/hello/world`.
-* Adding a dependency
+## Adding a dependency
The primary motivation for Go modules was to improve the
experience of using (that is, adding a dependency on)
@@ -167,11 +168,11 @@
looks up the module containing that package and adds it to
`go.mod`, using the latest version.
(“Latest” is defined as the
-latest tagged stable (non-[[https://semver.org/#spec-item-9][prerelease]]) version,
+latest tagged stable (non-[prerelease](https://semver.org/#spec-item-9)) version,
or else the latest tagged prerelease version,
or else the latest untagged version.)
-In our example, `go`test` resolved the new import `rsc.io/quote`
-to the module `rsc.io/quote`v1.5.2`.
+In our example, `go test` resolved the new import `rsc.io/quote`
+to the module `rsc.io/quote v1.5.2`.
It also downloaded two dependencies used by `rsc.io/quote`,
namely `rsc.io/sampler` and `golang.org/x/text`.
Only direct dependencies are recorded in the `go.mod` file:
@@ -184,7 +185,7 @@
require rsc.io/quote v1.5.2
$
-A second `go`test` command will not repeat this work,
+A second `go test` command will not repeat this work,
since the `go.mod` is now up-to-date and the downloaded
modules are cached locally (in `$GOPATH/pkg/mod`):
@@ -199,11 +200,11 @@
in critical areas such as correctness, security, and proper licensing,
just to name a few.
For more considerations, see Russ Cox's blog post,
-“[[https://research.swtch.com/deps][Our Software Dependency Problem]].”
+“[Our Software Dependency Problem](https://research.swtch.com/deps).”
As we saw above, adding one direct dependency often
brings in other indirect dependencies too.
-The command `go`list`-m`all` lists the current module
+The command `go list -m all` lists the current module
and all its dependencies:
$ go list -m all
@@ -213,20 +214,20 @@
rsc.io/sampler v1.3.0
$
-In the `go`list` output, the current module,
-also known as the _main_module_,
+In the `go list` output, the current module,
+also known as the _main module_,
is always the first line,
followed by dependencies sorted by module path.
The `golang.org/x/text` version `v0.0.0-20170915032832-14c0d48ead0c`
is an example of a
-[[https://golang.org/cmd/go/#hdr-Pseudo_versions][pseudo-version]],
+[pseudo-version](https://golang.org/cmd/go/#hdr-Pseudo_versions),
which is the `go` command's version syntax
for a specific untagged commit.
In addition to `go.mod`, the `go` command
maintains a file named `go.sum` containing
-the expected [[https://golang.org/cmd/go/#hdr-Module_downloading_and_verification][cryptographic hashes]] of the content of specific module versions:
+the expected [cryptographic hashes](https://golang.org/cmd/go/#hdr-Module_downloading_and_verification) of the content of specific module versions:
$ cat go.sum
golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c h1:qgOY6WgZO...
@@ -245,7 +246,7 @@
whether for malicious, accidental, or other reasons.
Both `go.mod` and `go.sum` should be checked into version control.
-* Upgrading dependencies
+## Upgrading dependencies
With Go modules, versions are referenced with semantic version tags.
A semantic version has three parts: major, minor, and patch.
@@ -254,7 +255,7 @@
Let's walk through a couple minor version upgrades.
In the next section, we’ll consider a major version upgrade.
-From the output of `go`list`-m`all`,
+From the output of `go list -m all`,
we can see we're using an untagged version of `golang.org/x/text`.
Let's upgrade to the latest tagged version and test that everything still works:
@@ -268,7 +269,7 @@
$
Woohoo! Everything passes.
-Let's take another look at `go`list`-m`all` and the `go.mod` file:
+Let's take another look at `go list -m all` and the `go.mod` file:
$ go list -m all
example.com/hello
@@ -290,10 +291,10 @@
The `go.mod` file has been updated to specify `v0.3.0` too.
The `indirect` comment indicates a dependency is not used directly
by this module, only indirectly by other module dependencies.
-See `go`help`modules` for details.
+See `go help modules` for details.
Now let's try upgrading the `rsc.io/sampler` minor version.
-Start the same way, by running `go`get` and running tests:
+Start the same way, by running `go get` and running tests:
$ go get rsc.io/sampler
go: finding rsc.io/sampler v1.99.99
@@ -327,15 +328,15 @@
ok example.com/hello 0.022s
$
-Note the explicit `@v1.3.1` in the `go`get` argument.
-In general each argument passed to `go`get` can take
+Note the explicit `@v1.3.1` in the `go get` argument.
+In general each argument passed to `go get` can take
an explicit version; the default is `@latest`,
which resolves to the latest version as defined earlier.
-* Adding a dependency on a new major version
+## Adding a dependency on a new major version
Let's add a new function to our package:
-`func`Proverb` returns a Go concurrency proverb,
+`func Proverb` returns a Go concurrency proverb,
by calling `quote.Concurrency`, which is provided by
the module `rsc.io/quote/v3`.
First we update `hello.go` to add the new function:
@@ -386,7 +387,7 @@
In the example, `v3` of `rsc.io/quote` is no longer `rsc.io/quote`: instead,
it is identified by the module path `rsc.io/quote/v3`.
This convention is called
-[[https://research.swtch.com/vgo-import][semantic import versioning]],
+[semantic import versioning](https://research.swtch.com/vgo-import),
and it gives incompatible packages (those with different major versions)
different names.
In contrast, `v1.6.0` of `rsc.io/quote` should be backwards-compatible
@@ -402,17 +403,17 @@
and so on.
This gives module authors a clear rule about possible duplication
of a single module path: it is impossible for a program to build with both
-`rsc.io/quote`v1.5.2` and `rsc.io/quote`v1.6.0`.
+`rsc.io/quote v1.5.2` and `rsc.io/quote v1.6.0`.
At the same time, allowing different major versions of a module
(because they have different paths)
gives module consumers the ability to
upgrade to a new major version incrementally.
-In this example, we wanted to use `quote.Concurrency` from `rsc/quote/v3`v3.1.0`
-but are not yet ready to migrate our uses of `rsc.io/quote`v1.5.2`.
+In this example, we wanted to use `quote.Concurrency` from `rsc/quote/v3 v3.1.0`
+but are not yet ready to migrate our uses of `rsc.io/quote v1.5.2`.
The ability to migrate incrementally
is especially important in a large program or codebase.
-* Upgrading a dependency to a new major version
+## Upgrading a dependency to a new major version
Let's complete our conversion from using `rsc.io/quote` to using only `rsc.io/quote/v3`.
Because of the major version change, we should expect that some APIs may have
@@ -432,7 +433,7 @@
$
(There is also a
-[[https://golang.org/issue/30778][known bug]] in the output;
+[known bug](https://golang.org/issue/30778) in the output;
the displayed import path has incorrectly dropped the `/v3`.)
We can update our use of `quote.Hello()` in `hello.go` to use `quoteV3.HelloV3()`:
@@ -470,10 +471,10 @@
PASS
ok example.com/hello 0.014s
-* Removing unused dependencies
+## Removing unused dependencies
We've removed all our uses of `rsc.io/quote`,
-but it still shows up in `go`list`-m`all` and in our `go.mod` file:
+but it still shows up in `go list -m all` and in our `go.mod` file:
$ go list -m all
example.com/hello
@@ -494,7 +495,7 @@
)
$
-Why? Because building a single package, like with `go`build` or `go`test`,
+Why? Because building a single package, like with `go build` or `go test`,
can easily tell when something is missing and needs to be added,
but not when something can safely be removed.
Removing a dependency can only be done after
@@ -503,7 +504,7 @@
An ordinary build command does not load this information,
and so it cannot safely remove dependencies.
-The `go`mod`tidy` command cleans up these unused dependencies:
+The `go mod tidy` command cleans up these unused dependencies:
$ go mod tidy
$ go list -m all
@@ -527,7 +528,7 @@
ok example.com/hello 0.020s
$
-* Conclusion
+## Conclusion
Go modules are the future of dependency management in Go.
Module functionality is now available in all supported Go versions
@@ -535,16 +536,16 @@
This post introduced these workflows using Go modules:
-- `go`mod`init` creates a new module, initializing the `go.mod` file that describes it.
-- `go`build`, `go`test`, and other package-building commands add new dependencies to `go.mod` as needed.
-- `go`list`-m`all` prints the current module’s dependencies.
-- `go`get` changes the required version of a dependency (or adds a new dependency).
-- `go`mod`tidy` removes unused dependencies.
+ - `go mod init` creates a new module, initializing the `go.mod` file that describes it.
+ - `go build`, `go test`, and other package-building commands add new dependencies to `go.mod` as needed.
+ - `go list -m all` prints the current module’s dependencies.
+ - `go get` changes the required version of a dependency (or adds a new dependency).
+ - `go mod tidy` removes unused dependencies.
We encourage you to start using modules in your local development
and to add `go.mod` and `go.sum` files to your projects.
To provide feedback and help shape the future of dependency management in Go,
please send us
-[[https://golang.org/issue/new][bug reports]] or [[https://golang.org/wiki/ExperienceReports][experience reports]].
+[bug reports](https://golang.org/issue/new) or [experience reports](https://golang.org/wiki/ExperienceReports).
Thanks for all your feedback and help improving modules.
diff --git a/content/v2-go-modules.article b/content/v2-go-modules.article
index cb8b7be..59d86de 100644
--- a/content/v2-go-modules.article
+++ b/content/v2-go-modules.article
@@ -1,19 +1,20 @@
-Go Modules: v2 and Beyond
+# Go Modules: v2 and Beyond
7 Nov 2019
Tags: tools, versioning
+Summary: This post is part 4 in a series.
Jean de Klerk
Tyler Bui-Palsulich
-* Introduction
+## Introduction
This post is part 4 in a series.
-- Part 1 — [[/using-go-modules][Using Go Modules]]
-- Part 2 — [[/migrating-to-go-modules][Migrating To Go Modules]]
-- Part 3 — [[/publishing-go-modules][Publishing Go Modules]]
-- *Part*4*—*Go*Modules:*v2*and*Beyond* (this post)
+ - Part 1 — [Using Go Modules](/using-go-modules)
+ - Part 2 — [Migrating To Go Modules](/migrating-to-go-modules)
+ - Part 3 — [Publishing Go Modules](/publishing-go-modules)
+ - **Part 4 — Go Modules: v2 and Beyond** (this post)
As a successful project matures and new requirements are added, past features
and design decisions might stop making sense. Developers may want to integrate
@@ -29,10 +30,10 @@
version. This post explores major version semantics, how to create and publish a new
major version, and how to maintain multiple major versions of a module.
-* Major versions and module paths
+## Major versions and module paths
Modules formalized an important principle in Go, the
-[[https://research.swtch.com/vgo-import][*import*compatibility*rule*]]:
+[**import compatibility rule**](https://research.swtch.com/vgo-import):
If an old package and a new package have the same import path,
the new package must be backwards compatible with the old package.
@@ -48,8 +49,8 @@
The need for major version suffixes is one of the ways Go modules differs from
most other dependency management systems. Suffixes are needed to solve
-the [[https://research.swtch.com/vgo-import#dependency_story][diamond dependency problem]].
-Before Go modules, [[http://gopkg.in][gopkg.in]] allowed package maintainers to
+the [diamond dependency problem](https://research.swtch.com/vgo-import#dependency_story).
+Before Go modules, [gopkg.in](http://gopkg.in) allowed package maintainers to
follow what we now refer to as the import compatibility rule. With gopkg.in, if
you depend on a package that imports `gopkg.in/yaml.v1` and another package that
imports `gopkg.in/yaml.v2`, there is no conflict because the two `yaml` packages
@@ -59,7 +60,7 @@
This is a special case for compatibility with gopkg.in: modules hosted at other
domains need a slash suffix like `/v2`.
-* Major version strategies
+## Major version strategies
The recommended strategy is to develop `v2+` modules in a directory named after
the major version suffix.
@@ -69,7 +70,7 @@
/v2/go.mod → module github.com/googleapis/gax-go/v2
This approach is compatible with tools that aren't aware of modules: file paths
-within the repository match the paths expected by `go`get` in `GOPATH` mode.
+within the repository match the paths expected by `go get` in `GOPATH` mode.
This strategy also allows all major versions to be developed together in
different directories.
@@ -82,7 +83,7 @@
since it provides the most compatibility. We recommend that module authors
follow this strategy as long as they have users developing in `GOPATH` mode.
-* Publishing v2 and beyond
+## Publishing v2 and beyond
This post uses `github.com/googleapis/gax-go` as an example:
@@ -132,10 +133,10 @@
$ go mod edit -module github.com/googleapis/gax-go/v2 v2/go.mod
$
-Note that the `v2` version is treated as a separate module from the `v0`/`v1`
+Note that the `v2` version is treated as a separate module from the `v0 / v1`
versions: both may coexist in the same build. So, if your `v2+` module has
multiple packages, you should update them to use the new `/v2` import path:
-otherwise, your `v2+` module will depend on your `v0`/`v1` module. For example,
+otherwise, your `v2+` module will depend on your `v0 / v1` module. For example,
to update all `github.com/my/project` references to `github.com/my/project/v2`,
you can use `find` and `sed`:
@@ -165,7 +166,7 @@
compatible changes and bug fixes will lead to new minor and patch releases
(for example, `v1.1.0`, `v2.0.1`, etc.).
-* Conclusion
+## Conclusion
Major version changes result in development and maintenance overhead and
require investment from downstream users to migrate. The larger the project,
diff --git a/content/versioning-proposal.article b/content/versioning-proposal.article
index 92c8f54..e85ca3d 100644
--- a/content/versioning-proposal.article
+++ b/content/versioning-proposal.article
@@ -1,13 +1,14 @@
-A Proposal for Package Versioning in Go
+# A Proposal for Package Versioning in Go
26 Mar 2018
Tags: tools, versioning
+Summary: Eight years ago, the Go team introduced `goinstall` (which led to `go get`) and with it the decentralized, URL-like import paths that Go developers are familiar with today. After we released `goinstall`, one of the first questions people asked was how to incorporate version information. We admitted we didn’t know. For a long time, we believed that the problem of package versioning would be best solved by an add-on tool, and we encouraged people to create one. The Go community created many tools with different approaches. Each one helped us all better understand the problem, but by mid-2016 it was clear that there were now too many solutions. We needed to adopt a single, official tool.
Russ Cox
-* Introduction
+## Introduction
Eight years ago, the Go team introduced `goinstall`
-(which led to `go`get`)
+(which led to `go get`)
and with it the decentralized, URL-like import paths
that Go developers are familiar with today.
After we released `goinstall`, one of the first questions people asked
@@ -25,17 +26,17 @@
we all believed the answer would be to follow the package versioning approach
exemplified by Rust’s Cargo, with tagged semantic versions,
a manifest, a lock file, and a
-[[https://research.swtch.com/version-sat][SAT solver]] to decide which versions to use.
+[SAT solver](https://research.swtch.com/version-sat) to decide which versions to use.
Sam Boyer led a team to create Dep, which followed this rough plan,
and which we intended to serve as the model for `go` command integration.
But as we learned more about the implications of the Cargo/Dep approach,
it became clear to me that Go would benefit from changing
some of the details, especially concerning backwards compatibility.
-* The Impact of Compatibility
+## The Impact of Compatibility
The most important new feature of
-[[https://blog.golang.org/preview-of-go-version-1][Go 1]]
+[Go 1](https://blog.golang.org/preview-of-go-version-1)
was not a language feature.
It was Go 1’s emphasis on backwards compatibility.
Until that point we’d issued stable release
@@ -44,21 +45,21 @@
We observed significant acceleration in interest and adoption
immediately after the release of Go 1.
We believe that the
-[[https://golang.org/doc/go1compat.html][promise of compatibility]]
+[promise of compatibility](https://golang.org/doc/go1compat.html)
made developers feel much more comfortable relying on
Go for production use
and is a key reason that Go is popular today.
Since 2013 the
-[[https://golang.org/doc/faq#get_version][Go FAQ]]
+[Go FAQ](https://golang.org/doc/faq#get_version)
has encouraged package developers to provide their own
users with similar expectations of compatibility.
-We call this the _import_compatibility_rule_:
+We call this the _import compatibility rule_:
“If an old package and a new package have the same import path,
the new package must be backwards compatible with the old package.”
Independently,
-[[http://semver.org/][semantic versioning]]
-has become the _de_facto_
+[semantic versioning](http://semver.org/)
+has become the _de facto_
standard for describing software versions in many language communities,
including the Go community.
Using semantic versioning, later versions are expected to be
@@ -71,7 +72,7 @@
as most Go developers expect,
then the import compatibility rule requires that
different major versions must use different import paths.
-This observation led us to _semantic_import_versioning_,
+This observation led us to _semantic import versioning_,
in which versions starting at v2.0.0 include the major
version in the import path: `my/thing/v2/sub/pkg`.
@@ -86,7 +87,7 @@
I was also surprised to realize that
there is a second, independent logical route to
semantic import versioning:
-[[https://talks.golang.org/2016/refactor.article][gradual code repair]]
+[gradual code repair](https://talks.golang.org/2016/refactor.article)
or partial code upgrades.
In a large program, it’s unrealistic to expect all packages in the program
to update from v1 to v2 of a particular dependency at the same time.
@@ -95,7 +96,7 @@
But then the program’s build, and the program’s final binary,
must include both v1 and v2 of the dependency.
Giving them the same import path would lead to confusion,
-violating what we might call the _import_uniqueness_rule_:
+violating what we might call the _import uniqueness rule_:
different packages must have different import paths.
The only way to have
partial code upgrades, import uniqueness, _and_ semantic versioning
@@ -131,7 +132,7 @@
which is the problem of deciding which package versions to use for a given build.
The constraints of Cargo and Dep make version selection
equivalent to
-[[https://research.swtch.com/version-sat][solving Boolean satisfiability]],
+[solving Boolean satisfiability](https://research.swtch.com/version-sat),
meaning it can be very expensive to determine whether
a valid version configuration even exists.
And then there may be many valid configurations,
@@ -141,7 +142,7 @@
to find the single best configuration, which always exists.
This algorithm,
which I call
-[[https://research.swtch.com/vgo-mvs][_minimal_version_selection_]],
+[_minimal version selection_](https://research.swtch.com/vgo-mvs),
in turn eliminates the need for separate lock and manifest files.
It replaces them with a single, short configuration file,
edited directly by both developers and tools,
@@ -161,7 +162,7 @@
eliminates that complexity,
leading to a much simpler system.
-* Progress, a Prototype, and a Proposal
+## Progress, a Prototype, and a Proposal
Dep was released in January 2017.
Its basic model—code tagged with
@@ -191,7 +192,7 @@
implied semantic import versioning.
That seemed like a real breakthrough.
I wrote a first draft of what became my
-[[https://research.swtch.com/vgo-import][semantic import versioning]]
+[semantic import versioning](https://research.swtch.com/vgo-import)
blog post,
concluding it by suggesting that Dep adopt the convention.
I sent the draft to the people I’d been talking to,
@@ -204,7 +205,7 @@
In mid-December, I discovered that import compatibility
and semantic import versioning together allowed
-cutting version selection down to [[https://research.swtch.com/vgo-mvs][minimal version selection]].
+cutting version selection down to [minimal version selection](https://research.swtch.com/vgo-mvs).
I wrote a basic implementation to be sure I understood it,
I spent a while learning the theory behind why it was so simple,
and I wrote a draft of the post describing it.
@@ -226,7 +227,7 @@
I spent the first three weeks of February turning the
wrapper into a full versioned `go` command, `vgo`;
writing drafts of a
-[[https://research.swtch.com/vgo][blog post series introducing `vgo`]];
+[blog post series introducing `vgo`](https://research.swtch.com/vgo);
and discussing them with
Sam Boyer, the package management working group,
and the Go team.
@@ -237,26 +238,26 @@
semantic import versioning, and minimal version selection,
the `vgo` prototype introduces a number of smaller
but significant changes motivated by eight years of
-experience with `goinstall` and `go`get`:
-the new concept of a [[https://research.swtch.com/vgo-module][Go module]],
+experience with `goinstall` and `go get`:
+the new concept of a [Go module](https://research.swtch.com/vgo-module),
which is a collection of packages versioned as a unit;
-[[https://research.swtch.com/vgo-repro][verifiable and verified builds]];
+[verifiable and verified builds](https://research.swtch.com/vgo-repro);
and
-[[https://research.swtch.com/vgo-cmd][version-awareness throughout the `go` command]],
+[version-awareness throughout the `go` command](https://research.swtch.com/vgo-cmd),
enabling work outside `$GOPATH`
and the elimination of (most) `vendor` directories.
-The result of all of this is the [[https://golang.org/design/24301-versioned-go][official Go proposal]],
+The result of all of this is the [official Go proposal](https://golang.org/design/24301-versioned-go),
which I filed last week.
Even though it might look like a complete implementation,
it’s still just a prototype,
one that we will all need to work together to complete.
-You can download and try the `vgo` prototype from [[https://golang.org/x/vgo][golang.org/x/vgo]],
+You can download and try the `vgo` prototype from [golang.org/x/vgo](https://golang.org/x/vgo),
and you can read the
-[[https://research.swtch.com/vgo-tour][Tour of Versioned Go]]
+[Tour of Versioned Go](https://research.swtch.com/vgo-tour)
to get a sense of what using `vgo` is like.
-* The Path Forward
+## The Path Forward
The proposal I filed last week is exactly that: an initial proposal.
I know there are problems with it that the Go team and I can’t see,
@@ -265,11 +266,11 @@
to identify and address the problems in the current proposal,
to make sure that the final implementation that ships in a future
Go release works well for as many developers as possible.
-Please point out problems on the [[https://golang.org/issue/24301][proposal discussion issue]].
+Please point out problems on the [proposal discussion issue](https://golang.org/issue/24301).
I will keep the
-[[https://golang.org/issue/24301#issuecomment-371228742][discussion summary]]
+[discussion summary](https://golang.org/issue/24301#issuecomment-371228742)
and
-[[https://golang.org/issue/24301#issuecomment-371228664][FAQ]]
+[FAQ](https://golang.org/issue/24301#issuecomment-371228664)
updated as feedback arrives.
For this proposal to succeed, the Go ecosystem as a
@@ -284,6 +285,6 @@
please email Steve Francia at spf@golang.org.
We’re looking forward to (finally!) providing the Go community with a single, official answer
-to the question of how to incorporate package versioning into `go`get`.
+to the question of how to incorporate package versioning into `go get`.
Thanks to everyone who helped us get this far, and to everyone who will help us going forward.
We hope that, with your help, we can ship something that Go developers will love.
diff --git a/content/why-generics.article b/content/why-generics.article
index 44e9e1e..b4c3a31 100644
--- a/content/why-generics.article
+++ b/content/why-generics.article
@@ -1,10 +1,11 @@
-Why Generics?
+# Why Generics?
31 Jul 2019
Tags: go2, proposals, generics
+Summary: This is the blog post version of my talk last week at Gophercon 2019.
Ian Lance Taylor
-* Introduction
+## Introduction
This is the blog post version of my talk last week at Gophercon 2019.
@@ -17,19 +18,19 @@
Go was released on November 10, 2009.
Less than 24 hours later we saw the
-[[https://groups.google.com/d/msg/golang-nuts/70-pdwUUrbI/onMsQspcljcJ][first comment about generics]].
+[first comment about generics](https://groups.google.com/d/msg/golang-nuts/70-pdwUUrbI/onMsQspcljcJ).
(That comment also mentions exceptions, which we added to the
language, in the form of `panic` and `recover`, in early 2010.)
In three years of Go surveys, lack of generics has always been listed
as one of the top three problems to fix in the language.
-* Why generics?
+## Why generics?
But what does it mean to add generics, and why would we want it?
To paraphrase
-[[https://www.dagstuhl.de/en/program/calendar/semhp/?semnr=98171][Jazayeri, et al]]:
+[Jazayeri, et al](https://www.dagstuhl.de/en/program/calendar/semhp/?semnr=98171):
generic programming enables the representation of functions and data
structures in a generic form, with types factored out.
@@ -99,7 +100,7 @@
Most other statically typed languages, like C++ or Java or Rust or
Swift, support generics to address exactly this kind of issue.
-* Go generic programming today
+## Go generic programming today
So how do people write this kind of code in Go?
@@ -175,7 +176,7 @@
with types factored out.
That's exactly what we want here.
-* What generics can bring to Go
+## What generics can bring to Go
The first and most important thing we want from generics in Go is to
be able to write functions like `Reverse` without caring about the
@@ -196,11 +197,11 @@
I went through `Reverse` in detail, but there are many other functions
that we could write generically, such as:
-- Find smallest/largest element in slice
-- Find average/standard deviation of slice
-- Compute union/intersection of maps
-- Find shortest path in node/edge graph
-- Apply transformation function to slice/map, returning new slice/map
+ - Find smallest/largest element in slice
+ - Find average/standard deviation of slice
+ - Compute union/intersection of maps
+ - Find shortest path in node/edge graph
+ - Apply transformation function to slice/map, returning new slice/map
These examples are available in most other languages.
In fact, I wrote this list by glancing at the C++ standard template
@@ -209,10 +210,10 @@
There are also examples that are specific to Go with its strong
support for concurrency.
-- Read from a channel with a timeout
-- Combine two channels into a single channel
-- Call a list of functions in parallel, returning a slice of results
-- Call a list of functions, using a Context, return the result of the first function to finish, canceling and cleaning up extra goroutines
+ - Read from a channel with a timeout
+ - Combine two channels into a single channel
+ - Call a list of functions in parallel, returning a slice of results
+ - Call a list of functions, using a Context, return the result of the first function to finish, canceling and cleaning up extra goroutines
I've seen all of these functions written out many times with different
types.
@@ -239,10 +240,10 @@
aren’t the only ones.
Here are some other examples.
-- Sets
-- Self-balancing trees, with efficient insertion and traversal in sorted order
-- Multimaps, with multiple instances of a key
-- Concurrent hash maps, supporting parallel insertions and lookups with no single lock
+ - Sets
+ - Self-balancing trees, with efficient insertion and traversal in sorted order
+ - Multimaps, with multiple instances of a key
+ - Concurrent hash maps, supporting parallel insertions and lookups with no single lock
If we can write generic types, we can define new data structures, like
these, that have the same type-checking advantages as slices and maps:
@@ -266,12 +267,12 @@
I hope I’ve explained why this is worth looking into.
-* Benefits and costs
+## Benefits and costs
But generics don't come from the
-[[https://mainlynorfolk.info/folk/songs/bigrockcandymountain.html][Big Rock Candy Mountain]],
+[Big Rock Candy Mountain](https://mainlynorfolk.info/folk/songs/bigrockcandymountain.html),
the land where the sun shines every day over the
-[[http://www.lat-long.com/Latitude-Longitude-773297-Montana-Lemonade_Springs.html][lemonade springs]].
+[lemonade springs](http://www.lat-long.com/Latitude-Longitude-773297-Montana-Lemonade_Springs.html).
Every language change has a cost.
There's no doubt that adding generics to Go will make the language
more complicated.
@@ -288,13 +289,13 @@
To make this more concrete I’m going to list a few guidelines we
should follow.
-** Minimize new concepts
+### Minimize new concepts
We should add as few new concepts to the language as possible.
That means a minimum of new syntax and a minimum of new keywords and
other names.
-** Complexity falls on the writer of generic code, not the user
+### Complexity falls on the writer of generic code, not the user
As much as possible the complexity should fall on the programmer
writing the generic package.
@@ -304,7 +305,7 @@
should be reported in a way that is easy to understand and to fix.
It should also be easy to debug calls into generic code.
-** Writer and user can work independently
+### Writer and user can work independently
Similarly, we should make it easy to separate the concerns of the
writer of the generic code and its user, so that they can develop their
@@ -315,7 +316,7 @@
This sounds obvious, but it's not true of generics in every other
programming language.
-** Short build times, fast execution times
+### Short build times, fast execution times
Naturally, as much as possible, we want to keep the short build times
and fast execution time that Go gives us today.
@@ -323,7 +324,7 @@
execution.
As much as possible, we want both.
-** Preserve clarity and simplicity of Go
+### Preserve clarity and simplicity of Go
Most importantly, Go today is a simple language.
Go programs are usually clear and easy to understand.
@@ -335,9 +336,9 @@
These guidelines should apply to any generics implementation in Go.
That’s the most important message I want to leave you with today:
-*generics*can*bring*a*significant*benefit*to*the*language,*but*they*are*only*worth*doing*if*Go*still*feels*like*Go*.
+**generics can bring a significant benefit to the language, but they are only worth doing if Go still feels like Go**.
-* Draft design
+## Draft design
Fortunately, I think it can be done.
To finish up this article I’m going to shift from discussing why we
@@ -345,7 +346,7 @@
discuss a design for how we think we can add them to the language.
At this year's Gophercon Robert Griesemer and I published
-[[https://github.com/golang/proposal/blob/master/design/go2draft-contracts.md][a design draft]]
+[a design draft](https://github.com/golang/proposal/blob/master/design/go2draft-contracts.md)
for adding generics to Go.
See the draft for full details.
I'll go over some of the main points here.
@@ -367,7 +368,7 @@
The element type of the slice has been factored out.
It's now named `Element` and has become what we call a
-_type_parameter_.
+_type parameter_.
Instead of being part of the type of the slice parameter, it's now a
separate, additional, type parameter.
@@ -397,7 +398,7 @@
more complex than `ReverseInts` and `ReverseStrings`, that complexity
falls on the writer of the function, not the caller.
-** Contracts
+### Contracts
Since Go is a statically typed language, we have to talk about the
type of a type parameter.
@@ -456,7 +457,7 @@
Here `contract` may be a new keyword, or a special identifier
recognized in package scope; see the design draft for details.
-Anybody who remembers [[https://github.com/golang/proposal/blob/4a530dae40977758e47b78fae349d8e5f86a6c0a/design/go2draft-contracts.md][the design we presented at Gophercon 2018]]
+Anybody who remembers [the design we presented at Gophercon 2018](https://github.com/golang/proposal/blob/4a530dae40977758e47b78fae349d8e5f86a6c0a/design/go2draft-contracts.md)
will see that this way of writing a contract is a lot simpler.
We got a lot of feedback on that earlier design that contracts were
too complicated, and we've tried to take that into account.
@@ -468,7 +469,7 @@
They also let you describe the relationship between different type
parameters.
-** Contracts with methods
+### Contracts with methods
Here is another simple example, of a function that uses the String
method to return a `[]string` of the string representation of all the
@@ -506,7 +507,7 @@
direct conversions between them.
So this is worth writing, even though `fmt.Stringer` exists.
-** Contracts with multiple types
+### Contracts with multiple types
Here is an example of a contract with multiple type parameters.
@@ -540,7 +541,7 @@
single type. It can describe the relationships between two or more
types.
-** Ordered types
+### Ordered types
One surprisingly common complaint about Go is that it doesn't have a
`Min` function.
@@ -601,7 +602,7 @@
return b
}
-** Generic data structures
+### Generic data structures
Finally, let's look at a simple generic data structure, a binary
tree. In this example the tree has a comparison function, so there
@@ -686,7 +687,7 @@
as much as possible using one is no different from using an ordinary
non-generic data structure.
-** Next steps
+### Next steps
We are working on actual implementations to allow us to experiment
with this design.
@@ -696,7 +697,7 @@
on these implementations as they become available.
Robert Griesemer has written a
-[[https://golang.org/cl/187317][preliminary CL]]
+[preliminary CL](https://golang.org/cl/187317)
that modifies the go/types package.
This permits testing whether code using generics and contracts can
type check.
diff --git a/content/wire.article b/content/wire.article
index 2d9ca5b..5113228 100644
--- a/content/wire.article
+++ b/content/wire.article
@@ -1,19 +1,20 @@
-Compile-time Dependency Injection With Go Cloud's Wire
+# Compile-time Dependency Injection With Go Cloud's Wire
9 Oct 2018
+Summary: The Go team recently [announced](https://blog.golang.org/go-cloud) the open source project [Go Cloud](https://github.com/google/go-cloud), with portable Cloud APIs and tools for [open cloud](https://cloud.google.com/open-cloud/) development. This post goes into more detail about Wire, a dependency injection tool used in Go Cloud.
Robert van Gent
-* Overview
+## Overview
-The Go team recently [[https://blog.golang.org/go-cloud][announced]] the
-open source project [[https://github.com/google/go-cloud][Go Cloud]],
-with portable Cloud APIs and tools for [[https://cloud.google.com/open-cloud/][open cloud]] development.
+The Go team recently [announced](https://blog.golang.org/go-cloud) the
+open source project [Go Cloud](https://github.com/google/go-cloud),
+with portable Cloud APIs and tools for [open cloud](https://cloud.google.com/open-cloud/) development.
This post goes into more detail about Wire,
a dependency injection tool used in Go Cloud.
-* What problem does Wire solve?
+## What problem does Wire solve?
-[[https://en.wikipedia.org/wiki/Dependency_injection][Dependency injection]]
+[Dependency injection](https://en.wikipedia.org/wiki/Dependency_injection)
is a standard technique for producing flexible and loosely coupled code,
by explicitly providing components with all of the dependencies they need to work.
In Go, this often takes the form of passing dependencies to constructors:
@@ -43,21 +44,21 @@
and then let Wire do the tedious work of generating initialization code
for the entire dependency graph.
-* Why is this part of Go Cloud?
+## Why is this part of Go Cloud?
Go Cloud's goal is to make it easier to write portable Cloud applications
by providing idiomatic Go APIs for useful Cloud services.
-For example, [[https://godoc.org/github.com/google/go-cloud/blob][blob.Bucket]]
+For example, [blob.Bucket](https://godoc.org/github.com/google/go-cloud/blob)
provides a storage API with implementations for Amazon's S3 and Google Cloud Storage (GCS);
applications written using `blob.Bucket` can swap implementations without
changing their application logic.
However, the initialization code is inherently provider-specific,
and each provider has a different set of dependencies.
-For example, [[https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket][constructing a GCS `blob.Bucket`]]
+For example, [constructing a GCS `blob.Bucket`](https://godoc.org/github.com/google/go-cloud/blob/gcsblob#OpenBucket)
requires a `gcp.HTTPClient`,
which eventually requires `google.Credentials`,
-while [[https://godoc.org/github.com/google/go-cloud/blob/s3blob][constructing one for S3]]
+while [constructing one for S3](https://godoc.org/github.com/google/go-cloud/blob/s3blob)
requires an `aws.Config`,
which eventually requires AWS credentials.
Thus, updating an application to use a different `blob.Bucket` implementation
@@ -66,34 +67,34 @@
of Go Cloud portable APIs,
but it's also a general-purpose tool for dependency injection.
-* Hasn't this been done already?
+## Hasn't this been done already?
There are a number of dependency injection frameworks out there.
-For Go, [[https://github.com/uber-go/dig][Uber's dig]] and [[https://github.com/facebookgo/inject][Facebook's inject]]
+For Go, [Uber's dig](https://github.com/uber-go/dig) and [Facebook's inject](https://github.com/facebookgo/inject)
both use reflection to do runtime dependency injection.
-Wire was primarily inspired by Java's [[https://google.github.io/dagger/][Dagger 2]],
-and uses code generation rather than reflection or [[https://en.wikipedia.org/wiki/Service_locator_pattern][service locators]].
+Wire was primarily inspired by Java's [Dagger 2](https://google.github.io/dagger/),
+and uses code generation rather than reflection or [service locators](https://en.wikipedia.org/wiki/Service_locator_pattern).
We think this approach has several advantages:
-- Runtime dependency injection can be hard to follow and debug when the
- dependency graph gets complex.
- Using code generation means that the initialization code that's executed
- at runtime is regular,
- idiomatic Go code that's easy to understand and debug.
- Nothing is obfuscated by an intervening framework doing "magic".
- In particular, problems like forgetting a dependency become compile-time errors,
- not run-time errors.
-- Unlike [[https://en.wikipedia.org/wiki/Service_locator_pattern][service locators]],
- there's no need to make up arbitrary names or keys to register services.
- Wire uses Go types to connect components with their dependencies.
-- It's easier to avoid dependency bloat. Wire's generated code will only
- import the dependencies you need,
- so your binary won't have unused imports.
- Runtime dependency injectors can't identify unused dependencies until runtime.
-- Wire's dependency graph is knowable statically, which provides opportunities for tooling and visualization.
+ - Runtime dependency injection can be hard to follow and debug when the
+ dependency graph gets complex.
+ Using code generation means that the initialization code that's executed
+ at runtime is regular,
+ idiomatic Go code that's easy to understand and debug.
+ Nothing is obfuscated by an intervening framework doing "magic".
+ In particular, problems like forgetting a dependency become compile-time errors,
+ not run-time errors.
+ - Unlike [service locators](https://en.wikipedia.org/wiki/Service_locator_pattern),
+ there's no need to make up arbitrary names or keys to register services.
+ Wire uses Go types to connect components with their dependencies.
+ - It's easier to avoid dependency bloat. Wire's generated code will only
+ import the dependencies you need,
+ so your binary won't have unused imports.
+ Runtime dependency injectors can't identify unused dependencies until runtime.
+ - Wire's dependency graph is knowable statically, which provides opportunities for tooling and visualization.
-* How does it work?
+## How does it work?
Wire has two basic concepts: providers and injectors.
@@ -175,19 +176,19 @@
but Wire saves a lot of manual toil for components and applications with
more complex dependency graphs.
-* How can I get involved and learn more?
+## How can I get involved and learn more?
-The [[https://github.com/google/wire/blob/master/README.md][Wire README]]
+The [Wire README](https://github.com/google/wire/blob/master/README.md)
goes into more detail about how to use Wire and its more advanced features.
-There's also a [[https://github.com/google/wire/tree/master/_tutorial][tutorial]]
+There's also a [tutorial](https://github.com/google/wire/tree/master/_tutorial)
that walks through using Wire in a simple application.
We appreciate any input you have about your experience with Wire!
-[[https://github.com/google/wire][Wire's]] development is conducted on GitHub,
-so you can [[https://github.com/google/wire/issues/new/choose][file an issue]]
+[Wire's](https://github.com/google/wire) development is conducted on GitHub,
+so you can [file an issue](https://github.com/google/wire/issues/new/choose)
to tell us what could be better.
For updates and discussion about the project,
-join [[https://groups.google.com/forum/#!forum/go-cloud][the Go Cloud mailing list]].
+join [the Go Cloud mailing list](https://groups.google.com/forum/#!forum/go-cloud).
Thank you for taking the time to learn about Go Cloud's Wire.
We’re excited to work with you to make Go the language of choice for developers
diff --git a/content/writing-scalable-app-engine.article b/content/writing-scalable-app-engine.article
index c5ca023..c97674c 100644
--- a/content/writing-scalable-app-engine.article
+++ b/content/writing-scalable-app-engine.article
@@ -1,12 +1,13 @@
-Writing scalable App Engine applications
+# Writing scalable App Engine applications
1 Nov 2011
Tags: appengine, optimization
+Summary: Back in May, we [announced](https://blog.golang.org/2011/05/go-and-google-app-engine.html) the Go runtime for App Engine. Since then, we've opened it up for everyone to use, added many new APIs, and improved performance. We have been thrilled by all the interesting ways that people are using Go on App Engine. One of the key benefits of the Go runtime, apart from working in a fantastic language, is that it has high performance. Go applications compile to native code, with no interpreter or virtual machine getting between your program and the machine.
David Symonds
-* Introduction
+##
-Back in May, we [[https://blog.golang.org/2011/05/go-and-google-app-engine.html][announced]]
+Back in May, we [announced](https://blog.golang.org/2011/05/go-and-google-app-engine.html)
the Go runtime for App Engine.
Since then, we've opened it up for everyone to use,
added many new APIs, and improved performance.
@@ -19,15 +20,15 @@
Making your web application fast is important because it is well known that
a web site's latency has a measurable impact on user happiness,
-and [[https://googlewebmastercentral.blogspot.com/2010/04/using-site-speed-in-web-search-ranking.html][Google web search uses it as a ranking factor]].
-Also announced in May was that App Engine would be [[http://googleappengine.blogspot.com/2011/05/year-ahead-for-google-app-engine.html][leaving its Preview status]]
-and transitioning to a [[https://www.google.com/enterprise/cloud/appengine/pricing.html][new pricing model]],
+and [Google web search uses it as a ranking factor](https://googlewebmastercentral.blogspot.com/2010/04/using-site-speed-in-web-search-ranking.html).
+Also announced in May was that App Engine would be [leaving its Preview status](http://googleappengine.blogspot.com/2011/05/year-ahead-for-google-app-engine.html)
+and transitioning to a [new pricing model](https://www.google.com/enterprise/cloud/appengine/pricing.html),
providing another reason to write efficient App Engine applications.
To make it easier for Go developers using App Engine to write highly efficient,
scalable applications, we recently updated some existing App Engine articles
to include snippets of Go source code and to link to relevant Go documentation.
-- [[http://code.google.com/appengine/articles/scaling/overview.html][Best practices for writing scalable applications]]
+ - [Best practices for writing scalable applications](http://code.google.com/appengine/articles/scaling/overview.html)
-- [[http://code.google.com/appengine/articles/managing-resources.html][Managing Your App's Resource Usage]]
+ - [Managing Your App's Resource Usage](http://code.google.com/appengine/articles/managing-resources.html)
