Verified Commit 1060d244 authored by Lars Bilke's avatar Lars Bilke

[web] Restructured get the source code and development workflows.

- The get the source code page now just references source code downloads
  as an archive.
- The GitLab and fork set up has been moved to the development workflows
  section.
- Added page on code review.
parent f06be701
......@@ -2,7 +2,7 @@
date = "2018-02-26T11:00:13+01:00"
title = "Code style and formatting"
author = "Lars Bilke"
weight = 1012
weight = 1014
[menu]
[menu.devguide]
......
......@@ -2,13 +2,31 @@
date = "2018-02-26T11:00:13+01:00"
title = "Code Reviews"
author = "Lars Bilke"
weight = 1014
weight = 1015
[menu]
[menu.devguide]
parent = "development-workflows"
+++
TODO!
Once you have submitted a [merge request]({{< ref "setup-fork.md/#optional-working-on-a-new-feature" >}}) the code review process kicks in which can be summarized as:
- [Good general introduction to GitHub](https://flaviocopes.com/github/)
- A core developer picks your MR for review.
- The core developer checks your code in respect to e.g. style and correctness.
- The core developer may also give hints on how to improve the code regarding to e.g. readability or performance.
- You iterate (make modifications) on the code.
- The core developer again checks the code and finally approves the changes.
- If also the [CI]({{< ref "continuous-integration.md" >}}) is happy (all checks and tests did pass) the MR is merged.
For more information on merge requests see the [GitLab documentation](https://docs.gitlab.com/ee/user/project/merge_requests/getting_started.html).
### How to request a code review
To request a code review set the merge request label to `workflow::please review`!
If you do not want a reviewer to have a look, e.g. because you are currently working on the MR you can set the merge request label to `workflow::in development` or `workflow::paused` (disables CI).
### How to indicate that the MR is ready for merge
- Set the merge request label to `workflow::please review`
- Remove the [`Draft`-flag](https://docs.gitlab.com/ee/user/project/merge_requests/drafts.html#mark-merge-requests-as-ready) (if you have set it previously)
......@@ -3,6 +3,7 @@ date = "2018-02-26T11:00:13+01:00"
title = "Development IDEs"
author = "Marc Walther"
weight = 1013
draft = true # This page is outdated
[menu]
[menu.devguide]
......
......@@ -2,11 +2,11 @@
date = "2018-02-26T11:00:13+01:00"
title = "Set Up GitLab"
author = "Lars Bilke"
weight = 1002
weight = 1012
[menu]
[menu.devguide]
parent = "getting-started"
parent = "development-workflows"
+++
## Introduction
......
+++
date = "2021-03-11T11:37"
title = "Introduction to Development Workflows"
author = "Lars Bilke"
weight = 1011
aliases = ["/docs/devguide/development-workflows"]
[menu.devguide]
parent = "development-workflows"
+++
You have already [build]({{< ref "/docs/devguide/getting-started/build.md" >}}) `ogs` and want to actively contribute to the project? Go ahead with section and especially follow these guides **step-by-step**:
- [Set Up GitLab]({{< ref "gitlab.md" >}})
- [Set Up your fork]({{< ref "setup-fork.md" >}})
Later you also want to get familiar with [coding style]({{< ref "code-format.md" >}}), the [code review]({{< ref "code-reviews.md" >}}) procedure as well as [continuous integration]({{< ref "continuous-integration.md" >}}).
+++
date = "2018-02-23T15:28:13+01:00"
title = "Branching model"
date = "2021-03-11T11:48"
title = "Set Up your fork"
author = "Lars Bilke"
weight = 1011
weight = 1013
aliases = ["/docs/devguide/development-workflows/branching-model"]
[menu]
[menu.devguide]
parent = "development-workflows"
+++
## Forking workflow
<div class='note'>
**Attribution**: The content of this page is largely taken from the [GitHub-blog](https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows).
</div>
## Explanation: Forking workflow
Git is very flexible in organizing a distributed development team. We use a so called **Forking workflow**.
......@@ -34,3 +41,98 @@ First thing to do when you start working on your local repository is to create a
Start committing changes in logical chunks. After you are happy with your implementation push your topic branch to your forked repository on GitLab.
Open a [*Merge Request*](https://docs.gitlab.com/ee/user/project/merge_requests/) which will initiate the code review process.
----
## Step: Create a fork
[Create a new fork](https://gitlab.opengeosys.org/ogs/ogs/-/forks/new) from the [official OGS-6 repository](https://gitlab.opengeosys.org/ogs/ogs).
This creates a new fork under your account with the URL `https://gitlab.opengeosys.org/YOUR-USERNAME/ogs`.
## Step: Setup your local clone
You can use the git command line tool to clone the remote repository on GitLab to your PC:
```bash
git clone --filter=blob:limit=100k git@gitlab.opengeosys.org:YOUR-USERNAME/ogs.git
cd ogs
git config remote.pushdefault origin
git config push.default current
```
This creates a new folder `ogs` in your current working directory with the OGS source code. After this step, the remote called `origin` refers to your fork on GitLab. It also sets the default remote for pushes to be `origin` and the default push behavior to `current`. Together this means that if you just type `git push`, the current branch is pushed to the `origin` remote.
<div class='note'>
The `--filter=blob:limit=100k`-parameter instructs git to only fetch files which are smaller than 100 Kbyte. Larger files (e.g. benchmark files, images, PDFs) are fetched on-demand only. This happens automatically and [is a replacement for the previous Git LFS tracked files](https://github.com/ufz/ogs/issues/2961). Requires **git 2.22**!
</div>
Create a second remote called `upstream` that points at the main OGS repository and fetch from it:
```bash
git remote add upstream https://gitlab.opengeosys.org/ogs/ogs.git
git fetch upstream
```
<!-- TODO: rerecord with GitLab -->
<!-- {{< asciinema url="https://asciinema.org/a/249002" speed="3" rows="20" >}} -->
## Optional: Enable git commit hooks
[Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) help to check for several issues before doing commits or pushes and it is highly recommended to enable these checks.
Install [pre-commit](https://pre-commit.com/) (a git hook manager) via Pythons `pip`:
```bash
pip3 install --user pre-commit
```
This installed `pre-commit` to `.local/bin` in your home directory or to `C:\Users\[username]\AppData\Roaming\Python\Python37\Scripts` on Windows. Make sure to have this directory in your `PATH`!
Enable the hooks in the source code with:
```bash
cd ogs
pre-commit install
```
## Optional: Working on a new feature
You only have to follow the above steps once. From then on, whenever you want to work on a new feature, you can more easily interact with the remote repositories.
Make sure that your local repository is up-to-date with the upstream repository:
```bash
git fetch upstream
```
Create a branch `feature-name` off of upstream `master`-branch to work on a new feature, and check out the branch:
```bash
git checkout -b feature-name upstream/master
```
This automatically sets up your local `new-feature`-branch to track the upstream `master`-branch. This means that if more commits are added to `master` upstream, you can merge those commits into your `feature`-branch by typing
```bash
git pull
```
or rebase your branch on top of the new master by typing
```bash
git pull --rebase
```
Now after you implemented the feature and committed your work you can push the new commits to the `feature-name`-branch on your GitLab fork:
```bash
git push
```
If your work is done submit a [merge request](https://gitlab.opengeosys.org/ogs/ogs/-/merge_requests/new).
This workflow is summarized with this picture:
![Workflow visualization](https://cloud.githubusercontent.com/assets/1319791/8943755/5dcdcae4-354a-11e5-9f82-915914fad4f7.png)
......@@ -54,4 +54,4 @@ So now the build process is running... This can take some time because maybe the
Congratulations you have finished the **Getting Started**-section!
Have a look at the other sections of this guide. Maybe check out [Development Workflows]({{< ref "branching-model" >}}) if you are interested in actively contributing to the project. The [Configuration Options]({{< ref "configuration-options" >}})-page shows you all available build customizations. Go ahead!
Have a look at the other sections of this guide. Check out [Development Workflows]({{< ref "/docs/devguide/development-workflows/introduction.md" >}}) if you are interested in actively contributing to the project. The [Configuration Options]({{< ref "configuration-options" >}})-page shows you all available build customizations. Go ahead!
......@@ -11,100 +11,19 @@ weight = 1003
<div class='note'>
### Attribution
<i class="far fa-exclamation-triangle"></i> This page describes how to get the source code as a simple download. The information on the forking workflow with `git` has been moved to the [Development workflows]({{< ref "setup-fork.md" >}})-section.
The content of this page is largely taken from the [GitHub-blog](https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows).
</div>
## Create a fork
## Download the source code
[Create a new fork](https://gitlab.opengeosys.org/ogs/ogs/-/forks/new) from the [official OGS-6 repository](https://gitlab.opengeosys.org/ogs/ogs).
To get the latest source code simply download it from [repository website](https://gitlab.opengeosys.org/ogs/ogs) and extract the archive:
This creates a new fork under your account with the URL `https://gitlab.opengeosys.org/YOUR-USERNAME/ogs`.
![](../zip-download.png)
## Setup your local clone
You can use the git command line tool to clone the remote repository on GitLab to your PC:
```bash
git clone --filter=blob:limit=100k git@gitlab.opengeosys.org:YOUR-USERNAME/ogs.git
cd ogs
git config remote.pushdefault origin
git config push.default current
```
This creates a new folder `ogs` in your current working directory with the OGS source code. After this step, the remote called `origin` refers to your fork on GitLab. It also sets the default remote for pushes to be `origin` and the default push behavior to `current`. Together this means that if you just type `git push`, the current branch is pushed to the `origin` remote.
<div class='note'>
The `--filter=blob:limit=100k`-parameter instructs git to only fetch files which are smaller than 100 Kbyte. Larger files (e.g. benchmark files, images, PDFs) are fetched on-demand only. This happens automatically and [is a replacement for the previous Git LFS tracked files](https://github.com/ufz/ogs/issues/2961). Requires **git 2.22**!
</div>
Create a second remote called `upstream` that points at the main OGS repository and fetch from it:
```bash
git remote add upstream https://gitlab.opengeosys.org/ogs/ogs.git
git fetch upstream
```
<!-- TODO: rerecord with GitLab -->
<!-- {{< asciinema url="https://asciinema.org/a/249002" speed="3" rows="20" >}} -->
## Enable git commit hooks
[Git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) help to check for several issues before doing commits or pushes and it is highly recommended to enable these checks.
Install [pre-commit](https://pre-commit.com/) (a git hook manager) via Pythons `pip`:
You can also download and extract with the command line:
```bash
pip3 install --user pre-commit
wget https://gitlab.opengeosys.org/ogs/ogs/-/archive/master/ogs-master.tar.gz
tar xf ogs-master.tar.gz
```
This installed `pre-commit` to `.local/bin` in your home directory or to `C:\Users\[username]\AppData\Roaming\Python\Python37\Scripts` on Windows. Make sure to have this directory in your `PATH`!
Enable the hooks in the source code with:
```bash
cd ogs
pre-commit install
```
## Optional: Working on a new feature
You only have to follow the above steps once. From then on, whenever you want to work on a new feature, you can more easily interact with the remote repositories.
Make sure that your local repository is up-to-date with the upstream repository:
```bash
git fetch upstream
```
Create a branch `feature-name` off of upstream `master`-branch to work on a new feature, and check out the branch:
```bash
git checkout -b feature-name upstream/master
```
This automatically sets up your local `new-feature`-branch to track the upstream `master`-branch. This means that if more commits are added to `master` upstream, you can merge those commits into your `feature`-branch by typing
```bash
git pull
```
or rebase your branch on top of the new master by typing
```bash
git pull --rebase
```
Now after you implemented the feature and committed your work you can push the new commits to the `feature-name`-branch on your GitLab fork:
```bash
git push
```
If your work is done submit a [merge request](https://gitlab.opengeosys.org/ogs/ogs/-/merge_requests/new).
This workflow is summarized with this picture:
![Workflow visualization](https://cloud.githubusercontent.com/assets/1319791/8943755/5dcdcae4-354a-11e5-9f82-915914fad4f7.png)
......@@ -17,6 +17,8 @@ parent = "getting-started"
+++
In this help section you will find everything related to development. Please walk through the Getting Started-section **step by step**. At the end you will have the latest OGS source code, the OGS finite element simulator compiled and everything you need to start developing for OGS! This first section of the developer guide will give you just a brief introduction, make sure to read the more advanced topics after you have familiarized yourself with the basics.
In this help section you will find everything related to development. Please walk through the Getting Started-section **step by step**. At the end you will have the latest OGS source code and the OGS finite element simulator compiled and ready to run! This first section of the developer guide will give you just a brief introduction, make sure to read the more advanced topics after you have familiarized yourself with the basics.
If you **want to contribute** to the OGS project please also walk through the [Development Workflows]({{< ref "/docs/devguide/development-workflows/introduction.md" >}})-section **step-by-step**.
Instructions may differ depending on your operating system (OS). Be sure to pick the right one in the **OS selector** at the top of the **next page**.
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