CONTRIBUTING

# 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](#reporting-bugs)
- [Suggesting improvements](#suggesting-improvements)
- [Asking for features](#asking-for-features)
- [Discussing issues](#discussing-issues)
- [Making pull requests](#making-pull-requests)
- [Other ways to contribute](#other-ways-to-contribute)

### Reporting bugs

If you have found a bug, you can report it using the
[issues](https://github.com/dotsem/tuSSHi/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](https://github.com/dotsem/tuSSHi/issues/new). 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](https://www.cockos.com/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 a personal message to me. 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](./ROADMAP.md);
2. Also make sure the idea is not already listed in the [issues](https://github.com/dotsem/tuSSHi/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](https://github.com/dotsem/tuSSHi/issues/new) 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](https://github.com/dotsem/tuSSHi/issues/new) 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. 

### 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](https://help.github.com/articles/about-pull-requests/).

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](https://chris.beams.io/posts/git-commit/).

### 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!*;
- Help with testing to improve the quality of the app;
- Talk about the project on your social networks, blogs, etc. Spread the word;
- 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 is based on [a template from Dovyski](https://github.com/Dovyski/template/blob/master/CONTRIBUTING.md)