Commit 88b18464 authored by Huste, Tobias (FWCC) - 111645's avatar Huste, Tobias (FWCC) - 111645 Committed by Erxleben, Fredo (FWCC) - 136987

Restructure contribution guide

- Move style guides to the bottom into one section
- Move workflow section to the top
parent 9c5f9e0c
Pipeline #19768 passed with stages
in 3 minutes and 52 seconds
---
layout: default
title: Contribution Guide
---
# Contribution Guide
Hey, you are interested in contributing to the web-page of _HIFIS Software_?
......@@ -12,10 +16,113 @@ 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]({{ site.baseurl | append: '/hifis/blog/2019/11/22/Workflow-to-Create-a-new-Blog-Post.html' | relative_url }} "Workflow to Create a New Blog Post")
[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
......@@ -120,113 +227,10 @@ $ gem install rubocop
$ rubocop path/to/ruby/code/folder/
```
## 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.
## Specific Aspects in our Style Guide
### Specific Aspects in our Style Guide
### User Interaction Considerations
**Offer Alternatives to Hover Interaction**
#### 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
......@@ -245,8 +249,8 @@ 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**
#### 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
......@@ -272,8 +276,8 @@ p {
See the `_sass` folder for definitions, grouped by context.
### HTML
**Write Comments in _Liquid_ tags**
#### HTML
##### Write Comments in _Liquid_ tags
Please use _Liquid_ comments in your HTML files to avoid them showing up in the
rendered version.
Example:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment