Maintenance notification: GitLab and all corresponding services will be down for maintenance from Thursday, June 24th 16:00 until Friday, June 25th 08:00. Please excuse the inconvenience and plan your work accordingly.

Verified Commit db287e21 authored by Erxleben, Fredo (FWCC) - 136987's avatar Erxleben, Fredo (FWCC) - 136987
Browse files

Add general files

parent d1bcf29c
---
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
[blog post]({% post_url /2019/11/2019-11-22-How-to-Create-a-new-Blog-Post %} "How to Create a New Blog Post?")
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>
```
---
title: License
author: the HIFIS team
layout: default
---
# License Information
Different licenses apply for specific parts of the project.
The full text of each license can be found in the location specified in the appropriate section of each document.
This file gives an overview which license applies to which part of the project.
## Proprietary
The following items are copyright protected.
* The Helmholtz logo and the HIFIS logo
* The website corporate design
* The _CorporateS_ and _Hermann_ fonts
© by Helmholtz-Gemeinschaft Deutscher Forschungszentren e.V. <br/>
Helmholtz Association of German Research Centres
All rights reserved.
## GNU GPL 3
Source code posted on this website is licensed under GNU GPLv3 unless explicitly
stated otherwise.
[License text](https://www.gnu.org/licenses/gpl-3.0.html)
## MIT License
The file _normalize.css_ is provided by a third party and comes under
MIT License. Please refer to the file itself for origin, version and
license information.
## Creative Commons CC-BY 4.0
Any content not listed above defaults to the
[![Creative Commons License Agreement](https://i.creativecommons.org/l/by/4.0/80x15.png "CC-BY 4.0")](https://creativecommons.org/licenses/by/4.0/)
_Creative Commons Attribution 4.0 International License_
unless explicitly stated otherwise.
# HIFIS Software web page
The HIFIS Software web page will be the home for gathering information about
the activities and services offered by the HIFIS Software team. This website
is built using Jekyll.
## Build the project locally
1. Clone the project locally
```bash
git clone --recursive https://gitlab.hzdr.de/hifis/software.hifis.net.git
cd software.hifis.net
```
2. [Install](https://jekyllrb.com/docs/installation/) Jekyll.
3. Install dependencies.
```bash
bundle install
```
4. Build and preview the web page.
```bash
bundle exec jekyll serve --future
```
5. Add content.
Execute the commands above from the root of your repository.
More information is available in Jekyll's
[documentation](https://jekyllrb.com/docs/)
## Add yourself as a team member
There are basically two variants of achieving this:
### Do it yourself
1. [Git-clone](https://git-scm.com/docs/git-clone) the repository and
[Git-checkout](https://git-scm.com/docs/git-checkout) into a new branch
(with option `-b <new-branch-name>`)
2. Edit [_data/hifis_team.yml](_data/hifis_team.yml) and add your information.
3. Add `<your_id_here>.md` into the `_members` folder, containing at least the
following frontmatter:
```yaml
---
layout: member
title: <your_last_name>, <your_first_name>
data: <your_id>
---
```
4. Create a
[merge request](https://docs.gitlab.com/ce/gitlab-basics/add-merge-request.html)
in GitLab.
5. Let someone review and merge your changes into branch `master`.
### Let someone else do it :)
1. Create a new issue, using the _add team member_ template.
2. Fill in at least the required information.
GNU General Public License
==========================
_Version 3, 29 June 2007_
_Copyright © 2007 Free Software Foundation, Inc. &lt;<http://fsf.org/>&gt;_
Everyone is permitted to copy and distribute verbatim copies of this license
document, but changing it is not allowed.
## Preamble
The GNU General Public License is a free, copyleft license for software and other
kinds of works.
The licenses for most software and other practical works are designed to take away
your freedom to share and change the works. By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change all versions of a
program--to make sure it remains free software for all its users. We, the Free
Software Foundation, use the GNU General Public License for most of our software; it
applies also to any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General
Public Licenses are designed to make sure that you have the freedom to distribute
copies of free software (and charge for them if you wish), that you receive source
code or can get it if you want it, that you can change the software or use pieces of
it in new free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you these rights or
asking you to surrender the rights. Therefore, you have certain responsibilities if
you distribute copies of the software, or if you modify it: responsibilities to
respect the freedom of others.
For example, if you distribute copies of such a program, whether gratis or for a fee,
you must pass on to the recipients the same freedoms that you received. You must make
sure that they, too, receive or can get the source code. And you must show them these
terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps: **(1)** assert
copyright on the software, and **(2)** offer you this License giving you legal permission
to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains that there is
no warranty for this free software. For both users' and authors' sake, the GPL
requires that modified versions be marked as changed, so that their problems will not
be attributed erroneously to authors of previous versions.
Some devices are designed to deny users access to install or run modified versions of
the software inside them, although the manufacturer can do so. This is fundamentally
incompatible with the aim of protecting users' freedom to change the software. The
systematic pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we have designed
this version of the GPL to prohibit the practice for those products. If such problems
arise substantially in other domains, we stand ready to extend this provision to
those domains in future versions of the GPL, as needed to protect the freedom of
users.
Finally, every program is threatened constantly by software patents. States should
not allow patents to restrict development and use of software on general-purpose
computers, but in those that do, we wish to avoid the special danger that patents
applied to a free program could make it effectively proprietary. To prevent this, the
GPL assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and modification follow.
## TERMS AND CONDITIONS
### 0. Definitions
“This License” refers to version 3 of the GNU General Public License.
“Copyright” also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
“The Program” refers to any copyrightable work licensed under this
License. Each licensee is addressed as “you”. “Licensees” and
“recipients” may be individuals or organizations.
To “modify” a work means to copy from or adapt all or part of the work in
a fashion requiring copyright permission, other than the making of an exact copy. The
resulting work is called a “modified version” of the earlier work or a
work “based on” the earlier work.
A “covered work” means either the unmodified Program or a work based on
the Program.
To “propagate” a work means to do anything with it that, without
permission, would make you directly or secondarily liable for infringement under
applicable copyright law, except executing it on a computer or modifying a private
copy. Propagation includes copying, distribution (with or without modification),
making available to the public, and in some countries other activities as well.
To “convey” a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through a computer
network, with no transfer of a copy, is not conveying.
An interactive user interface displays “Appropriate Legal Notices” to the
extent that it includes a convenient and prominently visible feature that **(1)**
displays an appropriate copyright notice, and **(2)** tells the user that there is no
warranty for the work (except to the extent that warranties are provided), that
licensees may convey the work under this License, and how to view a copy of this
License. If the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
### 1. Source Code
The “source code” for a work means the preferred form of the work for
making modifications to it. “Object code” means any non-source form of a
work.
A “Standard Interface” means an interface that either is an official
standard defined by a recognized standards body, or, in the case of interfaces
specified for a particular programming language, one that is widely used among
developers working in that language.
The “System Libraries” of an executable work include anything, other than
the work as a whole, that **(a)** is included in the normal form of packaging a Major
Component, but which is not part of that Major Component, and **(b)** serves only to
enable use of the work with that Major Component, or to implement a Standard
Interface for which an implementation is available to the public in source code form.
A “Major Component”, in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system (if any) on which
the executable work runs, or a compiler used to produce the work, or an object code
interpreter used to run it.
The “Corresponding Source” for a work in object code form means all the
source code needed to generate, install, and (for an executable work) run the object
code and to modify the work, including scripts to control those activities. However,
it does not include the work's System Libraries, or general-purpose tools or
generally available free programs which are used unmodified in performing those
activities but which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for the work, and
the source code for shared libraries and dynamically linked subprograms that the work
is specifically designed to require, such as by intimate data communication or
control flow between those subprograms and other parts of the work.
The Corresponding Source need not include anything that users can regenerate
automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same work.
### 2. Basic Permissions
All rights granted under this License are granted for the term of copyright on the
Program, and are irrevocable provided the stated conditions are met. This License
explicitly affirms your unlimited permission to run the unmodified Program. The
output from running a covered work is covered by this License only if the output,
given its content, constitutes a covered work. This License acknowledges your rights
of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey, without
conditions so long as your license otherwise remains in force. You may convey covered
works to others for the sole purpose of having them make modifications exclusively
for you, or provide you with facilities for running those works, provided that you
comply with the terms of this License in conveying all material for which you do not
control copyright. Those thus making or running the covered works for you must do so
exclusively on your behalf, under your direction and control, on terms that prohibit
them from making any copies of your copyrighted material outside their relationship
with you.
Conveying under any other circumstances is permitted solely under the conditions
stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
### 3. Protecting Users' Legal Rights From Anti-Circumvention Law
No covered work shall be deemed part of an effective technological measure under any
applicable law fulfilling obligations under article 11 of the WIPO copyright treaty
adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention
of such measures.
When you convey a covered work, you waive any legal power to forbid circumvention of
technological measures to the extent such circumvention is effected by exercising
rights under this License with respect to the covered work, and you disclaim any
intention to limit operation or modification of the work as a means of enforcing,
against the work's users, your or third parties' legal rights to forbid circumvention
of technological measures.
### 4. Conveying Verbatim Copies
You may convey verbatim copies of the Program's source code as you receive it, in any
medium, provided that you conspicuously and appropriately publish on each copy an
appropriate copyright notice; keep intact all notices stating that this License and
any non-permissive terms added in accord with section 7 apply to the code; keep
intact all notices of the absence of any warranty; and give all recipients a copy of
this License along with the Program.
You may charge any price or no price for each copy that you convey, and you may offer
support or warranty protection for a fee.
### 5. Conveying Modified Source Versions
You may convey a work based on the Program, or the modifications to produce it from
the Program, in the form of source code under the terms of section 4, provided that
you also meet all of these conditions:
* **a)** The work must carry prominent notices stating that you modified it, and giving a
relevant date.
* **b)** The work must carry prominent notices stating that it is released under this
License and any conditions added under section 7. This requirement modifies the
requirement in section 4 to “keep intact all notices”.
* **c)** You must license the entire work, as a whole, under this License to anyone who
comes into possession of a copy. This License will therefore apply, along with any
applicable section 7 additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no permission to license the
work in any other way, but it does not invalidate such permission if you have
separately received it.
* **d)** If the work has interactive user interfaces, each must display Appropriate Legal
Notices; however, if the Program has interactive interfaces that do not display
Appropriate Legal Notices, your work need not make them do so.
A compilation of a covered work with other separate and independent works, which are
not by their nature extensions of the covered work, and which are not combined with
it such as to form a larger program, in or on a volume of a storage or distribution
medium, is called an “aggregate” if the compilation and its resulting
copyright are not used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work in an aggregate
does not cause this License to apply to the other parts of the aggregate.
### 6. Conveying Non-Source Forms
You may convey a covered work in object code form under the terms of sections 4 and
5, provided that you also convey the machine-readable Corresponding Source under the
terms of this License, in one of these ways:
* **a)** Convey the object code in, or embodied in, a physical product (including a
physical distribution medium), accompanied by the Corresponding Source fixed on a
durable physical medium customarily used for software interchange.
* **b)** Convey the object code in, or embodied in, a physical product (including a
physical distribution medium), accompanied by a written offer, valid for at least
three years and valid for as long as you offer spare parts or customer support for
that product model, to give anyone who possesses the object code either **(1)** a copy of
the Corresponding Source for all the software in the product that is covered by this
License, on a durable physical medium customarily used for software interchange, for
a price no more than your reasonable cost of physically performing this conveying of
source, or **(2)** access to copy the Corresponding Source from a network server at no
charge.
* **c)** Convey individual copies of the object code with a copy of the written offer to
provide the Corresponding Source. This alternative is allowed only occasionally and
noncommercially, and only if you received the object code with such an offer, in
accord with subsection 6b.
* **d)** Convey the object code by offering access from a designated place (gratis or for
a charge), and offer equivalent access to the Corresponding Source in the same way
through the same place at no further charge. You need not require recipients to copy