Set Up your fork

Explanation: Forking workflow

Git is very flexible in organizing a distributed development team. We use a so called Forking workflow.

The following explanation is taken from an in-depth article on that model:

Instead of using a single server-side repository to act as the central codebase, it gives every developer a server-side repository. This means that each contributor has not one, but two Git repositories: a private local one and a public server-side one.

The main advantage of the Forking Workflow is that contributions can be integrated without the need for everybody to push to a single central repository. Developers push to their own server-side repositories, and only the project maintainer can push to the official repository. This allows the maintainer to accept commits from any developer without giving them write access to the official codebase.

The result is a distributed workflow that provides a flexible way for large, organic teams (including not trusted third-parties) to collaborate securely. This also makes it an ideal workflow for open source projects.

www.atlassian.com/git/tutorials/comparing-workflows#!workflow-forking

The workflow is summarized in the following image from the GitHub blog:

First thing to do when you start working on your local repository is to create a topic branch (based on the current master branch of the official repository) specific to a well defined feature or bugfix you are about to implement. Never work on the master-branch (it is reserved for the official version)! See also this tutorial on branching.

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 which will initiate the code review process.

Step: Create a fork

Create a new fork from the official OGS-6 repository.

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:

git clone --filter=blob:limit=100k git@gitlab.opengeosys.org:YOUR-USERNAME/ogs.git

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.

Local clone git settings

After that initially set some useful git settings for your local repo:

cd ogs

The following 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.

git config remote.pushdefault origin
git config push.default current

To streamline the updating workflow the rebase-command is configured to handle local modifications automatically (autostash). See this blog post on more information about the git rebase --autostash-functionality.

git config rebase.autoStash true

Create a second remote called upstream that points at the official OGS repository and fetch from it:

git remote add upstream https://gitlab.opengeosys.org/ogs/ogs.git
git fetch upstream

Optional: Enable git commit hooks

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 (a git hook manager) via Pythons pip:

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:

cd ogs
pre-commit install

You will also need to install clang-format:

sudo apt-install clang-format

brew install clang-format

Step: 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:

git fetch upstream

Create a branch feature-name off of upstream/master-branch to work on a new feature, and check out the branch:

git checkout -b feature-name upstream/master

To keep up to date with the developments in the official repository it is recommended to rebase your feature-branch regularly (at least weekly) with:

git fetch upstream
git rebase upstream/master

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:

git push -u origin feature-name  # -u is required only first time to set up the remote-tracking.

git push --force origin feature-name

If your work is done submit a merge request.

Again this triangular workflow is summarized with this picture:

[…] the Forking Workflow requires two remotes—one for the official repository, and one for the developer’s personal server-side repository. While you can call these remotes anything you want, a common convention is to use origin as the remote for your forked repository […] and upstream for the official repository.

www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow