This is a translated version from the Chinese (original) script. The slideshow can be acquired here. For comments, please head to the Chinese version of this post.
Hello everyone, I’m iBug from the University of Science and Technology of China. Today I’ll show you my experiences and tips in participating in open-source projects.
1. What is Open-Source Software?
Open-Source Software (OSS) is a classification of computer software whose source code is freely available. Open-source software always has a license attached to it, which defines the usage of its source code. A few common OSS licenses are GNU General Public License, MIT License, Apache 2.0 License, and the BSD License. Different licenses pose different requirements to users of the source code. For example, GNU GPL requires that any derived work be licensed under the same terms, while MIT License is more permissive on that. Meanwhile, the public availability of the source code enables everyone to participate and commit their contribution.
The original incentive of open-source software was to share knowledge. Software design and programming skills are both knowledge, so the ancestors share them by sharing source code. In an open-source model, every user is part of the community. Everyone can join the development and maintenance work, or help test and audit the code, or chime into the discussions. That’s how open-source software forms its distinctive collaboration model, and its adequate documentation, tutorials as well as discussions provide sufficient information to whoever wants to take part.
Then, why do people choose open-source software?
On the one hand, open-source software is well-audited. Contrary to proprietary software, open-source ones are not audited by a closed group, but rather anyone interested. Anyone can audit the code of any single open-source software, which grants open-source software with its unique transparency. Meanwhile, help from people with experience in security also adds to the overall security of the software.
On the other hand, every open-source software has a surrounding community. The persistence of the community around open-source software makes it perpetual and less likely abandoned. In addition, the variety of people in the community makes every part of the software well-maintained. Besides, the open availability of the source code enables the obtaining of a running software by compiling from source, which brings down the total cost of using it. (It isn’t unconditionally true, though. For example, NGINX sells a “premium version” of the software, NGINX Plus, for a fee.)
Here’s a collection of open-source software that many people recognize, including the TensorFlow ML framework, Windows Calculator, LibreOffice office suite, as well as Debian GNU/Linux operating system. Open-source software exists throughout our daily life and work.
2. My experiences in participating in open-source projects
This is my GitHub profile page. The 6 pinned repositories are:
- TetrisAI: A console Tetris game written in C, with a built-in AI playing mode
- SmokeDetector: I’ll elaborate on this one later
- PyReversi: A GUI reversi game developed with Python and PyQt5. Also has built-in AI to provide a “human vs. computer” mode
- CGadgets and vbsGadgets: As suggested by their names, they’re “gadgets” written in C and VBScript
- OJSandbox: My work from the course Research for newbies, a sandbox implementation for online judgers using Linux technologies like chroot and rlimits.
This is my Stack Overflow profile. I occasionally participate in the regular Q & A activities on Stack Overflow. So far, I have asked 100+ questions and answered 800+, and accrued an aggregate reputation of more than 22.6k. My top few tags include c++, c and python.
My first participation in an open-source project
My first experience took place at markondej/fm_transmitter. I was trying to set up my own FM radio station and loop music when I noticed that the “repeat” command-line option wasn’t working. I confirmed that there was nothing wrong with my Pi and the Raspbian OS on it, so I took a look at the code. It wasn’t hard for me to spot a missing negation in a condition check, so I patched it myself, recompiled the code and verified that my patch was working correctly.
My roommate was right beside me then, and came to help me when he saw me. Under his guidance, I forked the upstream repository, pushed my local changes up, and opened my first pull request. Two days later, the author replied “Thanks for your help” and merged my PR.
My primary participation in another open-source project
Look at the above image again. I anticipate that the icon at bottom-right is the least known one. It’s the logo of the organization Charcoal-SE, whose primary project is SmokeDetector, a headless chatbot that helps the Stack Exchange Network fight off spam.
The bot came into my attention in December 2017, and I was directed to Charcoal HQ after asking about it.
And I dropped into that chat room. Every day I chatted with them and watched the output from SmokeDetector, flagging spam that was reported. The routine continued to early January 2018, when someone noticed a bug with Smokey. I volunteered to take a look at it and fixed it, and fired up my first PR that changed some code (#1441). Since then, I worked hard to study the code of SmokeDetector and continued to submit a steady stream of fixes and improvements. In March 2018, they added me to their list of developers. In June, I was granted direct push access to the repository, indicating that I had been trusted for my proficiency in handling the project.
From SmokeDetector, I started the expansion of my contribution, and sought out for other interesting projects that I could give a hand to. One of them was metasmoke, a web dashboard for SmokeDetector, which is a Rails-based web application itself. Another one was the Charcoal website, hosted on GitHub Pages and built with Jekyll. With what I learned from working on the Charcoal website, I built my own website with Jekyll too, and submitted a PR to the theme that I started with.
Other contributions I’ve made
In addition to code patches, I also opened a series of decent issues, name a few:
- Magisk, a popular root framework for Android. I submitted a suggestion to improve its install script, which was accepted later. (#512)
- wtfpython, a collection of interesting Python constructs. I pointed out a mistake in the document (#81)
- BaiduPCS-Go, a command-line client for Baidu Net Disk. I reported a bug. (#402)
- I also opened a few trivial issues in repositories that I’m familiar with, so that more people could learn them by participating in Hacktoberfest.
Besides, I’m also an active participant in various discussions, as well as Stack Overflow. I enjoy helping others with my knowledge.
My personal top ★ repo is pac, which originated from a discussion on another repository. People had a strong need for specific functionality, which was implementable just with a PAC script, so I wrote one and shared it with the pac repo, which has accumulated a total of 24 stars by the time of writing this article. There’s one thing we can know for sure, that its star amount wasn’t for its complexity or use of high-tech, but rather its usefulness to passers-by. The issues section has also received a few questions, all of which have been answered by me.
What I’ve learned
I’d say pretty much the primary thing I’ve learned from those experiences is teamwork. Teamwork is very inclusive and involves the use of the Git Version Control System (VCS), a consistent coding style and documentation style, as well as the meaning and usage of a Continuous Integration system, and most importantly, the skills of communication.
3. Getting involved by yourself
Before chiming in, you should understand one point that an open-source project is a project, and thus, you have flexible ways of contributing.
-
For software, the most intuitive contribution is to submit code patches, such as bug fixes, enhancements, and test suites.
-
Besides, it’s also a valuable kind of contribution to help improve documentation and tutorials
-
Meanwhile, translating documents into other languages enables more people to participate.
For example, Transifex is a commonly used translation collaboration platform, and it powers many well-known projects like Disqus and SoundCloud.
-
Finally, if you’re not interested in all of the above, you still have the option of contributing supplementary information, like Q & A and bug reports.
So then, what are we going to reap for ourselves?
-
The most direct consequence is that you gained hand-on experiences working on a real-life project.
-
You also practiced your existing skills and learned new ones.
-
You acquired valuable knowledge and wisdom.
-
You can easily show off your hard work on open-source projects.
-
You can stand out from the crowd when applying for opportunities. Apparently, your HR / curator / mentor will more likely give you the offer when they can actually see your work.
An immediate example is my chance of speaking here, which owes a lot to the fact that my open-source achievements can be easily seen and verified by the event host.
Looks rather attractive, right? Then it’s time to set yourself up.
Discover your abilities
The first thing to decide is what you excel at. Say for example, if you’re good at turning ideas into code, or if you’re competent in discovering leak holes, or if you’re innovative at designing, and so on. Specific abilities help you excel at specific tasks.
Find your interest
Then you should find a project of interest. There are a few ways to search for them, listing a few for example:
- A piece of software that you use daily
- An interesting project that you come across, like the trio on the right side of GitHub dashboard
-
Random events that advocate open-source projects like Hacktoberfest, or another long-running one Up For Grabs
- Finally, an innovative idea that could start a new project on its own
If you decide to join an existing project, there are some preliminary checks that I advise you to perform.
- First and foremost, an open-source project must contain a
LICENSE. And it adds up if it has a Code of Conduct as well. - You should also judge the activity of the project, like the time of the last commit, as well as how often project maintainers commit.
- It’s a big bonus if the project has an active community, who can generate many Issues and Pull Requests, both of which are good indicators of project activity.
- Finally, a friendly atmosphere makes discussion more comfortable and constructive.
Effective communication
The most common thing that happens throughout your activity in a project is communicating with others. It’s often worth noting for the sake of the effectiveness of your communication that:
- You’re expected to do researches beforehand by yourself. You should probably avoid asking “how to write code for this”, and at the very least, “I wrote this code and it’s wrong” is a better question.
- Should you need to ask a question like “I wrote this code and it’s wrong”, you must provide enough context and (probably) code for others to identify the problem. Similarly, whatever discussion you’re starting, ensure you’ve enabled others to replicate what you’re describing.
- Keep the discussion straight and on-topic. No one is likely interested in that you wrote the code in Starbucks after an afternoon’s work at the port carrying bricks.
- For public projects, keep the discussion public as well unless there are other reasons not to, like reporting security issues or misbehavior of other community members.
- Respect others should their opinions differ.
After submitting your contribution
It’s time for you to wait for project maintainers to review your contribution and take further action. There are a few outcomes here.
- No one pays any attention to it and your Issue or PR just hangs. Maybe you should simply wait for longer, or perhaps you should have checked the project for recent activity.
- If anyone suggests improvement, it means that others have taken time to review your contribution. You should respect them and respond in time.
- Sometimes the maintainers or the community doesn’t accept your contribution. Don’t panic; see what others think and say, collect them as your own experiences.
- If your contribution gets accepted, then Congratulations!
Epilogue
Whether you’re new to open-source projects or experienced in the field, I hope you can go ahead and carry forward the idea of open-source.
More reading
For comments, please head to the Chinese version of this post.