GitHub 101
- GitHub 101
- GitHub Lingo
- GitHub Issues
- GitHub Pull Requests
This blog series started as a lightning talk at the 2017 PowerShell/DevOps Summit titled “Being an Upstanding Gitizen.”
If you’re a PowerShell user, chances are you’ve heard of GitHub by now. In addition to the many community-driven projects, even Microsoft’s own PowerShell team are doing a ton of their work in open source land. (!!!)
Even if you’ve somehow avoided it up to now, eventually, all of us will be consuming at least one of these open source projects. (Dabbled with VS Code yet? Called Find-Module against the PowerShell Gallery? Tried Pester?) If you use anything in the open source realm, and you:
- Need help, or
- Find a bug, or
- Just think the code should do X when you try to Y,
Guess what? You can do a lot more these days than just complain to your coworkers about how much M$ sucks. ;) It’s easier than ever to be part of the solution.
Open source exists only to encourage people like you to help out.
Reporting bugs, improving documentation, and requesting features are all valuable contributions, even before we discuss writing code. I hope this guide helps you consider stepping out of your comfort zone to pitch in when you find something wrong.
Table of Contents:
Benefits of Source Control
This is a series about the GitHub open source community, from my PowerShell-centric perspective. But I need to briefly advocate for your use of source control in general at $Job, even if you are far removed from open sourcing anything.
Source control is not just a developer thing. If you’ve ever turned your script.ps1 into script.ps1.old, I’m talking to you. Or if you commented out a line of code because you no longer needed it, but were afraid to lose it. Or if you want to preserve and easily browse/compare the history of the project…for your reference, or to help a new hire get up to speed. Or to easily track the development of a new feature without affecting the script.
All of those benefits are realized even before we start thinking about actively collaborating on projects with others.
Having a revision history in a centralized area pays for itself quickly; by taking that step, you’ve positioned yourself well for future enhancements. (Automated tests, continuous deployment, etc.) GitHub is only one option, though, and this series is about contributing to open source projects from others, so I won’t go into detail here. But it’s important enough to say, so if you have questions about it, please ask.
Why I Care
As a Windows ops guy, I didn’t grow up living and breathing open source. I only really got involved the PowerShell community ecosystem on GitHub in the last year or two, and there was a lot of trial and error while I figured out the right way to do things. Well, really, while I figured out a lot of wrong ways.
Lately I’ve found myself in unfamiliar territory: a maintainer of two (1 & 2) open source projects with modest activity. Let me be the first to say, this is a very new challenge for me, and I could be a lot better at it. Consequently, I’ve been spending a lot of time lately reading, learning, and thinking about how to be the best project maintainer I can be.*
* - Preferably without going crazy
The biggest lessons I’ve learned so far:
- There is not enough time in the day.
- People are still new to GitHub.
GOTO 1
There’s no way I’ll ever be able to personally teach every potential new contributor. The best I can do is write this blog series, point people here, hope it helps you to be awesome, and hope you will tell me if anything could be improved upon. Hint, hint.
On Project Diversity
If a project lives in happy fantasy open source land, you can assume the following: The creator believes that diversity in a project, properly focused, will make the project stronger.
Personally speaking, I will never find all the bugs, I will never envision all the use cases, and my writing–both code and English–will never hit the perfect equilibrium of precise yet accessible. (Friends of the blog know I may never grasp the concept of “precise.”) Harnessing the wisdom of the crowd is an incredibly powerful method of optimizing existing work.
Your combination of skills, experience, and perspective is unique. So once more: If it’s on GitHub, your help is wanted!
On Etiquette
Because I’m talking about GitHub in the context of “Being an Upstanding Gitizen,” we still need to step back and talk soft skills. (Yay!)
You found a bug, and you’ve decided to reach out and report it as a new issue. Excellent decision! Keep in mind:
You don’t have to write a single line of code.
If you do, great! But code bases are tough to dive into, and we all have limited time. Just the act of filing a new issue provides value.
Now, hopefully I’m stating the obvious here…but there are some real sub-optimal ways to interact on GitHub, and most of them involve the word “sucks.” This is an open source project, so 9 times out of 10 (99/100?) the owner/maintainer:
- Coded this work on his/her own time to solve a problem
- Provided it at no cost, hoping it would also help others
- Continues to support it for free
That’s not to say you are a burden to the maintainer! You should absolutely still file that issue. Bug reports are very helpful; they’ll make projects stronger, and they’re a helpful reminder that the project is actually being used. Again, the project is open source in the first place because it needs your help.
But while you’re helping out, I hope you also consider the person on the other end. Mind the golden rule, and stay positive–even if the person on the other end is having a bad day. Honestly, the PowerShell GitHub community is really ahead of the curve on this. I find it to be a really encouraging group, which we’re both lucky to have and careful to foster.
Oh, and understand you may not get a response within a business day, because most of these projects aren’t a business. :)
Key Takeaways
- Source control is vital for my IT Ops friends
- It’s not just for developers, and not just for open source
- GitHub is here to stay (even Microsoft is using it), so learn the basics
- Your help is wanted!
- Not just for official Microsoft projects, but anything you find on GitHub
- The PowerShell open source community is a welcoming and positive atmosphere
- Ok, not a perfect record, haha. But shake off the exceptions and stick with it!
Up Next
- Tomorrow, I’ll break down [GitHub Lingo]
- And then we’ll jump into how you should start contributing!