CONTRIBUTING.md 9.92 KB
Newer Older
Benoit Mortier's avatar
Benoit Mortier committed
1
2
3
4
# Contributing to FusionDirectory projects

## Table Of Contents

5
1. [Welcome](#Welcome)
Benoit Mortier's avatar
Benoit Mortier committed
6
7
8
2. [Code of Conduct](#code-of-conduct)
3. [I just have a question!](#i-just-have-a-question)
4. [How Can I Contribute?](#how-can-i-contribute)
9
    * [Translate FusionDirectory in your language](#translate-fusiondirectory)
Benoit Mortier's avatar
Benoit Mortier committed
10
11
12
13
14
    * [Finding Wonderful Bugs](#finding-wonderful-bugs)
    * [Any Feedback To Enhance Our Apps](#any-feedback-to-enhance-our-apps)
    * [Your Awesome And Mighty Codes Contributions](#your-awesome-and-mighty-codes-contributions)
5. [Coding with style](#coding-with-style)
    * [Git Commit Messages](#git-commit-messages)
15
    * [PHP Style Guide](#php-style-guide)
Benoit Mortier's avatar
Benoit Mortier committed
16
17
18
6. [Licensing](#licensing)

---
19
## Welcome
Benoit Mortier's avatar
Benoit Mortier committed
20

21
> «Here's a list of our guidelines, If you want to share a best practice, or think one of these guidelines should be removed, feel free to share it with us.»
Benoit Mortier's avatar
Benoit Mortier committed
22

23
:tada: First off, thanks for taking the time to contribute!
Benoit Mortier's avatar
Benoit Mortier committed
24

25
Now, sit comfortably at the fireplace, grab your glasses and immerse yourself in our documentation.
Benoit Mortier's avatar
Benoit Mortier committed
26
27
28
29
30
31
32
33
34
35
36
37
38

## Code Of Conduct

All projects and everyone participating in it is governed by [FusionDirectory Code Of Conduct](./CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please read this before.

## I just have a question!

> **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resource below.

We have an various channel of communications

*  [#fusiondirectory, the irc channel of FusionDirectory on freenode](https://webchat.freenode.net/), channel #fusiondirectory
*  [FusionDirectory Users mailing list](https://lists.fusiondirectory.org/wws/info/users)
39
*  [FusionDirectory dev mailing list](https://lists.fusiondirectory.org/wws/info/developpers)
Benoit Mortier's avatar
Benoit Mortier committed
40
41
42

## How Can I Contribute?

43
44
45
46
47
48
49
50
51
So, you've developed a new cool feature? Fixed an annoying bug? Found a mistake? Want to help translate FusionDirectory in your own language. We'd be happy to hear from you! :+1:

### Translate FusionDirectory

We are using [Transifex](https://www.transifex.com/fusiondirectory/FusionDirectory-1x/) to translate FusionDirectory.

* Create a transifex account
* Ask to be added to the language group you want to translate
* Start translating
Benoit Mortier's avatar
Benoit Mortier committed
52

53
54
55
56
57
58
59
60
61
62
63
### Register for a FusionDirectory project account

To create a FusionDirectory project Account you must go to

* [FusionDirectory Sign UP](https://register.fusiondirectory.org)

### Put FusionDirectory in debug mode

* Go into FusionDirectory configuration
* Activate the displaying of PHP errors, and the TRACE debug level

Benoit Mortier's avatar
Benoit Mortier committed
64
65
66
67
### Finding Wonderful Bugs

>This section guides you through submitting a bug report. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.

68
When you are creating a bug report, please include as many details as possible. Fill out the **Bugs** template to create issues, the information it asks for helps us resolve issues faster.
Benoit Mortier's avatar
Benoit Mortier committed
69
70
71
72
73
74
75
76

Explain the problem and include additional details to help maintainers reproduce the problem:

* **Use a clear and descriptive title** for the issue to identify the problem.
* **Describe the exact steps which reproduce the problem** in as many details as possible. For example, start by explaining wich brower and it's version. When listing steps, don't just say what you did, but explain how you did it. For example, if you moved the cursor to the end of an input, explain if you used the mouse, or a keyboard.
* **Describe the behavior** you observed after following the steps and point out what exactly is the problem with that behavior.
* **Explain which behavior** you expected to see instead and why.
* **Include screenshots and animated GIFs** which show you following the described steps and clearly demonstrate the problem. You can use [this tool](http://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and this tool or [this tool](https://github.com/GNOME/byzanz) on Linux.
77
78
* **Include the PHP errors and trace** collected at the debug step above
* **If the problem is linked to a specific LDAP entry** attach its LDAP dump.
Benoit Mortier's avatar
Benoit Mortier committed
79

80
81
82
83
84
Fill in a report on :

* [FusionDirectory](https://gitlab.fusiondirectory.org/fusiondirectory/fd/issues) for the core program
* [FusionDirectory Plugins](https://gitlab.fusiondirectory.org/fusiondirectory/fd-plugins/issues) for plugins.

Benoit Mortier's avatar
Benoit Mortier committed
85
86
87
88
89
### Any Feedback To Enhance FusionDirectory

>This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.


90
91
92
93
94
When you are creating a enhancement report, please include as many details as possible. Fill out the **Enhancement** template to create thoses issues, the information it asks for helps us resolve issues faster.


* [FusionDirectory](https://gitlab.fusiondirectory.org/fusiondirectory/fd/issues) for the core program
* [FusionDirectory Plugins](https://gitlab.fusiondirectory.org/fusiondirectory/fd-plugins/issues) for plugins.
Benoit Mortier's avatar
Benoit Mortier committed
95
96
97
98
99
100
101
102

* **Use a clear and descriptive title** for the issue to identify the suggestion.
* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
* **Include screenshots and animated GIFs** which help you demonstrate the steps which the suggestion is related to. You can use [this tool](http://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
* **Explain why this enhancement would be useful** to most FusionDirectory users.

### Your awesome And Mighty Codes Contributions
103

Benoit Mortier's avatar
Benoit Mortier committed
104
105
>This section guides you through submitting an enhancement suggestion, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.

106
107
108
109
110
111
112
113
114
115
116
117
118
When you are contributing a new fonctionnality or plugin, please include as many details as possible.

Fill out the **Contribution** template to create thoses issues, the information it asks for helps us resolve issues faster.

* [FusionDirectory](https://gitlab.fusiondirectory.org/fusiondirectory/fd/issues) for the core program
* [FusionDirectory Plugins](https://gitlab.fusiondirectory.org/fusiondirectory/fd-plugins/issues) for plugins.

* **Use a clear and descriptive title** for the issue to identify your contribution
* **Provide a step-by-step description of the contribution** in as many details as possible.
* **Include screenshots and animated GIFs** which help you demonstrate what this contribution is about. You can use [this tool](http://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
* **Explain why this contribution would be useful** to most FusionDirectory users.
* **Follow the** [Coding style](https://fusiondirectory-developer-documentation.readthedocs.io/en/latest/coding/codingstandards.html)
* **Use our** `PHP CodeSniffer <http://pear.php.net/package/PHP_CodeSniffer>`_ rules to check code compliance [CodeSniffer](https://fusiondirectory-developer-documentation.readthedocs.io/en/latest/coding/codingstandards.html#checking-standards)
Benoit Mortier's avatar
Benoit Mortier committed
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156

## Coding with style

### Git Commit Messages

>Having a good guideline for creating commits and sticking to it makes working with Git and collaborating with others a lot easier.

Here are some rules of thumb :

* Use the present tense ("Add feature" not "Added feature")
* If you have a body, separate the subject from the body with a newline
* Limit the subject line to 72 characters
* Do not end the subject line with a period
* Use imperative [mood](https://en.wikipedia.org/wiki/Imperative_mood#English) in the subject line
* If the subject is not clear enough, use the body to explain what and why as opposed to how
* Consider starting the commit message with an applicable emoji, when you feel it's an important commit :
    * :tada: When first / initial commit
    * :sparkles: When introducing new features
    * :ambulance: When fixing a bug
    * :handshake: When  merging files
    * :tractor: When you changing file structure or refactoring
    * :books: When writing docs
    * :gem: When new Release
    * :lipstick: For cosmetics purposes

#### Commit Message Format
Each commit message consists of a **header**, a **body** and a **footer**.  The header has a special format that includes a **type**, a **scope** and a **subject**:

```
<emoji> <type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

The **header** is mandatory and the **scope** of the header is optional.

157
158
159
160
161
162
163
164
Where type can be :
  * **feat**:  A new feature
  * **fix**: A bug fix
  * **core**: Code for the Core
  * **docs**: Documenting the code or writing new documentation
  * **style**: Cosmetics purpose
  * **test**: Adding missing or correcting tests

Benoit Mortier's avatar
Benoit Mortier committed
165
166
167
168
169
170
171
172
173
174
175
176
Examples:

```
:sparkles: feat(supann): Make supannRefId multivaluated

supannRefId on Structure object is too small and mono valued

close #5685
```

### PHP style Guide

177
To be sure to respect our guidelines, read [Coding standards](https://fusiondirectory-developer-documentation.readthedocs.io/en/latest/coding/index.html)
Benoit Mortier's avatar
Benoit Mortier committed
178
179
180
181
182
183
184
185
186
187
188
189
190

## Licensing

For all new projects and most of older one we use **GPL2+ License**. You can find it [here](../LICENSE.md).

Make sure to use resources that we have the rights to use. Copyrighted images and videos may cause legal problems.

---

This document is strongly inspired by the following resources: [ovh-ux-guidelines
](https://github.com/ovh-ux/ovh-ux-guidelines), [project-guidelines](https://github.com/wearehive/project-guidelines), [Atom Guidelines](https://github.com/atom/atom/blob/master/CONTRIBUTING.md#reporting-bugs), [Angularjs guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md).

With love :heart: