Contributor Guide

This section outlines helpful information for you to contribute to an open source project.

Repository checklist
Guide to writing issues
Best practices for contributors

Repository checklist

If you are a contributor, this checklist is a handy tool for evaluating how well set up a project is to receive contributions.

✅ It should have a README file.

The README should link to or describe:

Project purpose and context
Installation instructions

✅ Contributions/Contributing guide.

This guide is usually written in the CONTRIBUTIONS/CONTRIBUTING markdown file. It consists of:

The recommended process for making issues/submitting pull requests.
Ways to communicate with the maintainers.

You might find the contributing guide in the README file if there is no CONTRIBUTIONS/CONTRIBUTING file.

✅ A valid open source license.

It is not advised to work on a project that doesn't have a license or is not using a standard open source license. Check out The License section of our Maintainer Guide for resources about licenses.

✅ A Code of Conduct (COC).

Check the Code of Conduct (COC) to ensure you participate in a way that's consistent with the organization's guidelines.

Guide to writing issues

There is no such best way to write issues. But there are things we want to avoid that either will discredit what we want or need or won't help the person trying to solve the issue.

Some important things to remember:

Provide information: An issue needs information which can include pictures, metrics, and more. It makes the information more precise than just using words.
Describe the issue: Follow any templates provided by the organization and/or asking yourself: What, Where, When, How and Why. The issue must be clearly described so that anyone can understand it without being in your head. 🙂
Don't solve the issue: You are not expected to solve the issue. If you want to solve the issue, tell the maintainer in the comment that you want to do it and let them assign it to you.

A suggested solution can be a good thing, especially to help the contributors who have less experience. When you're writing issues on a repository that isn't your own, you might not have all of the contexts to provide the best solution. Therefore, the maintainers always have the final say in the solution or approach to the issue.

Tips before writing an issue

Check the repository's README and CONTRIBUTING guide (if they have one) to learn how maintainers expect communication and how to create an issue. For example, some repositories require you to start a discussion before making an issue.
Check current and closed issues to ensure no one has already written the issue you're going to write.
If the organization has discussions enabled, check if the issue has also been mentioned there.
Check the Code of Conduct (COC) to ensure you participate in a way that's consistent with the organization's guidelines. The absence of a COC is unfortunate, but it doesn't mean people should be rude or disrespectful, even if the issue is super frustrating.

How to create an issue

We'll walk you through how to create an issue and reference the Virtual Coffee repository as an example.

Go to Virtual Coffee repository.
Navigate to the Issue Tab.
Click the "New Issue" button and check if there is an available template.
Click on the issue category button that fits your needs, then follow all the steps and requirements.

How to write an issue

Remember, there isn't one best way to write an issue. When there are no specific templates provided, here is a list of what's good to share in different types of issues:

🐞 Bug Issue

Include this information in the issue:

Title: Clear enough to identify what the problem is about.
Screenshots: The screenshots of the UI, logs, if it's a performance issue, or anything that proves the problem exists.
Your setup: The device and OS version, type of browser and version that you use, and any other setup that can help reproduce the problem.
Description: Add the steps to reproduce the bug/behavior. Some things to consider: - What you think the correct behavior should be? - The current behavior and how it differs. - The conditions required to produce the bug. For example, the buttons or the link you click, etc.
Solution: If you think of a solution to solve the problem, you can suggest something. However, the maintainer would be the final decision-maker.
Links: Any issue or discussion that relates to this problem, if any.

🌱 Feature Issue

Title: Clear enough to identify what feature you want to add or see.
Description: Describe why you wish to request the feature.
Proposed Solution: What do you think the solution should be and why? If you don't have a suggestion, that's fine too!
Links: Any issue or discussion related to this request, if any.

📄 Documentation Issue

Title: Clear enough to identify what the problem is about.
Description: Describe why you request the documentation change. For example, "I noticed an unclear explanation of how to install the software in the installation section."
Proposed Solution: What do you think the solution should be and why? If you don't have a suggestion, that's fine too!

Best practices for contributors

Observing repository conventions

Most repositories will have certain conventions that you need to follow. These will differ from project to project. You can usually find them in the README or CONTRIBUTING file. The areas covered will vary, but there are common things to look out for:

Code style guides
General conventions for communicating
Branch naming conventions
Git workflows

The work process

Most projects expect some form of discussion before making a pull request. Expectations vary from project to project, and you can usually find them in the README or CONTRIBUTING file.

Many projects use labels such as bug, documentation, help wanted, ready for dev and many more to help you determine what issues you can work on.

Unless the documentation says otherwise, you should typically comment on an issue that you would like to work on. Ask the maintainer to assign you to it, and only start working on it when they give it to you. It helps to avoid duplication of work and ensures that expectations are aligned. Unless the repository explicitly states that it accepts unsolicited pull requests, you should not take the initiative to make a pull request to a project.

Communication with maintainers

Communication is key to working on open source. Most projects have communication conventions, and contributors should always follow these rules. Many projects primarily communicate via comments on issues or pull requests. Some projects have external groups such as Slack, a forum, IRC, or email lists where communication takes place and work is coordinated. If the project uses these, there should be information on the README or CONTRIBUTING file. If there is no specific information about where to communicate, you can probably assume that communication can take place via comments on issues or pull requests.

Regardless of the tools used to communicate, there are certain things to keep in mind to keep communication effective and respectful, especially in a international online space.

Always follow the Code of Conduct.: Yes, always, even if you disagree with its contents or think it restricts your freedom of speech. The community agreed on these rules to govern the space. As an entrant to the community, you must follow these rules.
Messages should be kept short and simple.: It is often best to keep to 'one message, one topic'. However, there may be times when this is not possible. For example, if you will be unavailable for some time and need to respond to several points. If you need to discuss several topics in one message, put each in a separate paragraph.
Disagreement and debate are healthy, but it is important to keep the conversation respectful.: You could criticize the ideas people express, but don't criticize the person directly.
Low-context communication works best in international, cross-cultural spaces.: Meanings should be explicit in the words you use. People from different cultures might not understand specific cultural references, cliches, and sayings.

Self-care

We recommend you approach open source work with the same professionalism as you would work for an employer. But remember, you are doing this in your spare time, and self-care is essential. It means that you should take care of things such as code style, documentation, and testing, just as you would in your work for an employer, but it is okay if you cannot work at a fast pace. If timescales come up in open source contributions, try to set reasonable expectations from the beginning. Otherwise, take a reasonably relaxed time to work on things. For non-trivial issues, you should not be expected to complete the work to a given timescale.