Skip to content

Commit 00ff653

Browse files
gr2mjanl
gr2m
authored and
janl
committed
feat(blog): Starter issues
1 parent e78c772 commit 00ff653

File tree

2 files changed

+157
-0
lines changed

2 files changed

+157
-0
lines changed

‎_config.yml

+1
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ paginate: 10
1717
# 404
1818
gems:
1919
- jekyll-redirect-from
20+
- jekyll-paginate
2021

2122
sub-navigation:
2223
- title: What is Hoodie?

‎_posts/2016-02-18-starter-issues.md

+156
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
3+
title: Starter Issues
4+
author: Gregor
5+
layout: blog-post
6+
comments: true
7+
8+
---
9+
10+
Every open source project loves new contributors. But — and this is something we learned at Hoodie — there are lots and lots of people who would love to contribute to Open Source, but don’t know how.
11+
12+
So what is missing? There is **a difference between welcoming Pull Requests and creating a contributor-friendly community**. One thing that is working out very well for us are “starter” issues.
13+
14+
## The extra mile
15+
16+
Putting a “starter” label on an issue is Hoodie’s red carpet that we roll out for new and existing contributors. Here is an [example “starter” issue](https://github.com/hoodiehq/hoodie-server-account/issues/81). We maintain a list of open starter issues at [http://go.hood.ie/hoodie-starter-issues](http://go.hood.ie/hoodie-starter-issues "Hoodie Starter Issues").
17+
18+
It might look like a lot of work compared to creating an issue that just states the problem, but you get faster at creating these once you get the hang of it. Plus, “starter” issues are often created as follow ups to quick issues created without much description. And the result is more than worth so small extra time investment.
19+
20+
The most important thing is the message an issue sends to someone who is new to the project. It shows that **we clearly care about people coming here**, that **we want them to succeed** and that **we are here to help**. It’s about people who want to contribute, and not about the project.
21+
22+
## Step by Step
23+
24+
<iframe width="560" height="315" src="https://www.youtube.com/embed/JhC7232lxVQ" frameborder="0" allowfullscreen></iframe>
25+
26+
<small>Pro Tip from [@kentcdodds](https://github.com/kentcdodds) after watching this video: use the “y” key to for getting a link to the file at the latest commit by hash.</small>
27+
28+
First, **explain what the situation is right now**, and **how it will look once the issue is closed**. This can be about a bug that must be fixed, about a feature that needs to be implemented, about a typo in the README, about a missing test…, whatever needs to be done.
29+
30+
After that comes **the step-by-step list of tasks**. We like to start by adding a link to the free video series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github) for people who have never started a Pull Request before, to get everyone on the same page.
31+
32+
The first actionable item is to **claim the issue**
33+
34+
<pre><code class="language-none">
35+
- [ ] claim this issue (assign yourself or comment below)
36+
</code></pre>
37+
38+
Once someone claimed the issue, we replace the item with something like
39+
40+
<pre><code class="language-none">
41+
- [x] claim this issue (@myusername)
42+
</code></pre>
43+
44+
If the issue involves writing code, then we link to a description on how to setup the repository and how to run tests
45+
46+
<pre><code class="language-none">
47+
- [ ] [Setup repository locally](url-here) and make sure
48+
that all tests pass
49+
</code></pre>
50+
51+
If the issue involves an update to the *README.md* file, then this is the next item, something like this
52+
53+
<pre><code class="language-none">
54+
- [ ] update the [README](link-to-readme-section): add
55+
`myLib.myMethod` in the same format the other APIs
56+
are documented
57+
</code></pre>
58+
59+
At Hoodie, we follow [Commit Message Conventions](https://github.com/hoodiehq/hoodie/blob/master/CONTRIBUTING.md#commit-message-conventions). Instead of explaining why and how, we make actionable items for the separate commits we’d like to have
60+
61+
<pre><code class="language-none">
62+
- [ ] Commit with `docs(README): myLib.myMethod`
63+
</code></pre>
64+
65+
Once the first commit is ready, it’s time to start the Pull Request. Even though we link the tutorial on how to contribute to open source above, we do it again, because it doesn’t hurt. We also give congratulations if this is going to be the first Pull Request for someone, because it means a lot to us :)
66+
67+
<pre><code class="language-none">
68+
- [ ] Start a Pull Request. Set description to `closes #123`
69+
If this is your first, welcome :tada: :smile:
70+
[Here is a great tutorial](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
71+
on how to send a pull request)
72+
</code></pre>
73+
74+
Once the PR is created, we check all the above boxes and replace the above item with something like
75+
76+
<pre><code class="language-none">
77+
- [x] Start a Pull Request (#123)
78+
</code></pre>
79+
80+
where *#123* is the number of the Pull Request. GitHub will automatically create a link to the Pull Request here.
81+
82+
If this issue is about code, a test needs to be written or adapted. We give guidance where the test needs to be added, ideally like to the files / lines
83+
84+
<pre><code class="language-none">
85+
- [ ] Create a file `/test/unti/my-method-test.js` in
86+
[/test/unit](https://github.com/myuser/mylib/tree/master/test/unit).
87+
See [/test/unit/my-other-method-test.js](https://github.com/myuser/mylib/tree/master/test/unit/other-method-test.js)
88+
for comparison
89+
- [ ] Add a check that `myLib.myMethod` is a function in [/test/integration/constructor-test.js](https://github.com/myuser/mylib/tree/master/test/integration/constructor-test.js)
90+
</code></pre>
91+
92+
Then we ask the contributor to commit and push the tests. This way the commit will trigger our continuous integration tests on [Travis CI](https://travis-ci.org) and will add a red <span style="color: #F00">**×**</span> to the commit, **so we can be sure that tests are failing as expected**. Here’s [an example](https://github.com/hoodiehq/pouchdb-hoodie-api/pull/100/commits) of what I mean.
93+
94+
<pre><code class="language-none">
95+
- [ ] Make sure that tests fail when run with `npm test`.
96+
Commit with `test: myLib.myMethod` and push
97+
</code></pre>
98+
99+
Now comes the fun part: **Writing the code!** We use a single item on the list to describe what the contributor should be doing. If helpful, we link to the right place and explain how the feature / bug fix can be implemented. But it is okay to keep it short and leave something for the contributor to figure out, that’s what’s fun after all ;) — And at this point the contributor should feel comfortable to ask for help if they get stuck. So often time we do:
100+
101+
<pre><code class="language-none">
102+
- [ ] Implement :)
103+
- [ ] Make sure tests pass when run with `npm test`.
104+
Commit with `feat: myLib.myMethod` and push
105+
</code></pre>
106+
107+
**The work is done**. Now someone else needs to review and merge the work.
108+
109+
<pre><code class="language-none">
110+
- [ ] Someone else: review & merge
111+
</code></pre>
112+
113+
During the review it may turn out that something is not quite right, so the pull request needs amendments. The contributor can add more commits as long as needed. Once they are done, they can either squash the commits themselves if they [know how to do it](https://www.google.com/url?q=https://egghead.io/lessons/javascript-how-to-squash-multiple-git-commits?series%3Dhow-to-contribute-to-an-open-source-project-on-github&amp;sa=D&amp;ust=1456225013529000&amp;usg=AFQjCNG4f-8HgRkaWUOjXcrMIcXS_cyyTw), or the reviewer does it for them.
114+
115+
It is very important that when the reviewer is cleaning up the commit messages, that they **keep the original author**. Nothing is more disappointing than a first pull request accidentally “stolen” by a reviewer. A custom author can be set with:
116+
117+
<pre><code class="language-none">
118+
git commit --author="Pat Doe <[email protected]>"
119+
</code></pre>
120+
121+
At the end of the issue we add ways to contact us, usually something like this:
122+
123+
> Ping us in the [Hoodie Chat](http://hood.ie/chat/) or on
124+
[Twitter](https://twitter.com/hoodiehq/) if you have any questions :)
125+
126+
Please let us know if you have any suggestions on how we can further improve our starter issues — we love hearing from you &lt;3
127+
128+
### Beyond the extra mile
129+
130+
If the issue involves writing a test, then you, the issue author, can create it yourself. Comment the test out and push it to master. **Then instead of asking the new contributor to figure out how to write the test, all the need to do is to uncomment it and see the tests fail**. This idea comes from Kent C. Dodds who wrote about it in his piece on
131+
[First Timers Only](https://medium.com/@kentcdodds/first-timers-only-78281ea47455) — one of our favourites :)
132+
133+
### Benefits
134+
135+
The benefits of starter issues go both ways. For people new to the project, it **lowers the barrier** and **makes contributing more fun**. For maintainers, it’s **a great way to empower more people** to do code reviews, as they have a list they can follow and check items off of. More importantly, it is our hope that **creating starter issues will become a part of the Open Source culture** and a great format for community engagement.
136+
137+
## See also
138+
139+
- [Making Your First Pull Request](http://www.charlotteis.co.uk/making-your-first-pull-request/)
140+
- [Contribute to Open Source](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
141+
- [Contributing to Hoodie](http://hood.ie/blog/contributing-to-hoodie.html)
142+
143+
## Thanks
144+
145+
I’d like to thank
146+
147+
- [Alex](https://github.com/espy)
148+
- [Charlotte](https://github.com/charlotteis)
149+
- [Jan](https://github.com/janl)
150+
- [Jenn](https://github.com/renrutnnej)
151+
- [Kim](https://github.com/kmcrayton7)
152+
- [Lewis](https://github.com/lewiscowper)
153+
- [Patricia](https://github.com/patriciagarcia)
154+
- [Kent](https://github.com/kentcdodds)
155+
156+
for their input reviewing this post!

0 commit comments

Comments
 (0)