git init - tips for newbie open source contributors
Looking for a side project? Contributing to open source can be a great way to meet people and sharpen your software skills. I’d like to share some tips for getting involved with open source from myself and other speakers from Girl Develop It SF’s Women in Open Source Panel hosted by Unity on June 26.
Know the Tools and Terms
Before we dive into the main content, let’s go through an overview of some common terminology. This article is focused on git and GitHub because its the most widely used and has strong open source support — repositories on GitHub are open source by default and you have to pay to keep them private — but it’s a wide world out there and git and Github aren’t the only tools and platforms for open source. SourceForge back in the day was once the market leader too.
- Open source: the original source code is made available and transparent. There are a number of different types of open source licenses (MIT, GNU, Apache, Creative Commons) that stipulate how the code can be modified, redistributed, requirements on making derivative works open source, and whether it can be used for commercial use
- contributor: someone who makes a contribution to an open source project, or a significant contribution
- maintainer or admin: the people who have the “keys” to the codebase, they are able to accept and revert changes
- repository (repo): the project codebase and any supporting materials or conversations attached to it
- git: a distributed version control system for tracking changes and collaborating on projects. Unlike centralized version control systems like CVS or SVN where a master version is kept in a remote, with git everyone keeps a local copy of the repository on their machine
- GitHub: an online community and platform leveraging the git system. Note, there are other platforms such as Gitlab, BitBucket where you can also use git.
- Pull request (PR): an object encapsulating the changeset, comments, and revisions when you submit a contribution to a repository. Before your changes get merged into the master branch, they usually undergo a review process
- (Code) review: when a peer or maintainer looks over your changes before your submission gets incorporated into the repo
- unit test: a small, independent testable of the code’s functionality. Usually part of an automated continuous integration process and runs after a new build, prior to code getting merged
People confuse Git and GitHub, but they’re two different things. Git is a version control system, and GitHub is a place where people use git to manage open source projects. — Frances Coronel
Just because something is open source doesn’t mean it’s free. For example, you have to purchase a license to use MySQL in a commercial environment. Open source also doesn’t mean that the code is a democracy. — LizTheDeveloper
Map out your goals
Ask yourself why “what are the reasons why I want to get involved with open source”. Is it to understand the inner workings of how large (or small) scale software projects operate? To gain experience with real-world software development practices? To work on a team project and how to collaborate in a distributed environment? To build your portfolio? (We’ll cover the last point in more detail a future blog post.) All of the above or more?
Once you’ve identified your motivations, the next step is to find aligned communities and projects that can support your growth. We heard a variety of origin stories from our panelists.
My foray into open source was incidental and wasn’t a contribution to a traditional code repository. I co-developed new curriculum and original exercises for Girl Develop It by leveraging open sourced material from other GDI chapters and added the new content to GDI San Francisco’s open source curriculum at teaching-materials.org. After becoming a maintainer and admin on teaching-materials.org, I also joined the ShelterTech volunteer team on the AskDarcel web app (repo link) as a front-end engineer, helping build the most reliable, up-to-date online database of services available to homeless and underserved communities in San Francisco.
What attracted me to ShelterTech was the opportunity to use my technical skills to solve a problem I cared about and give back to the local community — it was happenstance that the codebase was also an open source project. I also wanted to keep practicing hands-on coding (my full time job is product design), learn React, and stay up to date on web development.
With Open Source, you get exposure to software engineering practices like code reviews, plus feedback on docs, testing and style. When you work on solo projects in school, there isn’t as much of a driving factor explain the thought process or information contained in your head with others. Working in open source teaches you to develop code communication and collaboration skills. — Truc Nguyen
LizTheDeveloper’s first experience with open source — after 10 years in the tech industry as a developer — was starting Girl Develop It’s curriculum site! Now she maintains an open source curriculum as the CTO of Enki.
Frances Coronel has been active in all aspects of open source as a maintainer, contributor, backer, organization lead, etc. She used open source to practice contributing code in a collaborative environment and to mature her own coding practice.
Alyssa Kwan got into open source because out of her deep curiosity on how compilers worked. She wasn’t content with accepting tools as a black box and learned about compilers not as a theoretical class — but by reading and line by line dissection of the source code of an open source VM project and seeing its nuts and bolts.
I am a manager by training and a self taught software engineer. Open source is how I developed deep engineering knowledge and learned compiler theory. — Alyssa Kwan
Find a supportive community
Open source is about the community. Code is just an artifact.
So now, you’re ready to get started. But what next? And where? opensource.guide has great tips for first timers. If you’re part of a local community, check out meetups and civic tech projects such as Code for America Brigade.
If you’re a newbie, it’s important to find a supportive open source community that can help you grow. Look for communities that have a code of conduct and active maintainers. If you see an experienced or active contributor who gives good feedback on code reviews, be proactive and message them to ask for feedback or mentorship. Most people in open source volunteer out of passion and likely they’ll be flattered you noticed. In the worst case, they’re too busy.
Find the pockets that are good. Pursue the meaningful relationships; feed the relationships that feel good. — LizTheDeveloper
Hopefully you won’t encounter too many haters, but if you’re in a situation where you’re honestly trying your best but the community isn’t giving something back in return — you might have to cut your losses and let go. In other cases, you might decide to stay and become an agent of change if you truly believe the culture can improve and the “good pockets” can overcome the negativity.
If you find a community that is toxic, you just have to move on. — Alyssa Kwan
It’s a personal choice, but try to avoid investing energy into a project that isn’t supporting you or you don’t see a future in. A supportive community should provide the resources for a beginner to succeed.
Figure out how to dive in
When you’re evaluating a project, checking out the contribution guidelines or README is a good place to begin. When perusing Github repos, look for projects with a community profile which includes a scorecard on how well the project abides to recommended community standards.
Look through the issues list and seek out the beginner friendly issues or bug fixes to work on if they’re labeled.
For example, Girl Develop It’s open source repository provides a wiki with contribution tips, example templates, and lots of other documentation and tools for folks who want to add to or update our Open Source curriculum! Our issues are sorted and tagged that the newbie-friendly ones are easy to find.
However, newly formed communities might not have reached the stage of maturity where they’ve documented best practices yet — it doesn’t mean it it’s not worth trying.
Even if there isn’t a list of changes to make, there’s usually a communication channel to reach the maintainers. You can always ask them. It’s not always written down, but they usually have an idea of where they want the project to go. — Alyssa Kwan
In these cases, a good litmus test is to contact a maintainer or lead contributor and ask them to walk through the codebase with you. Offer to go through the onboarding process and take notes along the way. Chances are if you get lost or confused going through it with an expert, someone else picking up the project with no help will too. Your first contribution can be documenting and updating the starting material such as a README.md. You could make an impact right away by improving the onboarding process for the next person who joins.
Another approach is to go through an existing issues list or propose a small project of your own.
Keeping the momentum going
Once you’ve made your first contribution, what next? How do you respond to the feedback? When beginners make mistakes or trip up, the feedback shouldn’t be purely critical without suggesting ways to improve. If that happens, turn it back on the reviewer and ask them for tips on conventions, best practices, or how it could be done better. We’re all in it together.
As ShelterTech team member, I’m fortunate enough to get help from volunteers who are engineers by profession, patient, and enjoy mentoring. As an added benefit of being part of a local project, we often meet together in person for jam sessions and I’m able to pair program and get synchronous feedback.
Bugs and outages shouldn’t result in finger pointing at individuals, because it’s typically a failure of the process itself. If a change like that gets past testing, staging, code review, etc, then the system needs to be addressed. It’s everyone’s responsibility. — Truc Nguyen
Luckily, I’ve never been bullied or harassed on the projects I’ve worked on, but a different form of discouragement can be… *radio silence*. What do you do people aren’t doesn’t responding to your PRs or efforts? Don’t take it personally, sometimes people forget or fall behind! As as a maintainer, I haven’t been on top of reviewing issues all the time. Be persistent and follow up.
It can be discouraging when you make an open source edit and it’s not acknowledged. Sometimes you have to chase down or remind the admins, because they’re busy. As an admin of an open source project now, I try to be conscious of that. — Truc Nguyen
A great community enshrines best practices into their process to ensure the sustainability of the project and makes sure there’s proper resourcing, accountability, and succession planning. One thing to recognize is the open source community is often built on volunteer work. As you start to invest more of your own time and effort, start to scope out how the project is going to be maintained for long-term success. Is the codebase well documented? Are the maintainers active and responsive to feedback? Is there good knowledge sharing amongst the community? If a core member gets hit by a bus, will the project survive? How can we plan for the uncertain?
Not all contributions have to be “code changes”
You don’t have to code to be a good citizen of an open source community. There are a variety of ways to contribute including technical writing and content changes. Updating documentation sometimes needs the most love.
[Comments and non-code] contributions are valuable to the community and maintainers. — Alyssa Kwan
Your first change doesn’t have to be groundbreaking — we all have to start somewhere and that first step could be fixing a typo or adding more comments to the code, which also helps you learn get familiar with the project. It’s rare that you’ll start a project from scratch, so the detective skills required to get up to speed and navigate a new project are transferrable to jobs in industry or picking up your next OSS project.
Another great way to ramp up your knowledge is to use the open source product or technology yourself as a consumer. By going through the experience as the end user, you could add value by logging issues, bug reports, or provide feedback on how to improve the usability of the tool and supporting resources— it doesn’t necessarily need to have a UI.
Depending on how involved you get and your understanding of the codebase or technical design, you could also review and comment on PRs, draft design docs, and help plan the development roadmap. Maybe there isn’t a roadmap, prioritized issues, or documented vision. If you’re a more opportunistic product-oriented type person or organized project manager, you could work with the leads on translating their vision into workable milestones and breaking down high level initiatives into tasks.
Don’t be afraid to suggest new ways to get involved and it never hurts to ask!
Additional Resources
If you’re in San Francisco and looking for a newbie-friendly place to get started with or boost your coding journey, check out our Meetup to learn about upcoming workshops and events!
- Code & Coffee: Hacktoberfest Edition | Tuesday, October 16, 2018 from 6:30pm — 8:30pm
- Open Source Curriculum Hack Night for Hacktoberfest | Tuesday, October 23, 2018 from 6pm — 9pm
A highly active and accessible project to get started on is guide.freecodecamp.org, which has 1789 open PRs, and over 6000 closed. There are contributing guidelines, and a code of conduct, via Frances Coronel
Github’s showcase on projects great for new contributors
First timers only, a resource for making your first commit and discovering newbie issues
One of our GDI teachers Eva Gabriela Zamudio, wrote a helpful Guide to merging Git repositories
