The tangled ways of open source and how to master it: GitHub shares its wisdom
Business Concept image via Shutterstock
“Open source is complicated, especially for newcomers,” GitHub said in its roadmap for Open Source Guides. Open Source Guides is a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to open source.
Open Source Guides is a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. The first set was created and curated by GitHub, along with input from outside community reviewers, but they are not exclusive to GitHub products.
GitHub’s goal is “to aggregate community best practices,” not what they (or any other individual or entity) think is best. The reason behind Open Source Guides is that they felt that there weren’t enough resources for people creating open source projects.
We’d like this to be a safe space to talk about what’s hard, what’s scary, and what’s simply confusing about running open source projects.
The first set of guides includes the following:
This guide has five sections:
- Why contribute to open source. Some possible reasons are: to improve existing skills, meet people who are interested in similar things, find mentors and teach others, build public artifacts that help you grow a reputation, learn people skills and it’s empowering to be able to make changes, even small ones.
- What it means to contribute. “A common misconception about contributing to open source is that you need to contribute code. In fact, it’s often the non-code parts of a project that are most neglected or overlooked. You’ll do the project a huge favor by offering to pitch in with non-code contributions,” GitHub wrote in the guide.
- Orienting yourself to a new project. Don’t underestimate the importance of understanding the anatomy of an open source project.
- Finding a project to contribute to. GitHub encourages you to “start by thinking about the projects you already use or want to use. The projects you’ll actively contribute to are the ones you find yourself coming back to.”
- How to submit a contribution. Your ideas will be better understood if you give context, do your homework before you open an issue or pull request, or ask a question in chat, keep requests short and direct, keep all communication public, respect community decisions and ask questions. Above all, keep it classy.
- What happens after you submit a contribution. GitHub says that after you submit a contribution, one of the following will happen: you don’t get a response, someone requests changes to your contribution, your contribution doesn’t get accepted or your contribution gets accepted.
This guide also has five sections:
- The what and why of open source. This part of the guide tries to answer the following questions: What does “open source” mean? Why do people open source their work? and Does open source mean “free of charge”?
- Should I launch my own open source project? First, you need to set your goals. “If your goal is to learn how to collaborate with others or understand how open source works, consider contributing to an existing project.”
- Launching your own open source project. When you decide to launch your own open source project, remember that every project should include the following documentation:
- Naming and branding your project. It is recommended to choose a name that is “easy to remember and, ideally, gives some idea of what the project does.” You should avoid name conflicts and keep in mind that how you write (and code) affects your brand.
- Your pre-launch checklist. “Ready to open source your project? Here’s a checklist to help. Check all the boxes? You’re ready to go! Click ‘publish’ and pat yourself on the back.”
The first set contains 10 guides. In addition to the ones mentioned above, you can also read about:
- Finding users for your project. This guide includes the following sections: Spreading the word, figure out your message, help people find and follow your project, go where your project’s audience is (online), go where your project’s audience is (offline) and build a reputation.
- Building welcoming communities. This guide includes the following sections: Setting your project up for success, growing your community and resolving conflicts.
- Best practices for maintainers. This guide includes the following sections: What does it mean to be a maintainer, documenting your processes, learning to say no, leverage your community, bring in the robots and it’s okay to hit pause.
- Leadership and governance. This guide includes the following sections: What are examples of formal roles used in open source projects, how do I formalize these leadership roles, when should I give someone commit access, what are some of the common governance structures for open source projects, do I need governance docs when I launch my project, what happens if corporate employees start submitting contributions and do I need a legal entity to support my project?
- Getting paid for open source work. This guide includes the following sections: Why some people seek financial support, funding your own time, finding funding for your project and building a case for financial support.
- Your code of conduct. This guide includes the following sections: Why do I need a code of conduct, establishing a code of conduct, deciding how you’ll enforce your code of conduct and enforcing your code of conduct.
- Open source metrics. This guide includes the following sections: Why measure anything, discovery, usage, retention and maintainer activity.
- The legal side of open source. This guide includes the following sections: Why do people care so much about the legal side of open source, are public GitHub projects open source, just give me a TL;DR on what I need to protect my project, which open source license is appropriate for my project, what if I want to change the license of my project, does my project need an additional contributor agreement and what does my company’s legal team need to know?
In the second half of 2017, GitHub plans to “improve upon existing content and start to focus on additional content for open source consumers and contributors.”
Continue to improve the content for open source creators
Improve guide discoverability for open source creators
Expand the Open Source Guides to include content for open source consumers
Open Source Guides is open to community feedback. The content will remain open source for anyone to use.