Maintaining an Open Source Project

Contributing to Open Source

It is now possible to contribute to millions of open source repositories on sites like GitHub, which provides tools to help maintain open source projects.

Code of Conduct

A code of conduct is a written set of rules and standards for the people who interact with an open source project.

This would live in a file called CODE_OF_CONDUCT.

CONTRIBUTING.md

In an open source project, the CONTRIBUTING file is a guideline for how contributors to the project should participate.

This might include the exact steps to create an issue or submit code.

Open Source Licenses

An open source license is a legal document that specifies what people can and cannot do with your project.

For example:

Can someone modify your code and distribute it as their own?
Can they include your code as part of their own proprietary project?

The two major categories of licenses for open source are copyleft and permissive licenses.

If there are no licenses, people cannot assume they can use the project.

README.md

A README is the standard documentation file for open source projects. It should, at the very least, include the name of the repository and a description.

In a GitHub repository, this is typically where a visitor to the project should go first.

Writing a Good README file

A good README file in GitHub, at minimum, contains the following elements:

Title
Description
Features
How to use
Technologies
Collaborators
License

You can further level up your README file with markdown:

Use headers and HTML to format your README and make it easier to read.
The headers automatically generate a table of contents on GitHub!
Use media, such as images and videos, to make your project look more appealing.

An image of a README on GitHub showing table of contents for the project called "My Awesome Project". The headers include "What does it do?", "Usage" with a "Requirements" subsection, and "License".

GitHub Issues

A great way to track tasks that need to be worked on in a GitHub repository is to use GitHub Issues. GitHub Issues are built into GitHub and list the title, description, and assignee for an Issue. Other features are included as well, such as designating milestones and creating labels to keep everything in a repository organized.

The image shows a board of about 10-15 tasks that each have a title, a user associated, and multiple labels that indicate language or type of issue.

Good First Issue

Usually, in an open source project hosted on GitHub, you can label issues with the “good first issue” label to indicate it is an easy project for a beginner to take on.

Pull Requests on GitHub

A pull request is a feature of GitHub and other source code management tools that allow a repository’s collaborators to review and give feedback on proposed code changes before they are accepted and merged to another branch, usually the main branch. Each pull request creates a discussion forum that can be used by reviewers and authors alike to highlight or add comments to a single line of code or chunk of code, add videos or images, etc.

Going through the pull request process can increase group knowledge, improve product quality, and develop professional skills through group critique.

An image showing that the sonia_feature_navigation_menu branch cannot be merged automatically into the main branch when comparing the two branches.

Writing a Good Pull Request

Creating a good pull request can increase the chances of having your changes being accepted by the collaborators. Follow the steps below to properly structure your pull request, which can make it easier for reviewers to understand your proposed changes and receive their feedback quicker:

Concisely explain the purpose of the pull request in the title
Put the thought process behind code changes and the options you have considered in the description
- Including screenshots, GIFs, and videos can help others visualize your changes
Use and follow the pull request templates and guidelines, if provided
Make commit messages clear
Use comments both in your code and in the discussion
Keep pull requests small

A screenshot of "Open a pull request page" on GitHub.

Open Source: Improving Communication

One benefit of open source projects is that they help developers improve their coding and communication skills by collaborating with other developers from all over the world.

Open Source: Stability & Quality

One benefit of standard open source projects is that their code is often stable and high quality.

Because popular open source projects are so widely adopted, many people all over the world can contribute ideas, improvements, and fixes to these projects.

Open Source: Project Longevity

One benefit of open source projects is their longevity.

This is because the community can continue developing a project even if it is abandoned by its original maintainers, unlike proprietary software.

Copyleft License

A copyleft license requires that any modified version of an open source project also be released under the same license as the original project.

A strong copyleft license requires that any software that uses a project licensed under it must also be licensed in the same way (for example, also open source). Weak licenses, like LGPL, have no requirements for software that only use the licensed project.

GPL is an example of a strong copyleft license.

An image showing that, if one component of the project is licensed under GPL, the whole project must be licensed under GPL.

Permissive Licenses

Permissive licenses, which differ from copyleft licenses, do not put restrictions on people modifying or redistributing a project.

For example, if a private company wanted to fork an open source project, add some proprietary changes, and redistribute the project, this would be totally within their right as long as the project was under a permissive license.