Skip to content

Latest commit

 

History

History
106 lines (71 loc) · 6.43 KB

CONTRIBUTING.md

File metadata and controls

106 lines (71 loc) · 6.43 KB
Raw

Contributing

It's awesome that you are interested in contributing, thanks ❤️! This guide explains our internal processes and how we can work together to the best of our ability.

How to contribute

There are several ways to contribute to the project:

Reporting bugs

If you have found a bug, you can report it using the issues. Before reporting your bug, it is important to do the following checks:

  1. Update your local repository to the latest dev branch. Maybe your bug has already been fixed in the latest version;
  2. Verify if the bug has not been previously reported by someone else (search the existing issues).

If the bug has not been resolved or reported previously, then it is time to create a new issue. In the issue title try to summarize the problem by avoiding generic phrases like "System Failure" or "Installation Problems".

If possible, include images or videos in the bug description to make it easier to reproduce the problem. Use software like LICEcap to create an animated gif of your screen. Also provide details about your environment: execution platform, operating system, browser and version, etc. You must also add the label bug to the issue.

Note about security issues

If you have found a security issue do not use issues to report the bug. Write your report via email directly to some project administrator. It will be reviewed, validated and corrected as needed. We ask that you do not make the fault public for the safety of everyone using the project in its current state.

Suggesting improvements

Another great way to contribute is by suggesting improvements to the project, e.g. how it is structured. If you have any idea how we can improve the project, follow these steps:

  1. Make sure your idea is not already being addressed in our roadmap;
  2. Also make sure the idea is not already listed in the issues;
  3. Defend your idea and convincingly explain why it should be followed. Here are some questions to consider:
    1. Will more users of the project benefit from this idea or only yourself?
    2. What problem does your idea solve?
    3. Why is your suggestion better than what already exists in the code?
    4. Is it really worth taking time to implement your idea within our priorities?

After having examined all these questions, you can create a new issue describing the enhancements. Use the label enhancement.

Requesting features

Time is a limited resource. Since this is a community (non-sponsored) project, some features have higher priority than others. It's worth submitting your feature suggestion only if:

  1. The feature in question solves a problem that is not solved by anything that already exists in the project;
  2. The feature solves a real issue validated by people that use the project.

To create your feature request create a new issue using the label feature.

Discussing issues

Before we go into the code itself, it is very important to discuss with the community how each issue will be addressed. Any and all questions should be discussed, so anyone wishing to resolve that problem has as much information as possible to perform a solution.

Ideally, all issues should have a clear action plan before any code is written. We know that this is often not possible. However, try to explain what you want to achieve and how you intend to do it. Your ideas will receive feedback from the community, so we can ensure no work is wasted.

Issues under discussion should be labelled discussion indicating that that issue needs input and feedback from members of the community. We encourage you to participate as much as possible but stay tuned to our code of conduct before making any interaction with other community members.

Pull requests

Once you have a relatively clear plan of action, you should be ready to contribute any code. To do this, fork the project and work on top of a new branch based on the dev branch. It is a common practice to name your new branch with something related to the feature or bug you are fixing, e.g. fix-issue-45 or improved-gui. To learn more about pull requests and how they work, see this link.

Before you open your PR (pull request) make sure that:

  • Your PR solves a single issue. If you want to do more than one thing, split into multiple PRs;
  • Your code is functional (or something close to it). Provide testing if possible;
  • The messages from your commits are clear and describe the job well. For more tips on writing proper commit messages, see this guide.

Other ways to contribute

If you don't work with code but want to help the project, there are many more ways to contribute:

  • Help with documentation. It is extremely important!;
  • Talk about the project on your social networks, blogs, etc. Spread the word;
  • Organize events and give lectures about the project;
  • Create promotional material such as presentations, screencasts, media for sharing on social networks, etc;
  • Have you seen any discussion that interests you and you can add even without technical knowledge? Don't be shy and participate!

Have you thought of any other way to contribute? Share it with us!

Credits

This document was written with the help of other similar documents used in other communities. We highlight:

... among others!