GITHUB Quick Documentation for Contributors

This section 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://help.github.com/en.

Prerequisites

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

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

  • Replace your-username with your username on GitHub.

  • Replace feature-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.

    _images/fork.png

    Figure 4 Fork the repository.

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

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

    git clone git@github.com:your-username/bdp-core.git
    
    _images/checkout.png

    Figure 5 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 feature-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 feature-branch
    
  5. Navigate to your feature branch on Github (https://github.com/your-username/bdp-core/pull/new/feature-branch) to create a new pull request (see Figure 6).

    _images/create-pull-request-development.png

    Figure 6 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 7

    _images/show-pull-request-ok-development.png

    Figure 7 Show outcome of a pull request.

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

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 https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/configuring-a-remote-for-a-fork

  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://help.github.com/en/github/collaborating-with-issues-and-pull-requests/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 8.

_images/merge-conflicts-conflicts-development.png

Figure 8 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.

    git checkout feature-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 9.

    _images/merge-conflicts-output-development.png

    Figure 9 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.

    _images/merge-conflicts-solving-development.png

    Figure 10 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.

    _images/merge-conflicts-resolved-development.png

    Figure 11 A solved merge conflict.

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