Contribute

How to contribute to this project?

To contribute to this project, please follow the steps below.

1. Create an issue to your request or choose an issue already defined

The easiest way to contribute to this project is by creating an issue. On the issues page, you will have 4 issues templates options to suggest a contribution: Feature request (To request a new feature), Documentation (to request a documentation update in README, new usage examples, wikis, etc), Bug report (to report bugs), and Test requests (to request tests for a feature). Please choose one issue template and describe what do you really want in detail, use images, and code snippets if needed. Be clear in your request, and is not necessary to delete titles in the issues templates.

If your contribution is for an issue already defined, please ignore this step.

2. Fork this project in https://github.com/Dirack/diffractionSimulator/fork

This is an open-source project, distributed bellow the GPL3 License. When you fork it, you automatically agree with the terms and conditions of the GPL3. So, before you push your contributions to this project, fork it, and read the usage license.

3. Create a branch for your contribution (name it using gitflow).

In your forked version of this project create a new branch. The branch name should be a reference to the issue you created in step 1 in the following way ('ID' means the issue id number):

• For an issue of the type Feature request, the branch name should be 'feature/issue/ID'
• For an issue of the type Documentation request, the branch name should be 'documentation/issue/ID'
• For an issue of the type Test request, the branch name should be 'test/issue/ID'
• For an issue of the type Bug report, the branch name should be 'hotfix/issue/ID'

The default branch (master) and development branch names follow the rules below:

• The development branch is opened by the repository's administrator, and its name is 'develop/VERSION' ('VERSION' means the current tag version being developed, example 1.1.0)
• The default branch is master and only the repository's administrator can modify it

The branch merge follows gitflow rules:

• These branches are opened and merged in the current development branch: feature, documentation, and test.

• These branches are opened and merged in master: develop, and hotfix.

• The branch master receives modifications from develop and bug corrections from hotfix

• The branch develop receives modifications from any other branch, include bug corrections from master

4. Do clear commit messages (a title with 50 characters and two paragraphs of text)

The commit history is so important as its content. This repository standard for commit messages is a maximum of 50 characters title and a maximum of 2 paragraphs of text in the commit message describing the modification. Pull Requests with insufficient commit history will be rejected.

References to other commits are allowed and wanted, it is done adding the commit hash in the commit message. And a reference to the issue is required, it is done adding #ID ('ID' means issue id number) in the title of the commit message or text. Please check out the commit message example below with a reference to issue 3 and commit 228cc06:

Program morse - send email through terminal #3

Morse uses sendemail to send email messages through bash terminal.
The interface is based on Dialog now. This commit resolves dependencies
problems in commit 228cc06

If your modification is small, one variable name, or code line, for example, the commit message can have only the title. Avoid comments in the code to explain your modification, this can be done in the commit message properly. If your explanation is quite long (more than two paragraphs), it is better to split your modification into two commits or more with shorter and clear commit messages.

If you add a new file, it is important to add descriptive headers in the top of your source code following the template below (This is an example for a python source code, though the required informations are the same for all source files):

#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Program Name
# 
# Purpose: Test vfsa program in multiple interfaces model.
# 
# Site: https://dirack.github.io
# 
# Programer: Rodolfo A C Neves (Dirack) 26/03/2020
# 
# Email: rodolfo_profissional@hotmail.com
# 
# License: GPL-3.0 <https://www.gnu.org/licenses/gpl-3.0.txt>.

5. Push your contribution to this repository

After you check your modifications and commit history are following the required steps above, you can push them to your forked version of this repository with the following command (substitute <type> for feature, documetation, test, or hostfix, as described in step 3):

~$ git push origin <type>/issue/ID

Then do a pull request from this '<type>/issue/ID' branch in your repository to the correct branch in this repository: your base branch and destine branch names should follow the rules described in step 3.

6. Create a new Pull Request with a clear description of your contribution

When you click in the "pull request" button you will be redirected to a pull request template, please fill in this template with a clearer and detailed description of your modifications, use images and code snippets if you want. You do not need to delete the titles in the template.

There are some tips to increase the probability of your modifications acceptance: Add usage examples and automatic unit tests to your contribution. You can also document these examples in a README.md and group that in a separate directory. If they are unit tests, describe expected results and acceptance criteria in the README and pull request.