Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
How to create a shout out blog post
Giving a "shout-out" means to give recognition to a contributor of Hoodie’s community. Giving recognition is very important to us and we want to get better at it, but it also comes with several pitfalls that we have to keep in mind
- Every contribution counts. There is a human behind every contribution, and behind every human is a story. We do not judge if one contribution is worth more than another, it does not matter. It’s not about creating a competition of who contributes the most, but about creating a space where everyone is appreciated.
- While many of us are good at automating things, showing appreciation is not something we want to automate, ever. It is true that there is lots of room for improvement to help us find out who contributed something, but in the end, there should be a human being from the Hoodie community who uses the tools and decides how to phrase the shout-outs. We can write tools to make contributions more visible, but appreciation cannot be automated, otherwise it looses its value.
Read more about this and other topics on the Wecloming Communities blog post.
Here is an example shout-out blog post: http://hood.ie/blog/shoutouts-week-24.html
The current state of creating a shout-out blog post is pretty tedious. We have a tool that helps a little bit, but it still requires a lot of labors. Our goal is to eventually follow a regular schedule, but we don’t yet have a team in charge for that, and we probably need to improve the tools. Right now it takes me about 2h to create a shout out blog post
Kinds of contributions
- merged pull requests, extra shout-out to first time contributors, double shout-out to first-time Open Source contributors
- comments (bug reports, helpful comments)
We currently only have one tool that helps us, github-shoutouts, follow the instructions in the README to install it. Create a GitHub token, give it a description like "GitHub Shoutouts", you don’t need to give it any access. Once you create it copy the token somewhere safe, you will need it later.
Run the script like this
SHOUTOUT_GH_TOKEN=<your token here> github-shoutouts hoodiehq
It will ask you to set the starting date/time. Set it to the date when the last shout-out blog post was published.
When the script finished, it will create a file like
shoutouts-2016-07-12.md in the current directory you run it in. This is your starting point
If you have any ideas on how we cam improve this tool, create an issue. Your ideas are more than welcome.
Step by Step
shoutouts-*.mdfile created by
Add the outline of the blog post to the top of the file (or create a new one, as you like)
<summary here> ### Backers and Sponsors List current backers and sponsors from https://opencollective.com/hoodie ### New Contributors <intro and list of new contributors sorted by name. Start with first-time Open Source contributors, then list new contributors to Hoodie> ### New Contributions to Hoodie <list of contributions by contributor, sorted by name> ### Thanks to our maintainers Thanks to our maintainers, who review all kinds of new contributions before they make their way to our code, documentation or website <3 <list of people who reviewed pull request and help maintain the community in other ways> ### Special thanks <give extra shoutouts to things you want to highlight, see the [Special Thanks section of this shout out blog post](http://hood.ie/blog/shoutouts-week-24.html) as an example. Don’t worry about repeating yourself. Ask around if people have suggestions to whom they want to give shout outs to and for what. This is your stage, trust your guts, there is little you can make wrong here. And if you realise you forgot someone, make sure they get a shout out in the next blog post
Open Hoodie’s OpenCollective Page and list all current backers & sponsors in the Backers and Sponsors section.
First PR on the hoodie project!in the
shoutouts-*.mdfile. These are the people who contributed to Hoodie for the first time. To find out if their contribution was the the first on GitHub in general, go to http://firstpr.me/ and enter their username. Fill in their contributions to the
### New Contributorssection. Also check if some of the new backers and sponsors are new to the Hoodie community, in that case welcome them here as well! If the GitHub users provided their real names on their GitHub profile page, use them in the shoutouts, otherwise use the username.
shoutouts-*.mdfile. Everyone who reviewed a pull request helped to maintain the Hoodie community. List them all in the
Thanks to our maintainerssection. Lookup their names and use that.
Now go through all contributors, look for
landed. Write a sentence or two for everyone who landed a pull request and link to the pull requests
Ask around in the community what was special in the community since the last shout out blog post and write it down in the
- use emoji. Everything can be better with emoji :) Check out Kent C. Dodds’ all-contributors for ideas what emjoi to use to highlight different contributions