KayodeContributing to open source can be an awesome experience to help you learn, get job opportunities, network with people and also help others at the same time. Kent C. Dodds talks about how open source has been awesome to him here.
This article would provide tips for preparing your GitHub repository for open-source contributions.
It is assumed that you have basic experience with markdown syntax to work with most of the files needed in this article.
Tips and Tricks
Creating your README
The README.md is the entry point to your project when people visit your repository. It should contain:
- the description of the project.
- why the project is useful.
- how to get started.
- relevant information on using the project etc.
Most projects with short documentation would have the README. I’d recommend the same except the documentation is huge, you need to have it somewhere else that can support search, pagination etc.
Writing your Contribution Guideline
To create a contribution guideline, create a [CONTRIBUTING.md](http://CONTRIBUTING.md) at the root of your project and provide information that is necessary for new and old contributors to contribute to your project.
It can include information like:
- the different ways contributors can contribute to the project.
- how contributors can clone the repository on their local machine.
- how contributors can set up the code on their machine for development.
- how contributors can report bugs.
Defining the Code of Conduct
Working with people can be trivial in some cases. Open-source projects are not protected from people with abusive intent. Creating a code of conduct sets a foundation for creating a positive environment for people to contribute without disruption by negative behaviours like sexual harassment, abuse etc.
Create a CODE_OF_CONDUCT.md at the root of your project. Using markdown syntax, the file can contain information about:
- the project community pledge,
- the project community standards,
- enforcement guidelines.
You can adapt the guidelines provided by https://www.contributor-covenant.org/ to create your guideline.
Creating Status Checks
To enforce good development, you can include a form of status check each time a pull request is made to your project. Status check let you know if commits meet the conditions set for the repository. The checks can include continuous integration like:
- units tests
- code coverage
- code quality checks like DeepSource, SonarCloud etc.
GitHub Actions is recommended to trigger jobs or workflow by certain events on your repository.
Protect your Main Branch
Using GitHub, you need to protect your main branch to enforce that certain requirements are met before pushing to the branch. Protecting the branch can also prevent deletion or force pushes to the branch.
To set up protection rules for the main/default branch, ensure you have admin access to the repository then click on Settings > Branches and click on Add branch protection rule:
Then you can configure or select the rules you want active:
To read more about GitHub branch protection rules, you can visit here.
Create Pull Request Templates
To set a foundation for code reviews, you can create a pull request template with sets of required information that you feel is necessary for code review.
To create the template, create a new directory, called .github, and create a new file in the directory called PULL_REQUEST_TEMPLATE.md.
A sample template could look like this:
## Description
Issue closed #(issue)
## Change Type
<!--- This is a comment, you can leave this to give information to the contributor -->
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Minor changes in old functionality
## Checklist
- [ ] My changes are well-tested and commented
- [ ] I reviewed my changes
- [ ] My changes generate no new warnings
Make Use of GitHub Labels
You can utilize GitHub Labels to help create a standard workflow in a repository. You can use labels to categorize issues, pull requests and discussions.
GitHub provides defaults labels with their description, some of which includes:
-
bug: indicates an unexpected problem or unintended behaviours. -
documentation: indicates a need for improvements or additions to documentation. -
duplicate: indicates similar issues, pull requests, or discussions. -
enhancement: indicates a new feature request -
good first issue: indicates a good issue for first-time contributors -
help wanted: indicates that a maintainer wants help on an issue or a pull request. etc
To read more about GitHub Labels, you can visit this documentation.
Create Templates for Issues
Once contributors start noticing and using your project, it is very likely for a number of issues to be created on your repository.
At the time of writing this article, Typescript has over 5000 issues in its repository.
Creating templates for issues is a great way to organize issues on your repository.
To create these templates, create a directory named, ISSUE_TEMPLATE, in the .github directory which is at the root of your project. Then create new markdown files directly to create separate templates.
I will create a sample feature request template in a file called feature_template.md:
<!-- .github/ISSUE_TEMPLATE/feature_template.md -->
---
name: Feature Request
about: Suggest a new idea for this project
labels: enhancement
---
<!-- please fill each section completely -->
## Viability Checklist
- [ ] this wouldn't be breaking change in existing JavaScript
- [ ] this will not change the runtime environment
- [ ] this feature can be implemented with JavaScript
## Suggestion
<!-- A summary of what you are suggesting -->
## Use Case
<!-- How do you think this feature would be useful -->
Conclusion
Open source is not restricted to writing codes alone. You can help with documentation, help share and talk about the project with your friends, help with product designs and many more. I hope this article is able to get some guidelines that can help you get started in your next open-source project.
I am currently building a newsletter to share informative articles and news, my progress in creating startups with little experience and how you can learn from my experience.
Please subscribe via this link.
