5 Files That Every Open-Source Project Should Have

What to include in your open-source project, right from the start

Photo by Khachik Simonian on Unsplash.

“Open-source” is a buzzword in the technology industry right now. More and more companies are coming into the open-source world, including giants like Microsoft and Google, who are investing heavily in open-source projects with each passing year. Experts have finally realized that it’s not about keeping your code safe from others and trying to make something perfect with the limited resourced you have. Rather, it’s about being collaborative, bringing in more heads than you could ever afford to have, and, in turn, adding more ideas to create a perfect project.

But the amount of open-source projects that get funding to go ahead is still comparatively low. In recent times, there have been many programs to support the community and bring more people into it thanks to companies like GitHub. Last year, I attended the official launch event of GitHub in my country and one of the main topics discussed was how to encourage this community of creators and contributors.

In this article, we are going to talk about a few things you need to include in your open-source project to make it easier for everyone — including contributors, moderators, users, and sponsors — to help you in growing the project.

1. License

Licenses are an important part of open-source projects, as they’re mostly public and free to use. For any open-source repository to stay faithful to its title, it needs to have a license that allows others to freely use, change, or even distribute the project. It’s not mandatory to have a license, but without one, copyright laws will apply to your project. All the rights will stay with you, thereby not allowing people to reuse, recreate, or share your project.

The best practice while creating a license file is to create a text file named LICENSE.txt or LICENSE.md in the root of the repository. GitHub officially recommends Choosealicense to understand which license is right for your project.

LICENSE on the official Flutter repository.

2. README

I know it sounds redundant to add a README to this list, but this is the most important file that every open-source repository should have. A README file plays an important role in introducing and explaining a project. It helps people understand what the project is about, how to run it, documentation, etc. The most common file format used for READMEs is markdown README.md.

Having a great README file can be the difference between getting attention in the ocean of projects out there or not. This page by Matias lists everything you need to write a good README file, including example, tools, badges, etc.

README on the official Flutter repository.

3. CodeOwners

Regular code review is essential to every successful project, but in many cases, it’s not always clear who needs to review what. By defining a CodeOwners file in the project, repository maintainers can define the people responsible for doing this. According to GitHub’s docs:

“Code owners are automatically requested for review when someone opens a pull request that modifies code that they own.”

Anyone with admin or owner permissions can create a file named CODEOWNERS in the repository’s root directory while keeping in mind that people or teams chosen as code owners must have write permissions for the repository. CodeOwners can be defined for the entire repository or specific file types or folders. For example, if you add code owners for *.js files, only people listed on that line will be requested to review.

CODEOWNERS on the official Flutter repository.

4. Contributing

Open-source projects are all about contributions. That’s how every project grows. For most projects that accept active contributions, it is always good to have a guideline for contributors to make it easier for them as well as reviewers. This file will contain guidelines for anyone who wants to contribute to the project. This can include many things, such as where to find and track issues, sub-projects, blogs for the project to contribute, coding guidelines, etc.

To add a file, create a file named CONTRIBUTING ( not case sensitive) with a .md or .txt extension (optional) in the root folder or under docs/.

CONTRIBUTING on the official React Native repository.

5. Code of Conduct

A code of conduct is something that most people who are part of groups or communities would be aware of. In an open-source project, it also takes the literal meaning. A code of conduct defines best practices or guidelines on how to interact and communicate in the community. It will define the project’s community standards and contain principles on being inclusive of all contributors. It can also be the go-to document to resolve conflicts between community members, sort of like an unofficial legal handbook. It may also define the rules, regulations, and legal standpoints that govern a project.

This is an important file if you want to promote a culture of mutual respect, diversity, and inclusion within the project’s community.

You can add a code of conduct to the project by creating a file named CODE_OF_CONDUCT.md. This can also be done by using the “Add file” option in GitHub where you can also find various templates for a code of conduct.

Code of conduct on the official React Native repository.

Bonus: AUTHORS

This one is not necessary, but it’s good to have in any open-source project. This file contains a list of all the teams and people that have contributed to the project at some point. This is like a perk for any contributor to have their name (org name) listed in the repository, which gives them visibility in the tech community. To add this file, simply create an AUTHORS file in the project and add a format to add names using comments in the file.

Authors on the official Flutter repository.

Conclusion

You may have noticed that most guidelines mentioned in the article revolve around GitHub. That is because it is the place where open-source happens. But having these files in the repository will help regardless of the platform where the code is stored.

If you have any suggestions for files to be included in a repository, leave them in the comments.