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.
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.
$USERNAMEwith your username on GitHub.
$BRANCHwith the branch name you will develop in your forked version.
Before starting the development, you need to fork the original (upstream) repository.
Navigate to the repository on GitHub, e.g., https://github.com/noi-techpark/bdp-core.
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.
Navigate to your forked repository on GitHub, e.g., https://github.com/$USERNAME/bdp-core.
Check out the forked repository on your local machine, using the link that appears in your repository (see Figure 11):
~$ git clone firstname.lastname@example.org:$USERNAME/bdp-core.git
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.
Checkout the development branch:
~$ git checkout development
Create a new branch from the development branch locally on your machine:
~$ git checkout -b $BRANCH
Make some changes to the code and commit them:
~$ git add -A ~$ git commit -m "Some commit message"
Push the new branch to GitHub:
~$ git push --set-upstream origin $BRANCH
Navigate to your feature branch on Github (https://github.com/$USERNAME/bdp-core/pull/new/$BRANCH) to create a new pull request (see Figure 12).
You can write some description as well, to describe your changes.
Commit and push any changes of the pull request to this new branch.
For every commit the continuous integration pipeline will execute the tests and display the results in the pull request, like shown in Figure 13
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
List the current configured remote repository for your fork.
~$ git remote -v
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
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
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
Check out your fork’s local development branch.
~$ git checkout development
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 14.
To resolve merge conflicts, the following steps must be performed.
Sync your forked repository and make sure your local destination (development) branch is up to date with the original (upstream) repository branch.
Check out your feature branch.
~$ git checkout $BRANCH
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 15.
Go the the listed files of the previous output and resolve all merge conflicts. The conflicts in the files begin with
<<<<<<<and end with
=======separates the two versions.
You can resolve a conflict by simply deleting one of the two versions of the code and the inserted helper lines beginning with
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.
Add all resolved files to the index, commit the changes and push the changes to the server.
~$ git add -A ~$ git commit ~$ git push
After resolving the merge conflicts, the pull request can be accepted.
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.