GITHUB Quick Howto

This howto guides you in setting up on your local workstation the (forked) git repositories needed to contribute to the Open Data Hub project, along with some troubleshooting concerning pull requests and merge conflicts. For more detailed help, please refer to the online Github help, at https://docs.github.com/en/.

Prerequisites

There are no particular requirements to be satisfied to set up a workstation to work on Open Data Hub code, besides the standard software git and an IDE of your choice.

However, depending on the contribution you want to give, you may need to install some of the software used by the Open Data Hub, so make sure that you read the Guidelines for Developers to understand if you need to install some more software.

You also need an account on Github to be able to fork projects and contribute to the Open Data Hub project.

Conventions

In the following documentation some example names are used. Please replace them with suitable values:

• Replace $USERNAME with your username on GitHub.

• Replace $BRANCH with the branch name you will develop in your forked version.

Project Checkout

Before starting the development, you need to fork the original (upstream) repository.

1. Navigate to the repository on GitHub, e.g., https://github.com/noi-techpark/bdp-core.

2. Create a fork of the repository by clicking on the Fork button. If you are not logged in, you will be asked for a github username and password.

   

   Figure 33 Fork the repository.

3. Navigate to your forked repository on GitHub, e.g., https://github.com/$USERNAME/bdp-core.

4. Check out the forked repository on your local machine, using the link that appears in your repository (see Figure 34):

   ~$ git clone git@github.com:$USERNAME/bdp-core.git
   

   

   Figure 34 Clone the repository.

Create a pull request

In order to let your contribution be accepted in the Open Data Hub code base, you need to follow the following steps.

1. Checkout the development branch:

   ~$ git checkout development
   

2. Create a new branch from the development branch locally on your machine:

   ~$ git checkout -b test-branch
   

3. Make some changes to the code and commit them:

   ~$ git add -A
   ~$ git commit -m "Some commit message"
   

4. Push the new branch to GitHub:

   ~$ git push --set-upstream origin test-branch
   

5. Navigate to your feature branch on Github (https://github.com/$USERNAME/bdp-core/pull/new/$BRANCH) to create a new pull request (see Figure 35).

   

   Figure 35 Create a pull request.

   You can write some description as well, to describe your changes.

6. Commit and push any changes of the pull request to this new branch.

7. For every commit the continuous integration pipeline will execute the tests and display the results in the pull request, like shown in Figure 36

   

   Figure 36 Show outcome of a pull request.

8. In addition, the detailed logs can be viewed under https://ci.opendatahub.com.

Syncing a Fork

Your forked repository does not receive the updates of the original repository automatically. To sync for example the development branch of the two repositories and to keep the forked repository up-to-date with all the latest changes of the development branch from the original repository, the following steps have to be performed.

Before you can sync your fork with the original repository (an upstream repository), you must configure a remote that points to the upstream repository in Git. A more detailed description for the following steps can be found in the online Github help.

1. List the current configured remote repository for your fork.

   ~$ git remote -v
   

2. Specify a new remote upstream repository that will be synced with the fork.

   ~$ git remote add upstream https://github.com/noi-techpark/bdp-core.git
   

3. Verify the new upstream repository you’ve specified for your fork.

   ~$ git remote -v
   

You need sync a fork of a repository to keep it up-to-date with the original repository (upstream repository). A more detailed description for the following steps can be found in the online Github help https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork.

1. Fetch the branches and their respective commits from the upstream repository. Commits to development will be stored in a local branch, upstream/development

   ~$ git fetch upstream
   

2. Check out your fork’s local development branch.

   ~$ git checkout development
   

3. Merge the changes from upstream/development into your local development branch. This brings your fork’s development branch into sync with the upstream repository, without losing your local changes.

   ~$ git merge upstream/development
   

Resolving Merge Conflicts

When creating and working on a pull request, it could happen that the destination branch of the original repository will change. These changes could result in merge conflicts when pulling your code, like shown in Figure 37.

Figure 37 A Merge Conflict.

To resolve merge conflicts, the following steps must be performed.

1. Sync your forked repository and make sure your local destination (development) branch is up to date with the original (upstream) repository branch.

2. Check out your feature branch (replace $BRANCH with the actual branch name).

   ~$ git checkout $BRANCH
   

3. Merge the changes of the development branch to the feature branch.

   ~$ git merge development
   

   The command will output the files with merge conflicts. See sample output in Figure 38.

   

   Figure 38 Merge conflicts output.

4. Go the the listed files of the previous output and resolve all merge conflicts. The conflicts in the files begin with <<<<<<< and end with >>>>>>>. The ======= separates the two versions.

   

   Figure 39 Solving a merge conflicts.

   You can resolve a conflict by simply deleting one of the two versions of the code and the inserted helper lines beginning with <<<<<<<, =======, and >>>>>>>.

   If none of the two versions is completely correct, then you can delete the conflict entirely and write your own code to solve the conflict.

5. Add all resolved files to the index, commit the changes and push the changes to the server.

   ~$ git add -A
   ~$ git commit
   ~$ git push
   

6. After resolving the merge conflicts, the pull request can be accepted.

   

   Figure 40 A solved merge conflict.

A more detailed description can be found in the online Github help: ttps://docs.github.com/en/github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line