Skip to content

GitLab

Commit 0851a75b authored by Hueser, Christian (FWCC) - 138593's avatar Hueser, Christian (FWCC) - 138593
Browse files
Options

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
          Hide whitespace changes
          Inline Side-by-side
          Showing with 110 additions and 46 deletions
          CONTRIBUTING.md
          View file @ 0851a75b
          ......@@ -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
          ......
          _posts/2019-10-09-Workflow-to-Create-a-new-Blog-Post.md → _posts/2019-11-22-Workflow-to-Create-a-new-Blog-Post.md
          View file @ 0851a75b
          ---
          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
          assets/css/2019-10-09-Workflow-to-Create-a-new-Blog-Post/create_blog_post.scss → assets/css/2019-11-22-Workflow-to-Create-a-new-Blog-Post/create_blog_post.scss
          View file @ 0851a75b
          ......@@ -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

          Privacy | Imprint | Support | Status