content: add Contributor Workshop Post
Change-Id: Idd20f8c6c5e9f630fee8c436ae48b4c0e1966dc9
Reviewed-on: https://go-review.googlesource.com/53870
Reviewed-by: Dmitri Shuralyov <shurcool@gmail.com>
Reviewed-by: Chris Broadfoot <cbro@golang.org>
diff --git a/content/contributor-workshop.article b/content/contributor-workshop.article
new file mode 100644
index 0000000..533721c
--- /dev/null
+++ b/content/contributor-workshop.article
@@ -0,0 +1,387 @@
+Contribution Workshop
+9 Aug 2017
+Tags: community
+
+Steve Francia, Cassandra Salisbury, Matt Broberg, Dmitri Shuralyov
+
+* Contribution Workshop
+
+** Event Overview
+
+by [[https://twitter.com/spf13][Steve]]
+
+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
+Go project. This was the first time the Go project has ever attempted anything
+like this. We had about 140 participants and about 35 people who volunteered as
+mentors. Mentors not only received warm fuzzy feelings for helping others, but
+also a very stylish Go Mentor trucker hat. We had contributors of all
+ages and experience levels coming from North and South America, Africa, Europe,
+Asia, and Australia. It was truly a worldwide effort of Gophers coming together
+at GopherCon.
+
+One of our reasons for running the workshop was for it to act as a forcing
+function to make us improve our contributor experience. In preparation for the
+workshop, we rewrote our contributor guide, including adding a "troubleshooting"
+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,"_
+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
+the total score when they performed actions like registering an account, making
+a change list (also known as a CL, similar to a pull request),
+amending a CL, or submitting a CL.
+
+.image contributor-workshop/image17.png
+
+Brad Fitzpatrick, who stayed home from GopherCon this year, was ready and
+waiting to review all CLs submitted. He was so quick to review that many people
+thought he was an automated bot. Internally our team is now calling him
+"BradBot" mostly because we are in awe and a bit jealous.
+
+.image contributor-workshop/image9.jpg
+.image contributor-workshop/image6.png
+
+*** Impact
+
+We had a total of 65 contributions submitted from the people who participated
+in the workshop (within a week of the workshop). Of these, 44 were from
+contributors who had never previously contributed to any of the repos in the Go
+project. Half (22) of these contributions were already merged. Many of the
+others are waiting on the codebase to thaw as we are in the middle of a freeze
+for the upcoming 1.9 release.
+
+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]]
+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.
+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]]
+
+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]]
+
+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]]
+and she did submitting
+[[https://golang.org/cl/48871/][CL 48871]],
+after which she tweeted:
+
+.image contributor-workshop/image19.png
+
+Not only were some great improvements made, but most importantly, we narrowed
+the gap between the core Go team and the broader community members. Many people
+on the Go team remarked that the community members were teaching them things
+about the Go project. People in the community (in person, and on Twitter)
+remarked that felt welcome to participate in the project.
+
+.image contributor-workshop/image12.png
+.image contributor-workshop/image13.png
+.image contributor-workshop/image3.png
+
+*** Future
+
+The event was successful well beyond our expectations. Sameer Ajmani, Go team
+manager said, "The contributor workshop was incredibly fun and educational–for
+the Go team. We cringed as users hit the rough edges in our process, and
+celebrated when they got up on the dashboard. The cheer when the group score
+hit 1000 was awesome."
+
+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]].
+
+I've asked a few participants of the event to share their experiences below:
+
+** My Contribution Experience
+
+by [[https://twitter.com/cassandraoid][Cassandra]]
+
+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
+participate, so I thought what the heck.
+
+As I walked into the room (let's be real, I ran into the room because I was
+running late) I was pleased to see the room was jam-packed. I looked around for
+people in Gopher caps, which was the main indicator they were teachers. I sat
+down at one of the 16 round tables that had two hats and three non-hats.
+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.g23bf63f132_2_9][a link]]
+to make it easy to follow.
+
+.image contributor-workshop/image16.png
+
+The murmurs grew from a deep undercurrent to a resounding melody of voices,
+people were getting their computers set up with Go, they were skipping ahead to
+make sure their GOPATH was set, and were… wait what's Gerrit?
+
+Most of us had to get a little intro to Gerrit. I had no clue what it was, but
+luckily there was a handy slide. Jess explained that it was an alternative to
+GitHub with slightly more advanced code review tools. We then went through
+GitHub vs Geritt terminology, so we had better understanding of the process.
+
+.image contributor-workshop/image10.png
+
+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
+score system.
+
+.image contributor-workshop/image7.png
+
+Seeing your name pop up on the board and listening to everyone's excited was
+intoxicating. It also invoked a sense of teamwork that lead to a feeling of
+inclusion and feeling like you were truly a part of the Go community.
+
+.image contributor-workshop/image11.png
+
+In 6 steps a room of around 80 people were able to learn how to contribute to
+go within an hour. That's a feat!
+
+It wasn't nearly as difficult as I anticipated and it wasn't out of scope for a
+total newbie. It fostered a sense of community in an active and tangible way as
+well as a sense of inclusion in the illustrious process of Go contributions.
+
+I'd personally like to thank the Go Team, the Gopher mentors in hats, and my
+fellow participants for making it one of my most memorable moments at
+GopherCon.
+
+** My Contribution Experience
+
+by [[https://twitter.com/mjbrender][Matt]]
+
+I've always found programming languages to be intimidating. It's the code that
+enables me to write code. Surely smarter people than me should be working on
+it. It feels too distant to touch and too significant for me to edit. So when
+the opportunity to join a workshop to contribute to my new favorite programming
+language came up, I was as excited to see how I could help. A month later, I'm
+now certain that anyone and everyone can (and should) contribute back to Go.
+
+Here are my very verbose steps to go from 0 to 2 contributions to Go:
+
+*** 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]]
+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
+Go under `$GOPATH`, so I put it in my other workspace (which is ~/Develop).
+
+ cd $DEV # That's my source code folder outside of $GOPATH
+ git clone --depth 1 https://go.googlesource.com/go
+
+Then install the helper tool, `go-contrib-init`:
+
+ go get -u golang.org/x/tools/cmd/go-contrib-init
+
+Now you can run `go-contrib-init` from the folder we cloned above and see
+whether or not we're ready to contribute. If you're following along you're
+definitely not ready yet.
+
+Next, install codereview so you can participate in a Gerrit code review:
+
+ go get -u golang.org/x/review/git-codereview
+
+This package includes `git change` and `git mail` which will replace your
+normal workflow for `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
+you (more on choosing a CLA here. For me it was a personal one for all Google
+projects. You can see all CLAs you've signed at
+[[https://cla.developers.google.com/clas][cla.developers.google.com/clas]]).
+
+AND BAM. You're good (to go)! But where to contribute?
+
+*** Contributing
+
+In workshop sent us into the `scratch` repository, which is a safe place to
+fool around in order to master the workflow:
+
+ cd $(go env GOPATH)/src/golang.org/x
+ git clone --depth 1 [[https://go.googlesource.com/scratch][go.googlesource.com/scratch]]
+
+First stop is to `cd` in and run `go-contrib-init` to make sure you're ready to contribute:
+
+ go-contrib-init
+ All good. Happy hacking!
+
+From there, I made a folder, did a `git add -u` then took `git change` for a
+spin. It has what the Go team call the "magic hash", which is the one line you
+shouldn't touch. Other than that, it feels just like `git commit`. Once I got
+the commit message matching the format of `package: description` (description
+begins with a lowercase), I used `git mail` to send it over to Gerrit.
+
+Two good to know things: `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]].
+
+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 :+1:.
+
+.image contributor-workshop/image15.png
+.image contributor-workshop/image23.png
+
+*** 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
+around the many packages available to see what was available and interesting to
+me. And by "cruised around" I mean attempted to find a list of packages, then
+went to my source code to see what's around under the `go/src/` folder:
+
+.image contributor-workshop/image22.png
+
+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
+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).
+
+.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, 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:
+
+ func ExampleRegexp_FindString() {
+ re := regexp.MustCompile("fo.?")
+ fmt.Printf("%q\n", re.FindString("seafood"))
+ fmt.Printf("%q\n", re.FindString("meat"))
+ // Output:
+ // "foo"
+ // ""
+ }
+
+Kind of cool, right?? I followed Francesc's lead and added a function
+`ExampleQuoteMeta` and added a few I thought would be helpful. From there it's
+a `git change` and `git mail` to Gerrit!
+
+I have to say that Steve Francia challenged me to "find something that isn't an
+open issue and fix it," so I included some documentation changes for QuoteMeta
+in my patch. It's going to be open for a bit longer given the additional scope,
+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
+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]].
+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
+how simple it is to get into the flow of contributing. If you're like me,
+you'll be good 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
+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
+
+by [[https://twitter.com/shurcooL][Dmitri]]
+
+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
+before it started.
+
+I made my first contribution to Go on May 10th, 2014. I remember it was about
+four months from the moment I wanted to contribute, until that day, when I
+actually sent my first CL. It took that long to build up the courage and fully
+commit to figuring out the process. I was an experienced software engineer at
+the time. Despite that, the Go contribution process felt alien—being unlike all
+other processes I was already familiar with—and therefore seemed intimidating.
+It was well documented though, so I knew it would be just a matter of finding
+the time, sitting down, and doing it. The "unknown" factor kept me from giving
+it a shot.
+
+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]]
+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
+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!
+
+Which brings me to this event and why I thought it was such a good idea. For
+anyone who ever wanted to contribute to Go, but felt daunted by the unfamiliar
+and seemingly lengthy process (like I was during those four months), this was
+their chance! Not only is it easy to commit to figuring it out by attending the
+event, but also the Go team and helpful volunteer mentors would be there to
+help you along the way.
+
+Despite the already high expectations I had for the event, my expectations were
+exceeded. For one, the Go team had prepared really well and invested a lot in
+making the event that much more enjoyable for everyone. There was a very fun
+presentation that went over all the contributing steps quickly. There was a
+dashboard made for the event, where everyone's successfully completed steps
+were rewarded with points towards a global score. That made it into a very
+collaborative and social event! Finally, and most importantly, they were Go
+team members like Brad Fitzpatrick behind the scenes, helping review CLs
+promptly! That meant the CLs that were submitted received reviews quickly, with
+actionable next steps, so everyone could move forward and learn more.
+
+I originally anticipated the event to be somewhat dull, in that the
+contribution steps are extremely simple to follow. However, I found that wasn't
+always the case, and I was able to use my expertise in Go to help out people
+who got stuck in various unexpected places. It turns out, the real world is
+filled with edge cases. For instance, someone had two git emails, one personal
+and another for work. There was a delay with signing the CLA for the work
+email, so they tried to use their personal email instead. That meant each
+commit had to be amended to use the right email, something the tools didn't
+take into account. (Luckily, there is a troubleshooting section in the
+contribution guide covering this exact issue!) There were other subtle mistakes
+or environment misconfiguration that some people ran into, because having more
+than one Go installation was a bit unusual. Sometimes, the GOROOT environment
+variable had to be explicitly set, temporarily, to get godoc to show changes in
+the right standard library (I was tongue-in-cheek looking over my shoulder to
+check for Dave Cheney as I uttered those words).
+
+Overall, I oversaw a few new gophers make their first Go contributions. They
+sent the CLs, responded to review feedback, made edits, iterated until everyone
+was happy, and eventually saw their first Go contributions get merged to
+master! It was very rewarding to see the happiness on their faces, because the
+joy of making one's first contribution is something I can relate to myself. It
+was also great to be able to help them out, and explain tricky situations that
+they sometimes found themselves. From what I can tell, many happy gophers
+walked away from the event, myself included!
+
+** Photos from the event
+
+.image contributor-workshop/image2.jpg
+.image contributor-workshop/image4.jpg
+.image contributor-workshop/image5.jpg
+.image contributor-workshop/image8.jpg
+.image contributor-workshop/image14.jpg
+.image contributor-workshop/image18.jpg
+.image contributor-workshop/image20.jpg
+.image contributor-workshop/image21.jpg
+
+Photos by Sameer Ajmani & Steve Francia
diff --git a/content/contributor-workshop/image1.png b/content/contributor-workshop/image1.png
new file mode 100755
index 0000000..4985756
--- /dev/null
+++ b/content/contributor-workshop/image1.png
Binary files differ
diff --git a/content/contributor-workshop/image10.png b/content/contributor-workshop/image10.png
new file mode 100755
index 0000000..34693fc
--- /dev/null
+++ b/content/contributor-workshop/image10.png
Binary files differ
diff --git a/content/contributor-workshop/image11.png b/content/contributor-workshop/image11.png
new file mode 100755
index 0000000..7925273
--- /dev/null
+++ b/content/contributor-workshop/image11.png
Binary files differ
diff --git a/content/contributor-workshop/image12.png b/content/contributor-workshop/image12.png
new file mode 100755
index 0000000..457b102
--- /dev/null
+++ b/content/contributor-workshop/image12.png
Binary files differ
diff --git a/content/contributor-workshop/image13.png b/content/contributor-workshop/image13.png
new file mode 100755
index 0000000..b6b3b75
--- /dev/null
+++ b/content/contributor-workshop/image13.png
Binary files differ
diff --git a/content/contributor-workshop/image14.jpg b/content/contributor-workshop/image14.jpg
new file mode 100644
index 0000000..78e35f4
--- /dev/null
+++ b/content/contributor-workshop/image14.jpg
Binary files differ
diff --git a/content/contributor-workshop/image15.png b/content/contributor-workshop/image15.png
new file mode 100755
index 0000000..6bd638c
--- /dev/null
+++ b/content/contributor-workshop/image15.png
Binary files differ
diff --git a/content/contributor-workshop/image16.png b/content/contributor-workshop/image16.png
new file mode 100755
index 0000000..83e6919
--- /dev/null
+++ b/content/contributor-workshop/image16.png
Binary files differ
diff --git a/content/contributor-workshop/image17.png b/content/contributor-workshop/image17.png
new file mode 100755
index 0000000..3109972
--- /dev/null
+++ b/content/contributor-workshop/image17.png
Binary files differ
diff --git a/content/contributor-workshop/image18.jpg b/content/contributor-workshop/image18.jpg
new file mode 100644
index 0000000..41a62d0
--- /dev/null
+++ b/content/contributor-workshop/image18.jpg
Binary files differ
diff --git a/content/contributor-workshop/image19.png b/content/contributor-workshop/image19.png
new file mode 100755
index 0000000..e5c3470
--- /dev/null
+++ b/content/contributor-workshop/image19.png
Binary files differ
diff --git a/content/contributor-workshop/image2.jpg b/content/contributor-workshop/image2.jpg
new file mode 100644
index 0000000..e78605c
--- /dev/null
+++ b/content/contributor-workshop/image2.jpg
Binary files differ
diff --git a/content/contributor-workshop/image20.jpg b/content/contributor-workshop/image20.jpg
new file mode 100644
index 0000000..c477609
--- /dev/null
+++ b/content/contributor-workshop/image20.jpg
Binary files differ
diff --git a/content/contributor-workshop/image21.jpg b/content/contributor-workshop/image21.jpg
new file mode 100644
index 0000000..155ea69
--- /dev/null
+++ b/content/contributor-workshop/image21.jpg
Binary files differ
diff --git a/content/contributor-workshop/image22.png b/content/contributor-workshop/image22.png
new file mode 100755
index 0000000..8460e56
--- /dev/null
+++ b/content/contributor-workshop/image22.png
Binary files differ
diff --git a/content/contributor-workshop/image23.png b/content/contributor-workshop/image23.png
new file mode 100755
index 0000000..2cd5e53
--- /dev/null
+++ b/content/contributor-workshop/image23.png
Binary files differ
diff --git a/content/contributor-workshop/image3.png b/content/contributor-workshop/image3.png
new file mode 100755
index 0000000..4374122
--- /dev/null
+++ b/content/contributor-workshop/image3.png
Binary files differ
diff --git a/content/contributor-workshop/image4.jpg b/content/contributor-workshop/image4.jpg
new file mode 100644
index 0000000..b2a1783
--- /dev/null
+++ b/content/contributor-workshop/image4.jpg
Binary files differ
diff --git a/content/contributor-workshop/image5.jpg b/content/contributor-workshop/image5.jpg
new file mode 100644
index 0000000..ef198e8
--- /dev/null
+++ b/content/contributor-workshop/image5.jpg
Binary files differ
diff --git a/content/contributor-workshop/image6.png b/content/contributor-workshop/image6.png
new file mode 100755
index 0000000..7ed45f4
--- /dev/null
+++ b/content/contributor-workshop/image6.png
Binary files differ
diff --git a/content/contributor-workshop/image7.png b/content/contributor-workshop/image7.png
new file mode 100755
index 0000000..60edd58
--- /dev/null
+++ b/content/contributor-workshop/image7.png
Binary files differ
diff --git a/content/contributor-workshop/image8.jpg b/content/contributor-workshop/image8.jpg
new file mode 100644
index 0000000..a5eb553
--- /dev/null
+++ b/content/contributor-workshop/image8.jpg
Binary files differ
diff --git a/content/contributor-workshop/image9.jpg b/content/contributor-workshop/image9.jpg
new file mode 100644
index 0000000..abe4d44
--- /dev/null
+++ b/content/contributor-workshop/image9.jpg
Binary files differ
