Open Source Best Practices

#opensource #webdev #computerscience #codenewbie

Open source has always been an amazing place to learn, collaborate, contribute and build new stuff. Having been a part of many open source communities, events, and organizations, I have realized that people are slowly and steadily understanding the potential of open source as the future of technology. However, they often get confused regarding the workflow in open source projects and communities and end up doing mistakes that lead to not-so-good contributions and thus, often get stuck in a loop of code reviews and changes before they ever make a meaningful or effective contribution to a project.

Note: This article can only be helpful if you are familiar with the basic git terminology and have an understanding of the initial workflow of using git and GitHub.

Read here for more info: How to Contribute to Open Source

Here are some of the best practices that you can take up for your next contribution!

Culture and Communication

Open source communities are a big pool of people from different social and ethnic backgrounds, races, religions, and languages. Thus, the best way to walk along with everyone would be to practice empathy.

Always ensure that your tone stays friendly and respectful in a discussion.
Try to adapt your language to non-native English speakers as they might find the environment challenging or intimidating at times.
Stay humble and modest. None of us know everything, we are all learning. Some developers might need help with something that is very basic, be kind, and extend a helping hand whenever you can.

Try to learn yourself as much as possible, devote time to explore the codebase, and attempt to understand things before you ask a question on a public channel or open an issue. Even though, if you seem to be stuck with anything, do not hesitate to ask questions to fellow developers. Likewise, do respect the space and the questions put up by others.
Be nice and welcoming. Appreciate your fellow developers and contributors of they did a good job. Extend a " please " or " thank you " in a discussion to express politeness and generosity.

Communication Channels

Most of the open-source communities have their private or public communication channels like Slack, Discord, Gitter, etc as chat is a great way to connect with other contributors and maintainers.

To use these channels effectively, contributors should try to follow the below points:

Do not switch to private communication with a maintainer or fellow contributor until and unless very necessary, as this shuts out other contributors who might be facing the same issues and can get help straight away by reading the earlier conversation.
Do not discuss feature requests and bug reports over chat, as they are best handled over GitHub or Issue Trackers.

Feature Requests and Bug Reports

Feature Requests and bug reports are best handled over GitHub, but one must follow certain steps to use them constructively:

For any bug or feature, no matter how small or big, open an issue with all the necessary details, and don't forget to indicate if you're interested in working on it.
Try to include all relevant information when you submit an issue so as to help others understand it easily. Include links, information about the code that has to be changed, and screenshots wherever necessary.
Break down a big feature request into smaller issues, so that more than one contributor can simultaneously work on it.
Always remember to add steps to reproduce the bug that you are reporting while submitting a bug report.

Most open source projects use Issue templates for Feature Requests and Bug Reports. These can be used as a reference to the details that should be mentioned while submitting an issue.

Development

Once you have decided on the open-source project that you want to contribute to, the first step, to begin with, would be to set up the project on your local machine and run it. The steps are usually defined in the README.md file. The next step would be to go through the branch policies and contributing guidelines of that project, these can be easily found inside the CONTRIBUTING.md file. Once, you are done, you can begin with the changes in the project.

Even meanwhile development, if you have any doubts or come across any challenges, feel free to ask questions from the maintainers or the fellow contributors. (You can use either the communication channel or keep the conversation over GitHub.)

Commits and Pull Requests

Most first-time contributors are hesitant or fearful of making a PR, although, there's no need to be afraid, just keep a few things in mind while making your PR to get a quick code review and feedback:

Write meaningful commit messages, that convey what changes have been done. For example -

Ensure that you use the minimum number of commits for a change. In case, you have a lot of commits for a small fix, squash them before making a PR.

Do only the changes in the PR that were mentioned in the issue. Do not change anything else that is not relevant to that particular issue.
Always link your PR to the issue that it fixes. Learn how to do it here.

Make PRs from your own forks (even if you have the rights to the repo, do not create new branches, develop on your own branches).
State the actual enhancements or changes done in the PR rather than just mentioning Fixes #1. Refer to the PR template for details to be mentioned, if the project has one.
Remember to add a screenshot or video if you have made any UI changes. This boosts up the review process exponentially.

Help the reviewers solve merge conflicts if any. Read more about merge conflicts here.

Documentation

Everything in open-source happens through an exchange of words. Thus, documentation stands as a crucial step to provide information about your contribution.

Documentation is a continuous effort at every step of software development.

Add information on the new technologies, frameworks, libraries, and the code into the code itself via comments and into documentation files e.g. into the README.md or /docs folder.
Always help to keep documentation up to date and make it easy for new contributors to join the project.

Last but not the least, open-source is a collaboration between many different people with many different priorities, and sometimes, you got to wait until the right time. The other people working on a project likely have very different lives than you do, and their priorities may not match up with yours. Work projects, vacations, and family are some of the most common things that can push back a response to your needs and patience is the best way to deal with it. Since great things are worth the wait, never mind the delay.

This is all that I learned along my journey in open-source. I hope that the practices mentioned above take you closer to your next (effective) open-source contribution and help you fulfill your chance to give back to the community, one commit at a time!

If you find this insightful, do let me know your views in the comments. Also, any kind of feedback is welcome. In case you want to connect with me, follow the links below:

LinkedIn | GitHub | Twitter | StackOverflow