Include section about Review Apps in "Create Post" blog post and Contribution Guide

Blog post:
* changed publication date
* added section which explains Review Apps
* added screenshot
* rephrased text duplications
* fixed typos
* referenced contribution guide

Contribution guide:
* added section which explains Review Apps
* rephrased text duplications
* fixed typos
* referenced blog post
parent 4e7f3b7d
Pipeline #18689 passed with stages
in 4 minutes and 22 seconds
......@@ -9,6 +9,13 @@ 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]({{ 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")
explaining the suggested workflow in the blog post section
of the web-page.
## Code Guidelines and Best Practices
### Common Style Guides
......@@ -19,13 +26,6 @@ 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.
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/10/09/Workflow-to-Create-a-new-Blog-Post.html' | relative_url }} "Workflow to Create a New Blog Post")
explaining the suggested workflow in the Blog Post section
of the web-page.
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
......@@ -174,9 +174,38 @@ 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.
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.
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
......
---
title: Workflow to Create a New Blog Post
date: 2019-10-09
date: 2019-11-22
authors:
- hueser
layout: default
......@@ -9,7 +9,7 @@ excerpt_separator: <!--more-->
categories: [hifis, blog]
tags: [startblogging, guidedtour]
additional_css:
- 2019-10-09-Workflow-to-Create-a-new-Blog-Post/create_blog_post.css
- 2019-11-22-Workflow-to-Create-a-new-Blog-Post/create_blog_post.css
---
## TL;DR
......@@ -26,6 +26,12 @@ while a proper review process is still essential for the quality of
the blog posts.
So let us jump into it.
Note:
In case you are interested to know how to contribute
to _HIFIS Software_ web-page in general besides writing blog posts
you can find more information in the Contribution Guide
<sup>[[1]](https://gitlab.hzdr.de/hifis/software.hifis.net/blob/master/CONTRIBUTING.md "Contribution Guide")</sup>.
## Tools explained
First, I would like to introduce three tools which are very helpful
......@@ -34,8 +40,8 @@ if you are going to write a blog post.
**Version Control System _Git_**
_Git_
<sup>[[1]](https://en.wikipedia.org/wiki/Git "Git (Wikipedia)")</sup>
is a decentralized version control system which let you
<sup>[[2]](https://en.wikipedia.org/wiki/Git "Git (Wikipedia)")</sup>
is a decentralized version control system which lets you
store all files of your project and all snapshots / versions
of your changes.
It lets you track back the complete history
......@@ -46,7 +52,7 @@ local computer.
**Version Management Platform _GitLab_**
_GitLab_
<sup>[[2]](https://en.wikipedia.org/wiki/GitLab "GitLab (Wikipedia)")</sup>
<sup>[[3]](https://en.wikipedia.org/wiki/GitLab "GitLab (Wikipedia)")</sup>
provides you with user interfaces for several actions which can be
done on the remote server without downloading the whole repository
onto your local computer.
......@@ -62,7 +68,7 @@ to contribute with your blog posts.
**Static Web Site Generator _Jekyll_**
_Jekyll_
<sup>[[3]](https://en.wikipedia.org/wiki/Jekyll_(software) "Jekyll (Wikipedia)")</sup>
<sup>[[4]](https://en.wikipedia.org/wiki/Jekyll_(software) "Jekyll (Wikipedia)")</sup>
is a static web site generator.
You only write _Markdown_ text files and _Jekyll_ takes care of the
rest and generates a static web site containing only HTML and CSS
......@@ -112,10 +118,10 @@ like to blog about.
Open a new issue in the _GitLab UI_.
In order to do so, you need an account in GitLab of HZDR
<sup>[[4]](https://gitlab.hzdr.de "HZDR GitLab Instance")</sup>
<sup>[[5]](https://gitlab.hzdr.de "HZDR GitLab Instance")</sup>
and being added as member to the respective GitLab project.
Opening an issue is explained in the _GitLab Docs_
<sup>[[5]](https://docs.gitlab.com/ce/user/project/issues/managing_issues.html "Managing GitLab Issues")</sup>.
<sup>[[6](https://docs.gitlab.com/ce/user/project/issues/managing_issues.html "Managing GitLab Issues")</sup>.
It is essential to give it a comprehensive _title_ and _description_
which reflects the basic idea of the topic.
It is recommended to use the predefined _Issue Template_ "_blog-post_"
......@@ -128,19 +134,19 @@ If you use the template this will be done automatically for you.
The images below show such a blog-post issue as well as the
pre-defined description text and questions to answer.
![Blog Post Template View]({{ site.directory.images | append: '2019-10-09-Workflow-to-Create-a-new-Blog-Post/Screenshot_Blog_Post_Template_View_20191113.png' | relative_url }} "Blog Post Template View"){:.blog_post_template_image}
![Blog Post Template View]({{ site.directory.images | append: '2019-11-22-Workflow-to-Create-a-new-Blog-Post/Screenshot_Blog_Post_Template_View_20191113.png' | relative_url }} "Blog Post Template View"){:.blog_post_template_image}
![Blog Post Template Text]({{ site.directory.images | append: '2019-10-09-Workflow-to-Create-a-new-Blog-Post/Screenshot_Blog_Post_Template_Text_20191113.png' | relative_url }} "Blog Post Template Text"){:.blog_post_template_image}
![Blog Post Template Text]({{ site.directory.images | append: '2019-11-22-Workflow-to-Create-a-new-Blog-Post/Screenshot_Blog_Post_Template_Text_20191113.png' | relative_url }} "Blog Post Template Text"){:.blog_post_template_image}
**2. Write and Share your Post**
The next step is to create a Feature Branch based on branch _master_
and give it a meaningful name like `<issue_number>-<branch_name>`.
This can be done within the _GitLab User-Interfaces_
<sup>[[6]](https://docs.gitlab.com/ce/user/project/repository/web_editor.html#create-a-new-branch "Create a new Branch in GitLab")</sup>.
<sup>[[7]](https://docs.gitlab.com/ce/user/project/repository/web_editor.html#create-a-new-branch "Create a new Branch in GitLab")</sup>.
Navigate into this branch in _GitLab_ and open _GitLab Web IDE_
<sup>[[7]](https://docs.gitlab.com/ce/user/project/web_ide/#open-the-web-ide "Open GitLab Web IDE")</sup>.
<sup>[[8]](https://docs.gitlab.com/ce/user/project/web_ide/#open-the-web-ide "Open GitLab Web IDE")</sup>.
_GitLab Web IDE_ is the preferred tool to contribute if you are
unfamiliar with _Git_.
......@@ -163,14 +169,14 @@ You can check that everything you wrote is displayed as intended.
Now you are ready to start writing your _Markdown_ file following the specific
syntax of _Markdown_ files
<sup>[[8]](https://docs.gitlab.com/ce/user/markdown.html "GitLab Markdown")</sup>.
<sup>[[9]](https://docs.gitlab.com/ce/user/markdown.html "GitLab Markdown")</sup>.
Once you are done with your editing you would like to _stage_ and _commit_
your changes
<sup>[[9]](https://docs.gitlab.com/ce/user/project/web_ide/#stage-and-commit-changes "Stage and Commit Changes in GitLab Web IDE")</sup>
<sup>[[10]](https://docs.gitlab.com/ce/user/project/web_ide/#stage-and-commit-changes "Stage and Commit Changes in GitLab Web IDE")</sup>
giving it a meaningful message explaining your changes.
There is a blog post
<sup>[[10]](https://chris.beams.io/posts/git-commit/ "Best Practice of Git Commit Messages")</sup>
<sup>[[11]](https://chris.beams.io/posts/git-commit/ "Best Practice of Git Commit Messages")</sup>
about best practices for writing _Git_ commit messages.
The more verbose your messages are, the easier it is for others
to understand your changes.
......@@ -180,9 +186,9 @@ to understand your changes.
After some effort and a few commits, let us assume your blog post
is in a state where you consider it ready to see the light of day.
What you want to do at this point is to open a _Merge Request_
<sup>[[11]](https://docs.gitlab.com/ce/user/project/merge_requests/ "Merge Request")</sup>.
<sup>[[12]](https://docs.gitlab.com/ce/user/project/merge_requests/ "Merge Request")</sup>.
_GitLab's User-Interface_ lets you open _Merge Requests_
<sup>[[12]](https://docs.gitlab.com/ce/user/project/merge_requests/creating_merge_requests.html "Creating a Merge Request in GitLab")</sup>.
<sup>[[13]](https://docs.gitlab.com/ce/user/project/merge_requests/creating_merge_requests.html "Creating a Merge Request in GitLab")</sup>.
Give it a meaningful title and description and mention the
original issue as well (e.g. by stating "_Closes #<issue_number>._" in
the description).
......@@ -193,9 +199,27 @@ This is an important quality gate.
Do not rely on reviewing your own work.
Please select at least one other reviewer.
All comments on your _Merge Request_ appear as separate discussion
threads which need to be resolved by the reviewers before they can
actually merge your changes into branch _master_.
In order to make the review process as easy as possible GitLab
offers a feature called _Review Apps_ to inspect your branch.
This enables the blog post authors as well as reviewers to preview
the page in a test environment.
As soon as your your branch is pushed onto the remote
repository and the _GitLab CI Pipeline_ responsible for
deploying your branch finished successfully,
you can inspect your latest deployments of your branch
by clicking the button _View app_ in the User-Interface of your
Merge Request.
![Review Apps Button]({{ site.directory.images | append: '2019-11-22-Workflow-to-Create-a-new-Blog-Post/Screenshot_Review_Apps_01_20191121.png' | relative_url }} "Review Apps Button"){:.review_apps_button}
To access these pages you need to authenticate.
The credentials are as follows:
Username: `hifis`, Password: `HIFISReview!`.
As soon as someone reviews your blog post, all comments on your
_Merge Request_ appear as separate discussion threads which need
to be resolved by the reviewers before they can actually merge your
changes into branch _master_.
This means that you first discuss and integrate the suggestions into
your post as well as secondly add and commit changes to your branch.
......@@ -207,7 +231,7 @@ _GitLab_.
This tells _GitLab_ to integrate your changes into branch _master_.
By clicking that button a _GitLab CI (Continuous Integration) Pipeline_
<sup>[[13]](https://docs.gitlab.com/ce/ci/introduction/index.html "GitLab CI (Continuous Integration) Pipeline")</sup>
<sup>[[14]](https://docs.gitlab.com/ce/ci/introduction/index.html "GitLab CI (Continuous Integration) Pipeline")</sup>
is started and makes checks whether _Jekyll_ can still build the
whole project.
In case all is fine, this is indicated by a success icon.
......@@ -233,7 +257,7 @@ of the highest quality.
If you are looking for a good _Git_ tutorial I would like to suggest
the one from the _Software Carpentry_ group
<sup>[[14]](http://swcarpentry.github.io/git-novice/ "Software Carpentry Git Lessons")</sup>.
<sup>[[15]](http://swcarpentry.github.io/git-novice/ "Software Carpentry Git Lessons")</sup>.
_So what are the topics you would like to talk about today?_
Give it a try and let us know what your thoughts are which
......@@ -241,17 +265,18 @@ you would like to share with us.
## References
* [[1]](https://en.wikipedia.org/wiki/Git "Git (Wikipedia)") Git (Wikipedia)
* [[2]](https://en.wikipedia.org/wiki/GitLab "GitLab (Wikipedia)") GitLab (Wikipedia)
* [[3]](https://en.wikipedia.org/wiki/Jekyll_(software) "Jekyll (Wikipedia)") Jekyll (Wikipedia)
* [[4]](https://gitlab.hzdr.de "HZDR GitLab Instance") HZDR GitLab Instance
* [[5]](https://docs.gitlab.com/ce/user/project/issues/managing_issues.html "Managing GitLab Issues") Managing GitLab Issues
* [[6]](https://docs.gitlab.com/ce/user/project/repository/web_editor.html#create-a-new-branch "Create a new Branch in GitLab") Create a new Branch in GitLab
* [[7]](hhttps://docs.gitlab.com/ce/user/project/web_ide/#open-the-web-ide "Open GitLab Web IDE") Open GitLab Web IDE
* [[8]](https://docs.gitlab.com/ce/user/markdown.html "GitLab Markdown") GitLab Markdown
* [[9]](https://docs.gitlab.com/ce/user/project/web_ide/#stage-and-commit-changes "Stage and Commit Changes in GitLab Web IDE") Stage and Commit Changes in GitLab Web IDE
* [[10]](https://chris.beams.io/posts/git-commit/ "Best Practice of Git Commit Messages") Best Practice of Git Commit Messages
* [[11]](https://docs.gitlab.com/ce/user/project/merge_requests/ "Merge Request") Merge Request
* [[12]](https://docs.gitlab.com/ce/user/project/merge_requests/creating_merge_requests.html "Creating a Merge Request in GitLab") Creating a Merge Request in GitLab
* [[13]](https://docs.gitlab.com/ce/ci/introduction/index.html "GitLab CI (Continuous Integration) Pipeline") GitLab CI (Continuous Integration) Pipeline
* [[14]](http://swcarpentry.github.io/git-novice/ "Software Carpentry Git Lessons") Software Carpentry Git Lessons
* [[1]](https://gitlab.hzdr.de/hifis/software.hifis.net/blob/master/CONTRIBUTING.md "Contribution Guide") Contribution Guide
* [[2]](https://en.wikipedia.org/wiki/Git "Git (Wikipedia)") Git (Wikipedia)
* [[3]](https://en.wikipedia.org/wiki/GitLab "GitLab (Wikipedia)") GitLab (Wikipedia)
* [[4]](https://en.wikipedia.org/wiki/Jekyll_(software) "Jekyll (Wikipedia)") Jekyll (Wikipedia)
* [[5]](https://gitlab.hzdr.de "HZDR GitLab Instance") HZDR GitLab Instance
* [[6]](https://docs.gitlab.com/ce/user/project/issues/managing_issues.html "Managing GitLab Issues") Managing GitLab Issues
* [[7]](https://docs.gitlab.com/ce/user/project/repository/web_editor.html#create-a-new-branch "Create a new Branch in GitLab") Create a new Branch in GitLab
* [[8]](hhttps://docs.gitlab.com/ce/user/project/web_ide/#open-the-web-ide "Open GitLab Web IDE") Open GitLab Web IDE
* [[9]](https://docs.gitlab.com/ce/user/markdown.html "GitLab Markdown") GitLab Markdown
* [[10]](https://docs.gitlab.com/ce/user/project/web_ide/#stage-and-commit-changes "Stage and Commit Changes in GitLab Web IDE") Stage and Commit Changes in GitLab Web IDE
* [[11]](https://chris.beams.io/posts/git-commit/ "Best Practice of Git Commit Messages") Best Practice of Git Commit Messages
* [[12]](https://docs.gitlab.com/ce/user/project/merge_requests/ "Merge Request") Merge Request
* [[13]](https://docs.gitlab.com/ce/user/project/merge_requests/creating_merge_requests.html "Creating a Merge Request in GitLab") Creating a Merge Request in GitLab
* [[14]](https://docs.gitlab.com/ce/ci/introduction/index.html "GitLab CI (Continuous Integration) Pipeline") GitLab CI (Continuous Integration) Pipeline
* [[15]](http://swcarpentry.github.io/git-novice/ "Software Carpentry Git Lessons") Software Carpentry Git Lessons
......@@ -14,3 +14,13 @@
border: 1px solid $color-content-light-gray;
padding: 0.5rem;
}
.review_apps_button {
@include respond-to-medium(width, 75%, 100%, 100%);
max-width: 850px;
display: block;
margin-left: auto;
margin-right: auto;
border: 1px solid $color-content-light-gray;
padding: 0.5rem;
}
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