Contributor Guide

• Repository Checklist
• Guide to Writing Issues
  • Tips Before Writing an Issue
  • How to Create an Issue
  • How to Write an Issue
• Best Practices for Contributors
  • Observing Repository Conventions
  • The Work Process
  • Communication with Maintainers
  • Self-Care

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

✅ A README.md file
The README should link to or describe the following:

• Project purpose and context
• Installation instructions

✅ CONTRIBUTIONS/CONTRIBUTING.md file
This is a guide for contributors to contribute to the project. If none is available, you might find the contributing guide in the README.md file. CONTRIBUTIONS/CONTRIBUTING.md file consists of the following:

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

✅ 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.

Back to Top

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 the organization's templates and/or ask 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 writing issues on a repository that isn't your own, you might need more context to provide the best solution. Therefore, the maintainers always have the final say in the solution or approach to the issue.

• Check the repository's README.md and CONTRIBUTIONS/CONTRIBUTING.md (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 will bring up.
• If the organization has discussions enabled on their GitHub, check if the issue has also been mentioned.
• 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.

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

1. Go to the Virtual Coffee repository.
2. Navigate to the Issue Tab.
3. Click the "New Issue" button and check if a designated template for your issue is available.
4. Click on the issue category button that fits your needs, then follow all the steps and requirements.

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
  If it's a performance issue, the screenshots of the UI, logs, or anything that proves the problem exists.
• Your setup
  The device and OS version, browser type and version 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 do 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
  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 should the solution be and why? If you don't have a suggestion, that's fine too!
• Links
  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 should the solution be and why? If you don't have a suggestion, that's fine too!

Back to Top

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.md or CONTRIBUTIONS/CONTRIBUTING.md 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

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

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

Unless the documentation says otherwise, you should comment on an issue you want 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 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 occurs and work is coordinated. If the project uses these, there should be information on the README.md or CONTRIBUTIONS/CONTRIBUTING.md file. Without specific details on where to communicate, you can assume that communication can occur 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 an international online space.

• Always follow the Code of Conduct (COC)
  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 straightforward
  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.
• Keep the conversation respectful
  Disagreement and debate are healthy, but it is important to keep the conversation respectful. You could criticize people's ideas but don't criticize the person directly.
• Low-context communication 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.

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. Both you and the maintainer should set reasonable expectations from the beginning. You should expect to have a reasonably relaxed time to work on things. You should not be expected to complete the work by a strict deadline, even for non-trivial issues.

Back to Top