GitLab 14.5 is now available. 🚀 Learn what's new.

CONTRIBUTING.md 10.5 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
---
layout: default
title: Contribution Guide
excerpt:
  Contribution guide for the HIFIS Software website.
---
# Contribution Guide

Hey, you are interested in contributing to the web-page of _HIFIS Software_?
That is great, your help is much appreciated!
Please take some time to read about the Coding Guidelines and
Best Practices that were agreed upon.
If you have questions do not hesitate to contact a group member
of the development team.
Also, we are happy to learn what you think about this web-page
and get feedback regarding how to improve its appearance and content.

Note:
In case you are just interested to know how to contribute with a
blog post to _HIFIS Software_ web-page you can find a 
21
[blog post]({% post_url 2019/11/2019-11-22-How-to-Create-a-new-Blog-Post %} "How to Create a New Blog Post?")
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
explaining the suggested workflow in the blog post section 
of the web-page.

## Contribution Workflow

### Workflow in a Nutshell

**1. Open an Issue, Share and Discuss the Topic**

Once you come up with an idea about how to contribute to _HIFIS Software_
web-page you can open a
[GitLab Issue](https://docs.gitlab.com/ce/user/project/issues/managing_issues.html#create-a-new-issue "Open a GitLab Issues")
and describe the bug you would like to fix, the feature you want to code
or the refactoring, testing or other quality assurance measures
you would like to implement.

Important:
Of course you need your own GitLab account of the
[HZDR GitLab](https://gitlab.hzdr.de/ "HZDR GitLab")
instance to do so as well as being added as a group member to the
development team.

Note:
At this point in time you would like to know more about the
branching model
[GitLab Flow](https://docs.gitlab.com/ce/topics/gitlab_flow.html "GitLab Flow")
that is supported by GitLab and the User-Interfaces of GitLab.

**2. Contribute with your Developments**

As soon as you would like to get to work you need to create your own
Git-branch.
Please give the branch a meaningful name according to the pattern
`<issue-number>-<branch-name>`.
It is good practice to check your code with static code checking tools
regularly as well as writing unit tests for your code.
Furthermore, when having unit tests in place as a safe guard you can
start refactoring your code to make it more readable, reusable,
testable, maintainable without changing the actual functionality
of your code.
Each Git-push to the remote Git repository will start a so called
_GitLab CI Pipeline_ to check that everything still works
as intended.

**3. The Review Process to Improve your Developments**

To enter the review process you need to open a
[GitLab Merge Request](https://docs.gitlab.com/ce/user/project/merge_requests/creating_merge_requests.html "GitLab Merge Request")
and assign it to your primary reviewer.
Give the merge request a meaningful title and description and
reference the original issue by stating `Closes #<issue-number>.`
in the description.
If applicable, give the title a name starting with `[WIP]`
to indicate that you are still working on it.
This allows previews and runs the GitLab CI/CD pipeline on your commits.
Also, set the `Progress::CanReview` label for the merge request,
so the others know you want to have it reviewed.

Please feel free to use GitLab's _Review Apps_ functionality to
view and test your branch.
It is an easy way to inspect your changes in a test / staging 
environment as well as involve external reviewers into the project.
When pushing your branch onto the remote repository your branch is
automatically deployed to _Review Apps_.
You can preview your latest deployments of your branch
by clicking the button _View app_ in the User-Interface of your 
Merge Request.
Alternatively, for branch _master_ you can open the _External URL_
in your browser by yourself:
`https://hifis-review-app.hzdr.de/review-apps/hifis-software-hifis-net/`.
(The automatically generated _External URLs_ for all other 
branches contain an additional sequence of numbers, lower case
letters and dashes as an URL-friendly replacement of the branch
name given.)

You need to authenticate to access these pages.
The credentials are as follows:
Username: `hifis`, Password: `HIFISReview!`.

Note:
Make sure that the corresponding _GitLab CI Pipeline_ finished
successfully after pushing your changes to the remote repository,
otherwise the changes to your branch will not yet be deployed to
_Review Apps_ as a new version.

After opening a _Merge Request_ discuss the changes suggested by your 
reviewers in dedicated discussion threads in GitLab and agree upon 
how to integrate these suggestions into your code to improve your
developments.

Important:
Please do not rely on contributions that are not reviewed or
that are only reviewed by yourself.
This is an important quality gate.

After integration has been done and _GitLab CI Pipeline_
finishes successfully you are nearly crossing the finishing line.

**4. Integrate your Developments**

Once all discussion threads are resolved and the _GitLab CI Pipeline_
finishes successfully the primary reviewer can merge your branch into
branch _master_.
Be sure, we appreciate your contribution very much and thank you for
the great collaboration.

## Code Guidelines and Best Practices

### Common Style Guides

If you are about to contribute to this web-site we recommend to adhere to
common style guides for each language used.
Since we are using Jekyll to generate static web sites we mostly stick
to Markdown / Kramdown, HTML, CSS / SCSS and JavaScript.
Jekyll itself is written in Ruby.

The following common style guides for each language used are just a
suggestion. We do not expect from you to rigorously comply to these
style guides. Nonetheless, they are a good starting point for
contributions according to Best Practices:

A first reference point is the
[Google Markdown Style Guide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md "Google Markdown Style Guide").
The
[Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html "Google HTML/CSS Style Guide").
is another good reference point if you are about to write HTML and CSS.
In order to generate CSS from SCSS there are the
[SASS Style Rules](https://sass-lang.com/documentation/style-rules "SASS Style Rules")
as well.
In terms of Javascript there is the
[Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html "Google JavaScript Style Guide").
In the very unlikely case you are contributing to Jekyll or write your
own Jekyll plugins you should read also the
[Ruby Style Guide](https://rubystyle.guide/ "Ruby Style Guide").

This is a lot to read at the first glance, but it essentially saves you
and us time if you try to take these rules into account
right from the beginning, since these rule violations
might come up during the review process anyway.

### Style Checking Tools

Due to the fact that style guides are quite complex and to adhere to them
is a difficult task we recommend to consult dedicated tools to do the
checking for you.
Here comes the time saving into play.

| Static Code Analysis Tool | Language to Check |
|---|---|
| markdownlint | Markdown |
| HTML-Proofer | HTML|
| CSSLint | CSS |
| JSHint | JavaScript |
| Rubocop | Ruby |

#### markdownlint

[markdownlint](https://www.npmjs.com/package/markdownlint "markdownlint")
lets you check your Markdown. It is available as CLI-tool and
can be installed via npm and executed as follows:

```bash
$ npm install -g markdownlint
$ markdownlint path/to/markdown/folder/
```

#### HTML-Proofer

[HTML-Proofer](https://github.com/gjtorikian/html-proofer "HTML-Proofer")
lets you check your HTML. It is available as CLI-tool and
can be installed via gem and executed as follows:

```bash
$ gem install html-proofer
$ html-proofer path/to/html/folder/
```

#### CSSLint

[CSSLint](https://github.com/CSSLint/csslint/ "CSSLint")
lets you check your CSS. It is available as CLI-tool and
can be installed via npm and executed as follows:

```bash
$ npm install -g csslint
$ csslint path/to/css/folder/
```

#### JSHint

[JSHint](https://jshint.com/about/ "JSHint")
lets you check your JavaScript. It is available as CLI-tool and
can be installed via npm and executed as follows:

```bash
$ npm install -g jshint
$ jshint path/to/js/folder/
```

#### Rubocop

[Rubocop](https://github.com/rubocop-hq/rubocop "Rubocop")
lets you check your Ruby code. It is available as CLI-tool and
can be installed via gem and executed as follows:

```bash
$ gem install rubocop
$ rubocop path/to/ruby/code/folder/
```

### Specific Aspects in our Style Guide

#### User Interaction Considerations
##### Offer Alternatives to Hover Interaction
Keep in mind, that mobile devices like phones or tablets usually do not have the
ability to hover over an element on the website. Build alternatives for these
into your CSS and make sure they are used if the display is tablet-sized or
even smaller. Consult `_sass/_breakpoints.scss` for available breakpoints.

_More detailed discussion:_
Hovering is considered a good method to offer additional information without
forcing a context switch on the user (e.g. loading a new page or skipping to a
different part of the page).
Since for technical reasons this is not possible on mobile devices, an
alternative has to be considered for those. The usual approach is to entice the
user to click the element in question instead. To do so, it should be hinted to
the user that the element is clickable. If possible, use the websites default
link or button designs. In all other cases it can be achieved by either visual
styling (Since you can not use hover effects, consider subtle drop shadows) or
added badge icons
([Inspiration](https://www.flaticon.com/free-icons/hand-click)).

#### CSS
##### Avoid Magic Values
Values that show up in _CSS_ may carry a semantic meaning, e.g. colors of the
color palette or device sizes.
Use the provided _SASS_ variables or named CSS values instead of hard-coding
magic values. Expand the set of variables, if required.
Example:

```scss
@import "colors"
p {
    background-color: $color-helmholtz-blue;
    color: white;
}
```

instead of

```scss
p {
    background-color: #005AA0;
    color: #fff;
}
```

See the `_sass` folder for definitions, grouped by context.

#### HTML
##### Write Comments in _Liquid_ tags
Please use _Liquid_ comments in your HTML files to avoid them showing up in the
rendered version.
Example:

```liquid
<html>
    {% comment %}
        This text will not show up in the rendered HTML page.
        It serves a documentary purpose only.
    {% endcomment %}
</html>
```

instead of

```HTML
<html>
    <!-- This is an HTML comment. It will be preserved and show up in the 
    rendered page, cluttering and bloating the delivered code. -->
</html>
```