CONTRIBUTING.md 3.3 KB
Newer Older
1
2
# How to contribute

3
4
Redhopper is free software and welcomes any feedback or contribution so do not hesitate to contact us.

5
6
Feel free to improve this contribution guide.

7
8
## Provide feedback

9
1. You can email us at **redhopper (at) infopiiaf.fr** (French and English spoken);
Alexandre Friquet's avatar
Alexandre Friquet committed
10
2. Open an issue on [Framagit](https://framagit.org/infopiiaf/redhopper) (which uses [Gitlab CE](https://about.gitlab.com/features/#community)).
11
12
13
14
15

And let's talk about it!

## Provide code

16
There are two ways to provide code for Redhopper, the first one being the preferred one:
Alexandre Friquet's avatar
Alexandre Friquet committed
17
1. Fork the project on [Framagit](https://framagit.org/infopiiaf/redhopper) and propose a [merge request](https://framagit.org/help/gitlab-basics/add-merge-request.md);
18
2. Send a git patch to **redhopper (at) infopiiaf.fr** (French and English spoken).
19

20
Either way, please try to stick to the following rules.
21
22
23

### Prerequisites

24
We recommend you develop and test the plugin within a test instance of Redmine.
25
26

To be able to work on the tool (`RAILS_ENV=development`):
27
28

1. install Redmine: [how to install Redmine](http://www.redmine.org/projects/redmine/wiki/RedmineInstall)
Alexandre Friquet's avatar
Alexandre Friquet committed
29
1. install Redhopper: [how to install the plugin](https://framagit.org/infopiiaf/redhopper/tree/master#how-does-it-work)
30
31
32
1. in order to see if everything is ok, in Redmine root directory:
    1. run the tests: `bundle exec rails test plugins/redhopper/test/**/*`
    1. start Redmine: `bundle exec rails server`
33
34
35
36
37

Now you can work on improving Redhopper.

### Provide tests

38
Your patch will have more chance to be included within the tool if your improvement is well tested. If you find yourself lost, do not hesitate to tell us.
39

40
41
At this moment, you should already know how to run the tests, but in case you forgot what you've just read ;-)
```
42
bundle exec rails test plugins/redhopper/test/**/*
43
```
44
45
46
47
48

### CSS

#### SASS

49
Unfortunately Redmine does not use SASS (yet) but we use it to develop Redhopper. If you want to perform modifications on the CSS, you will **have to** run the SASS compiler after modifying the SASS file. To do so, just run in **Redmine** directory:
50
```
51
bundle exec sass --watch plugins/redhopper/assets/stylesheets:plugins/redhopper/assets/stylesheets
52
53
54
55
```
This way, the `sass` executable will watch for every changes in `.sass` files and compile the matching CSS file. Don't forget to commit both the SASS and CSS files when you're happy with your work.

_N.B.: Redmine copies plugins' assets at startup, so you have to **restart Redmine** to be sure each of your changes have been pulled in._
56
57

#### Conventions
58
59
60

We're (mostly) using CSS conventions inspired by [SMACSS](https://smacss.com/book/categorizing), [BEM](https://en.bem.info/method/definitions/) and [SUIT CSS](http://suitcss.github.io/). It relies on a few principles :

61
62
63
64
65
66
67
68
1. Style CSS classes, not HTML elements or IDs;
1. Make a clear distinction between a UI component, its states and subcomponents:
    * `.Component`: capitalized noun;
    * `.Component.is-active`: `is-` prefixed + adjective;
    * `.Component-subcomponent`: `-` suffixed + lowercase noun;
1. An HTML element may be a component and a subcomponent :
    * the _component_ class is for cosmetics;
    * the _subcomponent_ class is for positioning.
69

70
For instance, a kanban board might use classes like `KanbanBoard`, `KanbanBoard-column`, `Column`, `Column-kanban`, `Kanban`, `Kanban.is-blocked`