git

The Carob project is developed using “git”. This system allows for collaborative work and incremental improvements because changes made to the files can easily be tracked. A git project is called a “repo” (repository) and the “master” Carob repo is hosted on github.

To contribute to the Carob repo (and to other github based projects) you need to understand a few concepts and commands.

The first thing you need to do is create an account on github. Once you have that, you can fork the Carob repo to your account. A git fork is a copy of a git repo that allows the new owner to make changes without affecting the original project.

fork

To fork the Carob repo, navigate to the Carob github page, and click on the Fork button and chose your personal account as the target.

The forked repo will then be added to your account on your GitHub. The small text below the repository name confirms this is a fork.

Now you can clone (make a copy of) your branch to your computer so that you can make changes. You can change your branch as you please, as it does not affect the master repo (original project). However, if you want to contribute back to the master repo you should keep these changes to a minimum. But there is no need to worry too much about that, as you can simply delete your fork and create a new one if things went wrong.

After you make changes you need to add and/or commit your work and then push these from your computer to the version of your branch that is hosed on github. You can do these things with different tools. Here are instructions for the `command line<./git/commandline.html">`__ , GitHub Desktop and RStudio.

pull-request

Now that you have made changes to your fork of the Carob repo that you would like to contribute to the project, you can open a “pull request” (often abbreviated to “PR”). Before you do that, you need to assure that your fork is in sync with the master repo reagro/carob. This is because the master will likely also have changed in the meantime. It is imperative to assure that any differences between your fork and the master are only the changes (e.g. a new file) that you want to make.

It is important to sync regularly to avoid “conflicts” in which you made changes to a file that was also changed by someone else. The changes of this happening are small, and conflicts can be resolved, but it is best to avoid them.

Once your repo is synced with the master, you can contribute your commit by clicking on the contribute button.

Write a message in the box describing your contribution, and click on create a pull request.

See this document for a more fundamental description of making pull-requests, including the command line approach.